Users must subscribe to your app before you can send them notifications. If you try to send a message to an unsubscribed user, it will not be delivered.Setting up user subscriptions: See our User Management guide for implementation details.
Prerequisites
Before sending messages, ensure you have completed these steps:- Authentication Setup: Have your API key ready (see the Authentication guide if you need to set this up)
- App Registration: Your app must be registered with Dialect
- User Subscriptions: Ensure your users have subscribed to receive notifications from your app
Message Delivery Overview
Dialect’s REST API provides flexible delivery options:- Channel Selection: Messages are sent according to user channel preferences (IN_APP, email, Telegram, push)
- User Targeting: Send to individual users, groups, or broadcast to all subscribers
- Rich Content: Support for titles, actions, images, and formatted content
- Topic-Based: Optional targeting based on notification types/topics
How It Works
Step 1: Basic Message Sending
Send to a Single User
Send a notification to a specific user’s wallet address. This is the most common messaging pattern. API Reference:POST /v2/{appId}/send
- curl
- TypeScript
Send to Multiple Users
Send the same notification to multiple specific users in a single request. This is more efficient than making individual API calls and supports up to 10,000 wallet addresses. API Reference:POST /v2/{appId}/send
- curl
- TypeScript
Broadcast to All Users
Send notifications to all users subscribed to your app by using theall-subscribers
recipient type.
- curl
- TypeScript
Send Personalized Messages to Multiple Users
Send different notification content to multiple users using the batch endpoint. This is ideal for personalized alerts like individual portfolio updates, transaction confirmations, or customized recommendations. Supports up to 500 personalized messages per batch. API Reference:POST /v2/{appId}/send-batch
- curl
- TypeScript
When to use send-batch vs send:
- Use
/send
with"subscribers"
type when sending the same message to multiple users (up to 10,000) - Use
/send-batch
when sending different personalized content to multiple users (up to 500)
Step 2: Channel-Specific Delivery
Target Email and Telegram
Control which channels receive your message by specifying thechannels
array. Note that IN_APP notifications are delivered automatically when included, so you can add other channels as needed.
- curl
- TypeScript
Rich HTML Content for Email
When sending to email channels, you can use HTML formatting for rich content presentation.- curl
- TypeScript
Step 3: Interactive & Rich Messages
Actionable Notifications
Add action buttons to your notifications that allow users to take immediate action. Currently supports up to 3 action buttons that can direct users to websites.- curl
- TypeScript
Messages with Images
Include images in your notifications using publicly accessible URLs. Images are supported for IN_APP and EMAIL channels.- curl
- TypeScript
Step 4: Topic-Based Messaging
Send to Topic Subscribers
If you’ve configured notification topics, you can send targeted messages to users who have subscribed to specific categories.- curl
- TypeScript
Step 5: Advanced Operations
Get Your Subscribers
Retrieve a list of all wallet addresses currently subscribed to your application: API Reference:GET /v2/{appId}/subscribers
- curl
- TypeScript
offset
: Pagination offset (default: 0)limit
: Pagination limit (default: 1000, max: 10000)
- curl
- TypeScript
Message Examples by Use Case
Welcome Message
Transaction Alert
Security Alert
Price Alert
Error Handling
Common Response Codes
202 Accepted: Message sent successfullyError Handling Example
Best Practices
💡 Message Design Tips:- Keep titles concise and descriptive (especially important for email subjects)
- Structure longer messages with clear sections
- Always include clear calls-to-action when appropriate
- Use HTML formatting only for email channels
- Test your messages across different channels (IN_APP vs email vs Telegram)
- Implement proper error handling and retry logic for critical notifications
- Use batch sending for multiple recipients to improve efficiency
- Consider user time zones when sending time-sensitive notifications
- Respect user preferences and subscription settings
- Provide context in your messages - users should understand why they’re receiving the notification
- Use topic-based messaging to ensure relevance
- Make action buttons clear and valuable