Version: 1.0

Conversations API

Overview

Welcome to the Conversations API, your gateway to seamless customer engagement across multiple channels!

With this powerful API, you can connect with your customers through popular platforms like WhatsApp, Telegram, Apple Messages for Business,Viber Business Messages.

By simplifying communication across various channels, the Conversations API empowers you to provide exceptional customer experiences.

Postman

To explore our API endpoints interactively and make requests easily, you can access our Postman public collection.

Authentication

To access the features of the Conversations API, you need to authenticate your requests using an API token.

Follow these steps to get started:

Generate a unique API token through our intuitive client portal.
Include the generated token in the Authorization header of every API request you make.

Here's how to structure the header:

Header	Description	Example
Authorization	Your API token	`Bearer <API_TOKEN>`

Responses and Errors

Conversations API uses standard HTTP status code to indicate the outcome of a request. Below is a non-exhaustive list of the common status codes for your reference.

Status code	Description
200	successful request
400	bad request
401	Unauthorized access
404	Resource not found
5xx	something went wrong on our end

When requests are erroneous, the API will respond with a JSON body in the following format:

{
  "id":  <id>,
  "receivedTime":  <receivedTime>,
  "code":  <errorCode>,
  "message": "<errorMessage>"
}

Responses error codes are detailed below.

Http Status Code	Code	Message	Resolution
400	4000	Validation error	Check request body structure and ensure all required fields are present
401	4001	API Token is not valid	Verify your API token and regenerate if needed
400	4002	The user has unsubscribed	Remove contact from campaign or wait for user to re-subscribe
400	4003	Your balance is not sufficient for this transaction	Add credits to your account balance
400	4004	Missing parameters	Add missing required fields (type, to, content, channel)
400	4005	Parameters are invalid	Check parameter formats, lengths, and channel compatibility (see Supported Features section)
400	4006	Not allowed to send free-form messages	Use approved templates (required for WhatsApp initial contact) or check channel restrictions
400	4007	Channel is not activated	Activate the channel in your account settings
400	4010	Tag not found	Verify the tag ID exists in your account
400	4011	Tag already exists	Use a different tag name or update the existing tag
400	4020	Contact not found	Verify the contact ID exists in your account
400	4021	failover timeoutSeconds param illegal	Ensure timeoutSeconds value is within valid range
400	4022	failover channel max size	Reduce the number of failover channels in the chain
400	4023	failover channel duplicate	Remove duplicate channels from failover configuration
400	4024	Template not found	Verify the template ID and check approval status in your account
400	4025	Template validate error:	Check template parameters and format against template definition
400	4026	WhatsApp Cloud API template error	The Meta (WhatsApp) Cloud API rejected the request. The message field contains the user-facing reason from Meta (e.g. duplicate template name, invalid component).
400	4051	Sender is unavailable	Verify WhatsApp sender is properly configured and available
529	4052	Too Many Requests	The channel has been throttled, please try again later
400	4053	Unsupported Operation	Viber templates do not support modifications
400	4054	Unsupported Operation	Template management for this channel is not currently supported
400	4055	Unsupported Operation	Viber template mismatch
400	4060	Invalid channel user ID	Provide a valid WhatsApp Business-Scoped User ID (BSUID) in `CC.alphanumeric` format, e.g. `US.DDC91135R`
404	4065	Media not found	Verify the media ID exists and was uploaded by your account
400	4066	File too large	Ensure the file does not exceed the 200 MB limit
400	4067	Unsupported file type	Use a supported MIME type (see Media and WhatsApp Media endpoint descriptions)
400	4068	Media download failed	Verify the URL is publicly accessible and returns a valid response
500	4069	Upstream provider unavailable	Retry the request; if the issue persists contact support

Error Handling Best Practices:

Always check the code field in the response to identify the specific error
Log error messages for debugging and monitoring
Handle validation errors (4000-4007, 4010-4011, 4020-4025, 4051, 4060, 4065-4068) by correcting the request parameters before retrying
Monitor account balance to avoid 4003 errors
Refer to the Supported Features section for channel-specific constraints to prevent 4005 errors
Verify failover configuration parameters to avoid 4021-4023 errors

Supported features

The following table list the features supported for each available channel.

AppleMB

Feature	Content Type	Comments
Text	TEXT	Max 4,096 characters
Attachment (Image, Video, Document)	MEDIA	Max 100MB Image, Max 100MB Video, Max 100MB Document
Location	LOCATION	Geographic location sharing
QuickReply	QUICK_REPLY	Max 5 choices
RichLink	RICH_LINK	Rich cards with image, title, description, and link
ListPicker	LIST_PICKER	Multi-item selection lists
TimePicker	TIME_PICKER	Date and time selection interface
ApplePay	APPLEMB_PAY	Apple Pay integration for payments
Authentication	APPLEMB_AUTH	OAuth authentication flows
Form	APPLEMB_FORM	Interactive form elements
Update Message	APPLEMB_UPDATE_MESSAGE	Business Updates message to mobile number
TypingIndicator	TYPING_START / TYPING_END	Show (`TYPING_START`) or dismiss (`TYPING_END`) the typing indicator. No `content` body is required.
Subscribe/Unsubscribe	-	Subscription management
iMessageApps	-	iMessage app integrations

Viber

Feature	Content Type	Comments
Text	TEXT	Max 1,000 UTF-8 characters
Image	MEDIA	Max 200MB - Expected formats: .jpg, .png
Video	MEDIA	Max 200MB
Document	MEDIA	Max 200MB (.doc, .docx, .rtf, .dot, .dotx, .odt, .odf, .txt, .info, .pdf, .xps, .pdax, .eps, .xls, .xlsx, .ods, .fods, .csv, .xlsm, .xltx)
Action Button	BUTTON	Max 6 buttons - Allows businesses to include a single clickable button in a message that can trigger a URL. See `content.button/ViberButton` schema for full details.
List Message (QuickReply)	QUICK_REPLY	List messages provide the opportunity to present users with a question and 2-10 answers from which they can select one. When sent inside an active 24-hour session window, in-session list messages bill at the Viber session rate (type code `802`); otherwise they bill as transactional (type code `801`). The UI style can be controlled via `viber.listMessageUiType` (`1` = classic radio buttons, default; `2` = horizontal buttons, requires Viber client 27.8.2+). See `content.quickReply/ViberListMessage` schema for full details.
Carousel Message	CAROUSEL	Horizontal scrollable cards (multiple cards) - Carousel message type enables businesses to send a single message featuring text and multiple customizable sections (items), each showcasing different products or services along with dedicated media and a call-to-action.
Template	TEMPLATE	Russia/Ukraine templates, Transactional/Promotional templates, Viber templates
OTP Verification Message	-	OTP Verification messages enable brands to authenticate customers by sending them a one-time password (OTP). Contact our support team to have the list of supported languages and templates ID.

WhatsApp

Feature	Content Type	Comments
Text	TEXT	Max 1,024 UTF-8 characters
Image	MEDIA	Max 5MB (.jpg, .png)
Video	MEDIA	Max 16MB (.3gp, .mp4)
Audio	MEDIA	Max 16MB (.aac, .amr, .m4a, .mp3, .ogg)
Document	MEDIA	Max 100MB (.txt, .xls, .xlsx, .doc, .docx, .ppt, .pptx, .pdf)
Location	LOCATION	Geographic location sharing
Interactive Reply buttons	QUICK_REPLY	Quick reply buttons for user responses
Interactive CTA URL button	BUTTON	Max 3 buttons with call-to-action URLs
Template	TEMPLATE	Pre-approved message templates (Marketing, Utility, Authentication, Service) - Required for initial contact
Interactive List	-	Interactive list picker
Sticker	-	Sticker support
Reaction	-	Message reactions

RCS/RBM

Feature	Content Type	Comments
Text	TEXT	Max 3,072 characters
Media (Images, Videos, Documents, Audio)	MEDIA	Max 100MB (.ogx, .pdf, .aac, .mp3, .mpeg, .mp4, .3gp, .jpg, .gif, .png, .h263, .m4v, .m4p, .webm)
Location	LOCATION	Geographic location sharing
Suggested replies	QUICK_REPLY	Quick reply suggestions for user responses
Suggested actions (Buttons)	BUTTON	Max 4 buttons - Dial Number, Text, Location, Web URL
Rich card	CARD	Rich card with single image, title, description, and buttons
Rich card carousel	CAROUSEL	Horizontal scrollable cards (multiple cards)
Subscribe/Unsubscribe	-	Subscription management

Telegram

Feature	Content Type	Comments
Text	TEXT	Max 4,096 characters
Photo	MEDIA	Max 10MB
Video	MEDIA	Max 50MB
Audio	MEDIA	Max 50MB (.mp3, .m4a)
Document	MEDIA	Max 50MB
QuickReply/KeyboardRow	QUICK_REPLY	Quick reply buttons for user responses
Buttons	BUTTON	Action buttons with URLs or postback data

LINE

Feature	Content Type	Comments
Text	TEXT	Max 5,000 characters
Image	MEDIA	Max 10MB (.jpg, .jpeg, .png)
Video	MEDIA	Max 200MB (.mp4)
Audio	MEDIA	Max 200MB (.m4a)
Document	MEDIA	Max 200MB
QuickReply	QUICK_REPLY	Max 13 quick reply buttons for user responses
Subscribe/Unsubscribe	-	Follow/Unfollow events from the LINE Official Account

Notes:

Each channel table above includes a Content Type column showing the API content type value to use in message requests
Features marked with "-" in the Content Type column are channel-specific capabilities that don't map directly to the content type API parameter

Authentication

HTTP: Bearer Auth

Bearer HTTP authentication. Headers-- Authorization: Bearer <TOKEN>

Security Scheme Type:	http
HTTP Authorization Scheme:	bearer
Bearer format:	auth-scheme

Conversations API

Postman

Authentication

Responses and Errors

Supported features

Authentication​

Authentication