Conversation API

18 minutes of reading

1. Introduction #

Bot integration is an optional feature and it can be defined via billing subscription plan. With this feature the automatic responses to the messages received in the Easy Dialog app, can be generated with Botpress, some Custom third-party API or OpenAI-compatible chat completion API. So, when someone sends a message to the Easy Dialog app, if Bot is enabled, they will receive a message back generated by the Bot.

The Conversation API accounts can be managed after selecting the “Conversation API” option from the “Settings” > “Integration” section of the Business Messenger app.

2. Bot Integration Type #

For the Conversation Account, Integration type can be selected to be Botpress, Custom or AI.

2.1 Botpress Adapter #

Botpress is an open-source platform for developers to build chatbots. For integration with the Business Messenger app, you need to host Botpress v12 on your own, or you can contact our Sales team for more information about a hosted version on our servers.

2.1.1 Configuration for Botpress API #

In order to configure Botpress in the Business Messenger app, the following data are needed:

Bot ID – The bot ID is given on the botpress dashboard. The bot name is not accepted as a valid value.
Botpress URL – The URL for the botpress server, e.g. http://botpress.com:3000.
Credentials Email – The email that is used for the botpress account.
Credentials Password – The password for the botpress account.

2.1.2 Botpress Inbound #

The Business Messenger Conversation API will send the following inbound messages to Botpress Converse API in the following format:

Message Type	event.type or event.payload.type	Content Field	Content Description
Text	text	event.payload.text	Message text.
Picture	image	event.payload.image	URL to the image file.
Audio	audio	event.payload.audio	URL to the audio file.
Video	video	event.payload.video	URL to the video file.
File	file	event.payload.file	URL to the file.
Location	location	event.payload.latitude, event.payload.longitude	Latitude and longitude numbers.
Response	response	event.payload.response, event.payload.responseData	`event.payload.response` will contain response type: e.g. question, order, form `event.payload.responseData` will contain actual response data as javascript object.

2.1.3 Botpress Outbound #

All types of the Botpress outbound messages are supported: text, image, single choice messages, card, carousel, file, video, audio, location, etc.

Also, multi-message responses are supported.

2.2 Custom Adapter #

Integrating the Conversation API via Custom adapter provides most flexibility for automatic message responses while being very simple to understand and implement. The implementer is expected to develop a single webhook endpoint available at a public URL. It will receive all inbound messages as requests and it is expected to respond in the specific format to those requests, which will be processed and forwarded to the end users as automatic message responses.

2.2.1 Configuration for Custom API #

The following data are needed:

Webhook URL – The webhook URL to which POST request will be sent with an inbound message.
Signature – Signature key is a random string for signing and validating requests (it is preferred to be UUIDv4, but it can be anything).

Debug mode can be activated by selecting the “Debug Mode” checkbox located at the bottom of the configuration form in the Custom Adapter settings. It enables error reporting requests to help in identifying issues in bot responses. More details about Debug mode can be found in 2.2.4 Debug Mode section.

For Custom API a lot of different message types are supported for inbound and outbound traffic. Each inbound request data (what we send to the Custom API) is signed with the signature key from a configuration with sha512 algorithm which is base64 encoded. The signature key will be in the request header field [X-BM-Signature]. The exact function for signing a request is this:

return base64_encode(hash_hmac('sha512', $jsonRequestData, $signature, true));

This way it is possible to check authenticity of the request.

2.2.2 Inbound Requests #

These requests represent what we send to Custom webhook endpoint. The base format for the request is presented below:

{
  "serviceUuid": "d354fe67-87f2-4438-959f-65fde4622040",
  "dialogUuid": "237a9b91-f7dd-4a49-939d-af95820d84a0",
  "channel": "telegram",
  "message": {
    "from": "1014279770",
    "providerMsgID": "497",
    "allowedChannels": [
      "telegram"
    ],
    "body": {
      "textMessage": {
        "content": "Hello"
      }
    }
  },
  "contact": {
    "uuid": "ae77ee16-1f77-4617-a5f0-c17b5483b730",
    "mobile": "+4163456568",
    "first_name": "John",
    "last_name": "Smith",
    "language": "en",
    "birthday": "1991-09-24",
    "channel_identifiers": "1014279770,+4163456568",
    "channel_names": "telegram,whatsapp",
    "channel_opt_statuses": "in,in",
    "created_dt": "2023-01-04T15:07:09Z",
    "opt_status": "in",
    "status": "active"
  }
}

The request contains the following details:

serviceUuid – UUID for the Business Messenger account.
dialogUuid – Internal UUID for Easy Dialog conversation. It can be used to differentiate the conversations.
channel – From which channel the message arrived. Possible channels: SMS, Viber, Telegram, Facebook, Instagram, RCS (RBM).
message – Main JSON object with message data. See Message object definition below.
contact – Object with a contact data from the Business Messenger app. Contact fields without value might be omitted or presented with null value. See Contact object definition below.

2.2.3 Webhook Response #

After the request is received and data is processed, in the response we expect an outbound message that we will send to the user who sent the message. Format supports multiple messages in one response.

JSON examples of a response are presented below:

1. An example of a response with a picture message:

{
  "messages": [
    {
      "body": {
        "textMessage": {
          "content": "Hello John Doe"
        }
      }
    },
    {
      "body": {
        "pictureMessage": {
          "url": "https://www.apple.com/v/macbook-air/n/images/overview/hero_endframe__ea0qze85eyi6_large.jpg",
          "name": "MacBook Air"
        }
      }
    }
  ]
}

2. An example of a response with a location and a suggestion messages:

{
  "messages": [
    {
      "body": {
        "textMessage": {
          "content": "Hello John Doe"
        }
      }
    },
    {
      "body": {
        "locationMessage": {
          "latitude": 37.3348,
          "longitude": -122.0089,
          "text": "Apple Park",
          "url": "https://www.google.com/maps/place/Apple+Park/@37.3346438,-122.011166,17z/data=!3m1!4b1!4m5!3m4!1s0x808fb596e9e188fd:0x3b0d8391510688f0!8m2!3d37.3346438!4d-122.008972"
        },
        "suggestionsMessage": {
          "suggestions": [
            {
              "text": "Website",
              "openUrl": {
                "url": "https://www.apple.com"
              }
            }
          ]
        }
      }
    }
  ]
}

3. An example of a response with a card carousel message:

{
  "messages": [
    {
      "body": {
        "textMessage": {
          "content": "Hello John Doe"
        }
      }
    },
    {
      "body": {
        "cardCarouselMessage": {
          "content": [
            {
              "media": {
                "url": "https://www.apple.com/v/macbook-air/n/images/overview/hero_endframe__ea0qze85eyi6_large.jpg"
              },
              "title": "MacBook Air",
              "description": "Power. It’s in the Air.",
              "suggestions": [
                {
                  "text": "Visit",
                  "openUrl": {
                    "url": "https://www.apple.com/macbook-air/"
                  }
                }
              ]
            },
            {
              "media": {
                "url": "https://www.apple.com/v/apple-watch-series-7/d/images/overview/hero/hero_intro_hardware__fg5bn8mfky2q_large.jpg"
              },
              "title": "Apple Watch Series 7",
              "description": "Full screen ahead.",
              "suggestions": [
                {
                  "text": "Visit",
                  "openUrl": {
                    "url": "https://www.apple.com/apple-watch-series-7/"
                  }
                }
              ]
            }
          ]
        }
      }
    }
  ]
}

4. An example of a response with a picture message:

{
  "messages": [
    {
      "body": {
        "textMessage": {
          "content": "Hello John Doe"
        }
      }
    },
    {
      "body": {
        "pictureMessage": {
          "url": "https://www.apple.com/v/macbook-air/n/images/overview/hero_endframe__ea0qze85eyi6_large.jpg",
          "name": "MacBook Air"
        }
      }
    }
  ]
}

Webhook Response contains the following details:

messages – The main array of objects for the responses. It can be an empty array, or there can be more then one message. Each item in the array represents a separate message.
messages.body – Each message must have a body object with the actual Message object.

The received response we’ll transform to one or more messages and send back as a response message. All messages will be presented in the Easy Dialog app conversations.

Custom Webhook endpoint, described in 4. Method Details section of this document, is used for the integration of external systems regarding Inbound and Outbound Traffic. This endpoint should understand our payloads.

2.2.4 Debug Mode #

When debug mode is enabled, in case your response gets rejected by our validation system, the webhook endpoint will get another request containing just error information. You can use this info for troubleshooting. You are not expected to return any specific content on this request. You can return an empty string.

JSON example of an error reporting request is given below.

{
  "debugInfo": {
    "error": "Invalid webhook response Code: no_content, message: No content in message body, description: Message body does not include required content, items: [API ERR ITEM=[message:no_content:Message body does not include required content]]",
    "request": "{\"serviceUuid\":\"d354fe67-87f2-4438-959f-65fde4622044\",\"dialogUuid\":\"237a9b91-f7dd-4a49-939d-af95820d84af\",\"channel\":\"telegram\",\"message\":{\"from\":\"1014279771\",\"providerMsgID\":\"570\",\"allowedChannels\":[\"telegram\"],\"body\":{\"textMessage\":{\"content\":\"bot-error\"}}},\"contact\":{\"birthday\":\"1988-08-06\",\"title\":\"?️\",\"uuid\":\"ae77ee16-1f77-4617-a5f0-c17b5483b736\"}}",
    "response": "{\"messages\":[{\"body\":{\"textMessage\":{\"contentX\":\"Hello\"}}}]}"
  }
}

2.3 AI Adapter #

By selecting the “AI” option for the “Integration Type”, you can select an AI model provider, or you can use a custom URL of an API endpoint, that accepts OpenAI-compatible chat completion requests (Google, Anthropic, xAI (AKA Grok), Mistral AI, DeepSeek, etc.).

In order to configure Bot integration with an AI provider in the Business Messenger app, you have to create an account on an AI provider platform and generate an API key.

Note: Your secret API keys will not be displayed again after you generate them. Store your secret API keys in a secure, private location.

2.3.1 Configuration for AI Adapter #

In the Business Messenger app, visit Settings > Integration > Conversation API page , and click “Add Conversation Account” button.

The following actions are needed:

In the opened window, add Name and Description for the Conversation account. For Integration Type, select the “AI” option.
The Base URL select field allows you to select an AI provider from the list, or you can specify a custom URL of an API endpoint, that accepts OpenAI-compatible chat completion requests. The list includes Google, Anthropic, xAI (AKA Grok), Mistral AI, DeepSeek, etc.
Fill in your API Key for the selected AI provider. After you sign up for an account with an AI provider, you have to generate your API key on the AI provider’s platform.
Note: Store your API keys in a secure private location.
Select a Model. The AI models are predefined sets with different capabilities and price points. Detailed information please find on the AI provider’s pages.For example, more info about OpenAI models you can find on OpenAI Models page.
Custom Instructions – you can set optionally custom instructions text so that you can tailor AI to better meet your needs. Custom instructions allow you to add preferences or requirements that you would like AI to consider when generating its responses. Note that using “Custom Instructions” parameter, increases billable token usage.
History – AI does not have built-in memory of previous conversation replies. The way to simulate this, is to resend a certain number of recent replies on each new request. Note that using “History” parameter, increases billable token usage.
Set the Max Tokens – the maximum number of tokens that can be generated in the chat completion. This value can be used to control costs for text generated via API. AI models process text by breaking it down into tokens, which are common sequences of characters found in text. The exact limit of tokens varies by model.
Set the Temperature parameter. It controls randomness: Lowering results in less random completions. As the temperature approaches zero, the model will become deterministic and repetitive.

With these settings saved, the AI bot can be enabled for sending responses in the Easy Dialog app.

3. Method Overview #

Endpoint for Custom adapter for the Conversation API.

POST/your-webhook-endpoint

Custom adapter for the Conversation API.

4. Method Details #

Endpoint for Custom adapter for the Conversation API.

4.1 Custom Webhook Endpoint #

Integrating the Conversation API via Custom adapter provides most flexibility for automatic message responses.

It is expected from a customer to develop a single webhook endpoint available at a public URL. This endpoint should understand our payloads. The endpoint will receive all inbound messages as requests and it should respond in the specific format to those requests, which will be processed and forwarded to the end users as automatic message responses.

Please note that event though we use common payload format, each channel has its own characteristics, features and limitations. Please find details in 6. Channels Features section of this document. When responding, you can either use common denominator of features across all expected channels, or customize your response based on the specific channel of the current request.

POST/your-webhook-endpoint

Custom adapter for the Conversation API.

Method Overview #

The method creates a webhook.

Parameters #

Name	Type	Description
body (required)	object (body)	Request data.

Request body object example

{
  "serviceUuid": "d354fe67-87f2-4438-959f-65fde4622040",
  "dialogUuid": "237a9b91-f7dd-4a49-939d-af95820d84a0",
  "channel": "telegram",
  "message": {
    "from": "1014279770",
    "providerMsgID": "497",
    "allowedChannels": [
      "telegram"
    ],
    "body": {
      "textMessage": {
        "content": "Hello"
      }
    }
  },
  "contact": {
    "uuid": "ae77ee16-1f77-4617-a5f0-c17b5483b730",
    "mobile": "+4163456568",
    "first_name": "John",
    "last_name": "Smith",
    "language": "en",
    "birthday": "1991-09-24",
    "channel_identifiers": "1014279770,+4163456568",
    "channel_names": "telegram,whatsapp",
    "channel_opt_statuses": "in,in",
    "created_dt": "2023-01-04T15:07:09Z",
    "opt_status": "in",
    "status": "active"
  }
}

Responses #

Code	Description	Links
200	Webhook created.	No links.

Expected Response Example #

Your endpoint is expected to respond to the webhook request with a list of messages if you intend to reply. This is a response payload example which will return 2 messages: a text and a picture message.

{
  "messages": [
    {
      "body": {
        "textMessage": {
          "content": "Hello"
        }
      }
    },
    {
      "body": {
        "pictureMessage": {
          "url": "https://www.apple.com/v/macbook-air/s/images/overview/design/lifestyle-gallery/design_portability_1__gfw34rh367u6_large.jpg",
          "name": "MacBook Air"
        }
      }
    }
  ]
}

5. Data Models #

Data Models define the structure of a JSON document and describe the data related to the Custom webhook endpoint.

5.1 Webhook Request Payload #

WebhookRequestPayload object properties:

Name	Type	Description
serviceUuid	string	The Business Messenger app account UUID.
dialogUuid	string	The Easy Dialog conversation UUID.
channel	string	From which channel the message was arrived. Possible values: SMS, Viber, Telegram, Facebook, Instagram, RCS (RBM).
message	object	The message data. Message object.
contact	object	The Business Messenger app’s contact data. Contact object.

JSON Example #

{
  "serviceUuid": "d354fe67-87f2-4438-959f-65fde4622040",
  "dialogUuid": "237a9b91-f7dd-4a49-939d-af95820d84a0",
  "channel": "telegram",
  "message": {
    "from": "1014279770",
    "providerMsgID": "497",
    "allowedChannels": [
      "telegram"
    ],
    "body": {
      "textMessage": {
        "content": "Hello"
      }
    }
  },
  "contact": {
    "uuid": "ae77ee16-1f77-4617-a5f0-c17b5483b730",
    "mobile": "+4163456568",
    "first_name": "John",
    "last_name": "Smith",
    "language": "en",
    "birthday": "1991-09-24",
    "channel_identifiers": "1014279770,+4163456568",
    "channel_names": "telegram,whatsapp",
    "channel_opt_statuses": "in,in",
    "created_dt": "2023-01-04T15:07:09Z",
    "opt_status": "in",
    "status": "active"
  }
}

5.2 Webhook Response #

WebhookResponse object properties:

Name	Type	Description
messages	array	It can contain TextMessage and SuggestionsMessage, and one of: PictureMessage object, VideoMessage object, AudioMessage object, FileMessage object, FileListMessage object, LocationMessage object, ContactMessage object.

JSON Example #

{
  "messages": [
    {
      "body": {
        "textMessage": {
          "content": "Hello John Doe"
        }
      }
    },
    {
      "body": {
        "locationMessage": {
          "latitude": 37.3348,
          "longitude": -122.0089,
          "text": "Apple Park",
          "url": "https://www.google.com/maps/place/Apple+Park/@37.3346438,-122.011166,17z/data=!3m1!4b1!4m5!3m4!1s0x808fb596e9e188fd:0x3b0d8391510688f0!8m2!3d37.3346438!4d-122.008972"
        },
        "suggestionsMessage": {
          "suggestions": [
            {
              "text": "Website",
              "openUrl": {
                "url": "https://www.apple.com"
              }
            }
          ]
        }
      }
    }
  ]
}

5.3 Message #

Message object properties:

Name	Type	Description
to	array	An array of destinations. MessageDestination object.
from	string	Sender ID received from a channel.
providerMsgID	string	Message ID received from a channel.
allowedChannels	array	An array of allowed channels. Possible values: sms, facebook, viber, telegram, instagram, gbm.
custom	array	An array of custom values.
body	object	The message body. Possible values: TextMessage object, PictureMessage object, VideoMessage object, AudioMessage object, FileMessage object, FileListMessage object, LocationMessage object, ContactMessage object, SuggestionsMessage object, CardMessage object, CardCarouselMessage object.

5.4 Text Message #

TextMessage object properties:

Name	Type	Description
content	string	The message content.

JSON Example #

{
  "textMessage": {
    "content": "Hello"
  }
}

5.5 Picture Message #

PictureMessage object properties:

Name	Type	Description
name	string	File name.
url	string	HTTP URL for the media file.
mimeType	string	File MIME type.
size	integer	File size.
thumbnailName	string	Thumbnail file name.
thumbnailUrl	string	HTTP URL for the thumbnail file.
thumbnailMimeType	string	Thumbnail file MIME type.
thumbnailSize	integer	Thumbnail file size.

JSON Example #

{
  "pictureMessage": {
    "url": "https://www.apple.com/v/macbook-air/s/images/overview/design/lifestyle-gallery/design_portability_1__gfw34rh367u6_large.jpg",
    "name": "MacBook Air"
  }
}

5.6 Video Message #

VideoMessage object properties:

Name	Type	Description
name	string	File name.
url	string	HTTP URL for the media file.
mimeType	string	File MIME type.
size	integer	File size.
playingLength	integer	File playing length.
thumbnailName	string	Thumbnail file name.
thumbnailUrl	string	HTTP URL for the thumbnail file.
thumbnailMimeType	string	Thumbnail file MIME type.
thumbnailSize	integer	Thumbnail file size.

JSON Example #

{
  "videoMessage": {
    "url": "https://www.apple.com/105/media/us/iphone-13-pro/2021/404b23a8-f9c5-466c-b0e6-3d36705b959d/anim/macro-video/large.mp4",
    "name": "iPhone"
  }
}

5.7 Audio Message #

AudioMessage object properties:

Name	Type	Description
name	string	Audio name.
url	string	HTTP URL for the media file.
mimeType	string	File MIME type.
size	integer	File size.
playingLength	integer	File playing length.

JSON Example #

{
  "audioMessage": {
    "url": "https://staging-assets.sms.es.pro/Audios/nice_tune_MP3_1MG.mp3",
    "name": "Sample Audio"
  }
}

5.8 Media Message #

MediaMessage object properties:

Name	Type	Description
url	string	HTTP URL for the media file.
thumbnailUrl	string	HTTP URL for the thumbnail file.
height	string	Media file height.

5.9 File Message #

FileMessage object properties:

Name	Type	Description
name	string	File name.
url	string	File URL.
mimeType	string	File MIME type.
size	integer	File size.
thumbnailName	string	Thumbnail file name.
thumbnailUrl	string	HTTP URL for the thumbnail file.
thumbnailMimeType	string	Thumbnail file MIME type.
thumbnailSize	integer	Thumbnail file size.
fileType	string	File type.

JSON Example #

{
  "fileMessage": {
    "url": "http://www.africau.edu/images/default/sample.pdf",
    "name": "Sample PDF"
  }
}

5.10 File List Message #

FileListMessage object properties:

Name	Type	Description
text	string	Message text.
files	array	An array of FileMessage objects.

5.11 Location Message #

LocationMessage object properties:

Name	Type	Description
latitude	number	Latitude.
longitude	number	Longitude.
text	string	Location message text.
url	string	Location URL.

JSON Example #

{
  "locationMessage": {
    "latitude": 37.3348,
    "longitude": -122.0089,
    "text": "Apple Park",
    "url": "https://www.google.com/maps/place/Apple+Park/@37.3346438,-122.011166,17z/data=!3m1!4b1!4m5!3m4!1s0x808fb596e9e188fd:0x3b0d8391510688f0!8m2!3d37.3346438!4d-122.008972"
  }
}

5.12 Contact Message #

ContactMessage object properties:

Name	Type	Description
name	string	Contact’s name.
email	string	Contact’s email.
address	string	Contact’s address.
phone	string	Contact’s phone.

JSON Example #

{
  "contactMessage": {
    "firstName": "John",
    "lastName": "Smith",
    "name": "John Smith",
    "phone": "+15550783611",
    "email": "john@example.com",
    "address": "AB 12",
    "country": "US",
    "language": "en"
  }
}

5.13 Suggestions Message #

SuggestionsMessage object properties:

Name	Type	Description
suggestions	array	An array of Suggestion object.

5.14 Suggestion #

Suggestion object properties:

Name	Type	Description
text	string	Text to display for the suggestion.
postback	string	Postback data.
replyWith	object	ReplyWithSuggestion object.
openUrl	object	OpenUrlSuggestion object.
dialNumber	object	DialNumberSuggestion object.
composeMessage	object	ComposeMessageSuggestion object.
showMapLocation	object	ShowMapLocationSuggestion object.
createCalendarEvent	object	CreateCalendarEventSuggestion object.

5.15 Reply With Suggestion #

ReplyWithSuggestion object properties:

Name	Type	Description
postback	string	The message postback.

5.16 Open Url Suggestion #

OpenUrlSuggestion object properties:

Name	Type	Description
url	string	Open website.

5.17 Dial Number Suggestion #

DialNumberSuggestion object properties:

Name	Type	Description
number	string	A number.

5.18 Compose Message Suggestion #

ComposeMessageSuggestion object properties:

Name	Type	Description
number	string	A number.
test	string	A message text.

5.19 Show Map Location Suggestion #

ShowMapLocationSuggestion object properties:

Name	Type	Description
latitude	number	A location latitude.
longitude	number	A location longitude.
label	string	Label.
url	string	Google maps URL.

5.20 Create Calendar Event Suggestion #

CreateCalendarEventSuggestion object properties:

Name	Type	Description
title	string	Title.
description	string	Description.
start	string	Start of the event.
end	string	End of the event.

5.21 Card Message #

CardMessage object properties:

Name	Type	Description
layout	object	Card layout.
content	array	CardMessageContent object.

JSON Example #

{
  "cardMessage": {
    "content": {
      "media": {
        "url": "https://www.apple.com/v/macbook-air/s/images/overview/design/lifestyle-gallery/design_portability_1__gfw34rh367u6_large.jpg"
      },
      "title": "MacBook Air",
      "description": "Power. It’s in the Air.",
      "suggestions": [
        {
          "text": "Cool",
          "replyWith": {
            "postback": "cool"
          }
        },
        {
          "text": "Lame",
          "replyWith": {
            "postback": "lame"
          }
        }
      ]
    }
  }
}

5.22 Card Carousel Message #

CardCarouselMessage object properties:

Name	Type	Description
layout	object	Message layout.
content	array	An array of CardMessageContent objects.

JSON Example #

{
  "cardCarouselMessage": {
    "content": [
      {
        "media": {
          "url": "https://www.apple.com/v/macbook-air/s/images/overview/design/lifestyle-gallery/design_portability_1__gfw34rh367u6_large.jpg"
        },
        "title": "MacBook Air",
        "description": "Power. It’s in the Air.",
        "suggestions": [
          {
            "text": "Visit",
            "openUrl": {
              "url": "https://www.apple.com/macbook-air/"
            }
          }
        ]
      },
      {
        "media": {
          "url": "https://www.apple.com/v/apple-watch-series-7/d/images/overview/hero/hero_intro_hardware__fg5bn8mfky2q_large.jpg"
        },
        "title": "Apple Watch Series 7",
        "description": "Full screen ahead.",
        "suggestions": [
          {
            "text": "Visit",
            "openUrl": {
              "url": "https://www.apple.com/apple-watch-series-7/"
            }
          }
        ]
      }
    ]
  }
}

5.23 Card Message Content #

CardMessageContent object properties:

Name	Type	Description
media	object	MediaMessage object.
title	string	Card message title.
description	string	Card message description.
suggestions	array	An array of possible values: ReplyWithSuggestion object, OpenUrlSuggestion, DialNumberSuggestion object, ComposeMessageSuggestion object, ShowMapLocationSuggestion object, CreateCalendarEventSuggestion object.

5.24 Message Destination #

MessageDestination object properties:

Name	Type	Description
number	string	Destination as a number.
alias	string	Destination as an alias.

5.25 Contact #

Contact object properties:

Note: Not all Contact fields are required. Contact fields without value might be omitted or presented with null value.

Name	Type	Description
uuid	string	Contact UUID.
created_dt	string($date‑time)	Contact creation date and time, in RFC 3339 format.
updated_dt	string($date‑time)	Date and time when a contact is updated, in RFC 3339 format.
opt_status	string	Opt status. Available values: in, out.
opt_status_webpush	string	Opt status webpush. Available values: in, out.
first_name	string	Contact’s first name.
last_name	string	Contact’s last name.
second_name	string	Contact’s second name.
nick_name	string	Contact’s nick name.
gender	string	Gender of a contact, male or female.
birthday	string	Birthday of a contact, in YYYY-MM-DD format.
salutation	string	Salutation.
title	string	Title.
language	string	Language.
nationality	string	Nationality,
mobile	string	Mobile number.
email	string	Email address.
phone	string	Phone number.
fax	string	Fax number.
address	string	Address.
zip	string	Postal code.
city	string	City.
region	string	Region.
country	string	Country.
b_company	string	Company.
b_mobile	string	Business mobile number.
b_email	string	Business email address.
b_fax	string	Business fax number.
b_phone	string	Business phone number.
b_address	string	Business address.
b_zip	string	Business address postal code.
b_city	string	Business address city.
b_region	string	Business address region.
b_country	string	Business address country.
b_job_title	string	Job title.
b_department	string	Department.
b_reception_code	string	Reception code.
list_uuid	string	List UUID.
channel_names	string	Channel names, in CSV format.
channel_opt_status	string	Channel opt status in CSV format.

6. Channels Features #

Each channel has its own characteristics, features and limitations. When responding, you can either use the common set of features supported across all channels, or tailor your response based on the specific channel of the current request.

6.1 Channels and Message Types #

Depending on the channel used, some message types may not be supported by the Conversation API. The table below shows which message types are compatible with which channel.

Message Type / Channel	SMS	WhatsApp	RCS	Telegram	Viber	Facebook	Instagram	Email	Web Push
Text Message	✓	✓	✓	✓	✓	✓	✓	–	–
Picture	–	✓	✓	✓	✓	✓	✓	–	–
Audio	–	✓	✓	✓	✓ ^*	✓	✓ ^*	–	–
Video	–	✓	✓	✓	✓	✓	✓ ^*	–	–
File	–	✓	✓ ^*	✓	✓	✓	✓ ^*	–	–
Card	–	✓	✓	✓ ^*	✓	✓	✓	–	–
Carousel	–	–	✓	✓ ^*	✓	✓	✓	–	–
Contact	–	✓	✓ ^*	✓	✓	✓ ^*	✓ ^*	–	–
Location	–	✓	✓ ^*	✓	✓	✓ ^*	✓ ^*	–	–
Template	–	✓	–	–	–	–	–	–	–

* This message type is not natively supported by the channel, but it’s rather emulated using other message types.

6.2 Channels and Button Types #

Depending on the channel used, some button types may not be supported. The table below shows which button types are compatible with which channel.

Button Type / Channel	SMS	WhatsApp	RCS	Telegram	Viber	Facebook	Instagram	Email	Web Push
Reply	–	✓	✓	✓ ^[2]	✓	✓	✓	–	–
URL	–	✓ ^[1]	✓	✓ ^[3]	✓	✓	✓	–	–
Dial	–	–	✓	–	–	✓	–	–	–
Compose	–	–	–	–	–	–	–	–	–
Location	–	–	✓	✓ ^[4]	✓ ^[4]	✓ ^[4]	✓ ^[4]	–	–
Calendar	–	–	✓	–	–	–	–	–	–

^[1] only for templates, 2 buttons max.
^[2] not possible in carousel.
^[3] emulated in carousel.
^[4] emulated as URL.

6.3 Channels Features Limitation #

The table below shows the channels features limitation regarding maximum text length, maximum file size, supported file types, etc.

Feature / Channel	SMS	WhatsApp	RCS	Telegram	Viber	Facebook	Instagram	Email	Web Push
Max Text Length	918 (GSM characters) or 402 (UCS characters)	4096only 1024 if buttons are present	3072	4096	4096	2000only 640 if buttons are present	1000	–	–
Max Image Size (bytes)	–	26214400	104857600	5242880	3145728	26214400	26214400	–	–
Max Thumb Image Size (bytes)	–	–	102400	204800	102400	–	–	–	–
Max Video Size (bytes)	–	16777216	104857600	20971520	27262976	26214400	26214400	–	–
Max Audio Size (bytes)	–	16777216	104857600	20971520	52428800	26214400	26214400	–	–
Max File Size (bytes)	–	104857600	104857600	20971520	52428800	26214400	26214400	–	–
Max Card File (img) Size (bytes)	–	5242880	104857600	5242880	512000	26214400	26214400	–	–
Max Buttons in a Card	–	3	4	–	2	3	3	–	–
Max Card Title Length	–	60	200	–	256	80	80	–	–
Max Card Description Length	–	1024	2000	1024 title+desc+btn txt	512	80	80	–	–
Max Cards in Carousel	–	–	11	10	6	10	10	–	–
Max Button Caption Length	–	20	25	–	50	20	20	–	–
Supported Image File Types	–	png (image/png)jpg (image/jpg)jpeg (image/jpeg)	png (image/png)jpg (image/jpg)jpeg (image/jpeg)gif (image/gif)	png (image/png)jpg (image/jpg)jpeg (image/jpeg)	png (image/png)jpg (image/jpg)jpeg (image/jpeg)gif (image/gif)	png (image/png)jpg (image/jpg)jpeg (image/jpeg)gif (image/gif)	png (image/png)jpg (image/jpg)jpeg (image/jpeg)gif (image/gif)	–	–
Supported Video File Types	–	mp4 (video/mp4)3gp (video/3gp)

What are your Feelings

Still having problems? How can we help?

Updated on 9 de October de 2025

1. Introduction #

2. Bot Integration Type #

2.1 Botpress Adapter #

2.1.1 Configuration for Botpress API #

2.1.2 Botpress Inbound #

2.1.3 Botpress Outbound #

2.2 Custom Adapter #

2.2.1 Configuration for Custom API #

2.2.2 Inbound Requests #

2.2.3 Webhook Response #

2.2.4 Debug Mode #

2.3 AI Adapter #

2.3.1 Configuration for AI Adapter #

3. Method Overview #

4. Method Details #

4.1 Custom Webhook Endpoint #

Method Overview #

Parameters #

Responses #

Expected Response Example #

5. Data Models #

5.1 Webhook Request Payload #

JSON Example #

5.2 Webhook Response #

JSON Example #

5.3 Message #

5.4 Text Message #

JSON Example #

5.5 Picture Message #

JSON Example #

5.6 Video Message #

JSON Example #

5.7 Audio Message #

JSON Example #

5.8 Media Message #

5.9 File Message #

JSON Example #

5.10 File List Message #

5.11 Location Message #

JSON Example #

5.12 Contact Message #

JSON Example #

5.13 Suggestions Message #

5.14 Suggestion #

5.15 Reply With Suggestion #

5.16 Open Url Suggestion #

5.17 Dial Number Suggestion #

5.18 Compose Message Suggestion #

5.19 Show Map Location Suggestion #

5.20 Create Calendar Event Suggestion #

5.21 Card Message #

JSON Example #

5.22 Card Carousel Message #

JSON Example #

5.23 Card Message Content #

5.24 Message Destination #

5.25 Contact #

6. Channels Features #

6.1 Channels and Message Types #

6.2 Channels and Button Types #

6.3 Channels Features Limitation #

What are your Feelings

Share This Article :

How can we help?