Conversation API
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's ChatGPT. So, when someone sends a message to Easy Dialog, if Bot is enabled, they will receive a message back generated by the Bot.
This feature can be enabled or disabled through the Business Messenger application's Settings section. The bot can be set up from the Settings > Conversation API Settings page.
The first option is a checkbox for enabling/disabling Conversation API. If this option is checked, then Bot API type has to be selected.
2. Bot API Type
Bot API type can be selected to be Botpress, Custom or ChatGPT.
2.1 Botpress Adapter
Botpress is an open-source platform for developers to build chatbots. For detailed info about Botpress, please visit Botpress page.
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.
Botpress Inbound
The Botpress API as an inbound message accepts only textual messages. So if it is received as an inbound message for the Easy Dialog anything except textual message, it will be ignored and not passed to the Botpress API.
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 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.
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).
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.
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-65fde4622044",
"dialogUuid": "d5f7d6dd-dc30-451d-a442-a920fdbd6704",
"channel": "viber",
"message": {
"from": "RC32utNr+lEKr/Gij0TYTw==",
"to": [],
"providerMsgID": 5715661107573693000,
"allowedChannels": [
"viber"
],
"custom": [],
"timestamp": {
"date": "2022-06-09 12:26:15.904000",
"timezone_type": 1,
"timezone": "+00:00"
},
"body": {
"textMessage": {
"content": "Hi"
}
}
},
"contact": {
"uuid": "c4609f39-7c46-4bf5-b4f1-b8b0bc05beca",
"created_dt": "2022-06-09 12:20:07",
"updated_dt": "2022-06-09 12:20:07",
"opt_status": "in",
"opt_status_webpush": "out",
"first_name": "John",
"last_name": "Doe",
"second_name": null,
"nick_name": null,
"gender": null,
"birthday": null,
"salutation": null,
"title": null,
"language": "en",
"nationality": null,
"mobile": null,
"email": null,
"phone": null,
"fax": null,
"address": null,
"zip": null,
"city": null,
"region": null,
"country": "RS",
"b_company": null,
"b_mobile": null,
"b_email": null,
"b_fax": null,
"b_phone": null,
"b_address": null,
"b_zip": null,
"b_city": null,
"b_region": null,
"b_country": null,
"b_job_title": null,
"b_department": null,
"b_reception_code": null,
"list_uuid": null,
"channel_names": "viber",
"channel_opt_statuses": "in"
}
}
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, GBM.
message - Main JSON object with message data.
contact - Object with a contact data from the Business Messenger app.
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.3 ChatGPT Adapter
ChatGPT is a type of language model developed by OpenAI. It is designed to respond to natural language queries and generate human-like responses.
For detailed info about ChatGPT, please visit OpenAI ChatGPT page.
Configuration for ChatGPT
In order to configure Bot integration for ChatGPT in the Business Messenger app, the following actions are needed:
-
Create an account on ChatGPT Sign Up page.
-
Generate API key on OpenAI API keys page.
Note: Your secret API keys will not be displayed again after you generate them. Store your secret keys in a secure, private location.
-
Visit Settings > Conversation API page in the Business Messenger app and check the check box to enable Conversation API.
-
For API Type select ChatGPT.
-
Fill in your OpenAI API secret Key.
-
Select a Model. The OpenAI API models are predefined sets with different capabilities and price points. Beside already listed, you can type in any model that it is already exist on the ChatGPT platform. More info about OpenAI ChatGPT models, please find on OpenAI ChatGPT Models page.
You can also create your own custom models by fine-tuning the base models with your training data for your specific use case, e.g. customer support chatbot. More details on how to train your ChatGPT Bot you can find on Fine-tuning the model for ChatGPT page.
-
Set the Max Tokens - the limit for a text. The GPT family of 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. One token is roughly 4 characters for a text in English.
-
Set the Temperature parameter - it controls the randomness of the output. As the temperature approaches zero, the model will be more deterministic.
With these settings saved, the ChatGPT bot can be enabled for sending responses in the Easy Dialog app.
Details about pricing, please find on ChatGPT Pricing page.
3. Method Overview
Endpoint for Custom adapter for Conversation API.
4. Method Details
Endpoint for Custom adapter for Conversation API.
4.1 Create Custom Adapter for Conversation API
Integrating 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.
Method Overview
The method creates a webhook.
Parameters
Name | Type | Description |
---|---|---|
body (required) | object (body) | Request data. |
Request body object example
{
"serviceUuid": "string",
"dialogUuid": "string",
"channel": "string",
"message": {
"from": "string",
"to": [
"string"
],
"providerMsgID": "string",
"allowedChannels": [
"sms"
],
"custom": [
"string"
],
"timestamp": {
"date": "string",
"timezone_type": 0,
"timezone": "string"
},
"body": {
"textMessage": {
"content": "string"
}
}
},
"contact": {
"uuid": "string",
"created_dt": "string",
"updated_dt": "string",
"opt_status": "string",
"opt_status_webpush": "string",
"first_name": "string",
"last_name": "string",
"second_name": "string",
"nick_name": "string",
"gender": "string",
"birthday": "string",
"salutation": "string",
"title": "string",
"language": "string",
"nationality": "string",
"mobile": "string",
"email": "string",
"phone": "string",
"fax": "string",
"address": "string",
"zip": "string",
"city": "string",
"region": "string",
"country": "string",
"b_company": "string",
"b_mobile": "string",
"b_email": "string",
"b_fax": "string",
"b_phone": "string",
"b_address": "string",
"b_zip": "string",
"b_city": "string",
"b_region": "string",
"b_country": "string",
"b_job_title": "string",
"b_department": "string",
"b_reception_code": "string",
"list_uuid": "string",
"channel_names": "string",
"channel_opt_status": "string"
}
}
Responses
Code | Description | Links |
---|---|---|
200 | Webhook created. | No links. |
Success Response 200: Webhook Created
{
"messages": [
{
"body": {
"textMessage": {
"content": "string"
}
}
},
{
"body": {
"cardCarouselMessage": {
"content": [
{
"media": {
"url": "string"
},
"title": "string",
"description": "string",
"suggestions": [
{
"text": "string",
"openUrl": {
"url": "string"
}
}
]
},
{
"media": {
"url": "string"
},
"title": "string",
"description": "string",
"suggestions": [
{
"text": "string",
"openUrl": {
"url": "string"
}
}
]
}
]
}
}
}
]
}
5. Data Models
Data Models define the structure of a JSON document and describe the data related to the Custom webhook endpoint.
5.1 RequestBody
RequestBody 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, GBM. |
message | object | The message data. Message object. |
contact | object | The Business Messenger app's contact data. Contact object. |
JSON Example
{
"serviceUuid": "string",
"dialogUuid": "string",
"channel": "string",
"message": {
"from": "string",
"to": [
"string"
],
"providerMsgID": "string",
"allowedChannels": [
"sms"
],
"custom": [
"string"
],
"timestamp": {
"date": "string",
"timezone_type": 0,
"timezone": "string"
},
"body": {
"textMessage": {
"content": "string"
}
}
},
"contact": {
"uuid": "string",
"created_dt": "string",
"updated_dt": "string",
"opt_status": "string",
"opt_status_webpush": "string",
"first_name": "string",
"last_name": "string",
"second_name": "string",
"nick_name": "string",
"gender": "string",
"birthday": "string",
"salutation": "string",
"title": "string",
"language": "string",
"nationality": "string",
"mobile": "string",
"email": "string",
"phone": "string",
"fax": "string",
"address": "string",
"zip": "string",
"city": "string",
"region": "string",
"country": "string",
"b_company": "string",
"b_mobile": "string",
"b_email": "string",
"b_fax": "string",
"b_phone": "string",
"b_address": "string",
"b_zip": "string",
"b_city": "string",
"b_region": "string",
"b_country": "string",
"b_job_title": "string",
"b_department": "string",
"b_reception_code": "string",
"list_uuid": "string",
"channel_names": "string",
"channel_opt_status": "string"
}
}
5.2 ResponseBody
ResponseBody 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
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. |
timestamp | object | Timestamp object. |
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 TextMessage
TextMessage object properties:
Name | Type | Description |
---|---|---|
content | string | The message content. |
JSON Example
{
"textMessage": {
"content": ""
}
}
5.5 PictureMessage
PictureMessage object properties:
Name | Type | Description |
---|---|---|
name | string | File name. |
url | string | HTTP URL for the media file. |
mimeType | string | File MIME type. |
size | string | File size. |
playingLength | string | Playing length. |
thumbnailName | string | Thumbnail file name. |
thumbnailUrl | string | HTTP URL for the thumbnail file. |
thumbnailMimeType | string | Thumbnail file MIME type. |
thumbnailSize | string | Thumbnail file size. |
JSON Example
{
"pictureMessage": {
"name": "string",
"url": "string",
"mimeType": "string",
"size": "string",
"playingLength": "string",
"thumbnailName": "string",
"thumbnailUrl": "string",
"thumbnailMimeType": "string",
"thumbnailSize": "string"
}
}
5.6 VideoMessage
VideoMessage object properties:
Name | Type | Description |
---|---|---|
name | string | File name. |
url | string | HTTP URL for the media file. |
mimeType | string | File MIME type. |
size | string | File size. |
playingLength | string | File playing length. |
thumbnailName | string | Thumbnail file name. |
thumbnailUrl | string | HTTP URL for the thumbnail file. |
thumbnailMimeType | string | Thumbnail file MIME type. |
thumbnailSize | string | Thumbnail file size. |
5.7 AudioMessage
AudioMessage object properties:
Name | Type | Description |
---|---|---|
name | string | Audio name. |
url | string | HTTP URL for the media file. |
5.8 MediaMessage
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 FileMessage
FileMessage object properties:
Name | Type | Description |
---|---|---|
name | string | File name. |
url | string | File URL. |
mimeType | string | File MIME type. |
size | integer | File size. |
playingLength | string | Playing length. |
thumbnailName | string | Thumbnail file name. |
thumbnailUrl | string | HTTP URL for the thumbnail file. |
thumbnailMimeType | string | Thumbnail file MIME type. |
thumbnailSize | string | Thumbnail file size. |
5.10 FileListMessage
FileListMessage object properties:
Name | Type | Description |
---|---|---|
text | string | Message text. |
files | array | An array of FileMessage objects. |
JSON Example
{
"fileListMessage": {
"text": "",
"files": [
{
"name": "",
"url": "",
"fileType": ""
"mimeType": "",
"size": 0,
"playingLength": "",
"thumbnailName": "",
"thumbnailUrl": "",
"thumbnailMimeType": "",
"thumbnailSize": ""
}
//,...
]
}
}
5.11 LocationMessage
LocationMessage object properties:
Name | Type | Description |
---|---|---|
latitude | number | Latitude. |
longitude | number | Longitude. |
text | string | Location message text. |
url | string | Location URL. |
5.12 ContactMessage
ContactMessage object properties:
Name | Type | Description |
---|---|---|
name | string | Contact's name. |
string | Contact's email. | |
address | string | Contact's address. |
phone | string | Contact's phone. |
5.13 SuggestionsMessage
SuggestionsMessage object properties:
Name | Type | Description |
---|---|---|
suggestions | array | An array of Suggestion object. |
5.14 Suggestion
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 ReplyWithSuggestion
ReplyWithSuggestion object properties:
Name | Type | Description |
---|---|---|
postback | string | The message postback. |
5.16 OpenUrlSuggestion
OpenUrlSuggestion object properties:
Name | Type | Description |
---|---|---|
url | string | Open website. |
5.17 DialNumberSuggestion
DialNumberSuggestion object properties:
Name | Type | Description |
---|---|---|
number | string | A number. |
5.18 ComposeMessageSuggestion
ComposeMessageSuggestion object properties:
Name | Type | Description |
---|---|---|
number | string | A number. |
test | string | A message text. |
5.19 ShowMapLocationSuggestion
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 CreateCalendarEventSuggestion
CreateCalendarEventSuggestion object properties:
Name | Type | Description |
---|---|---|
title | string | Title. |
description | string | Description. |
start | string | Start of the event. |
end | string | End of the event. |
JSON Example
{
"text": "Create Event",
"createCalendarEvent": {
"title": "",
"description": ""
"start": "",
"end": ""
}
}
5.21 CardMessage
CardMessage object properties:
Name | Type | Description |
---|---|---|
layout | object | Card layout. |
content | array | CardMessageContent object. |
5.22 CardCarouselMessage
CardCarouselMessage object properties:
Name | Type | Description |
---|---|---|
layout | object | Message layout. |
content | array | An array of CardMessageContent objects. |
5.23 CardMessageContent
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. |
JSON Example
{
"cardCarouselMessage": {
"layout": {},
"content": [
{
"media": {},
"title": "Card 1",
"description": "",
"suggestions": [ /* Array of suggestions */ ]
},
{
"media": {},
"title": "Card 2",
"description": "",
"suggestions": [ /* Array of suggestions */ ]
}
]
}
}
5.24 Timestamp
Name | Type | Description |
---|---|---|
date | string | Time and date of the message. |
timezone_type | integer | Time zone type. |
timezone | string | Time zone. |
5.25 MessageDestination
MessageDestination object properties:
Name | Type | Description |
---|---|---|
number | string | Destination as a number. |
alias | string | Destination as an alias. |
5.26 Contact
Name | Type | Description |
---|---|---|
uuid | string | Contact UUID. |
created_dt | string | Contact creation date and time. |
updated_dt | string | Date and time when contact is updated. |
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. |
birthday | string | Birthday of a contact. |
salutation | string | Salutation. |
title | string | Title. |
language | string | Language. |
nationality | string | Nationality, |
mobile | string | Mobile number. |
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. |
channel_opt_status | string | Channel opt status. |