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 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.

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-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.

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:

1. Create an account on ChatGPT Sign Up page.

2. 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.

3. Visit Settings > Conversation API page in the Business Messenger app and check the check box to enable Conversation API.

   

4. For API Type select ChatGPT.

5. Fill in your OpenAI API secret Key.

6. 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.

7. 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.

8. 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 Custom Webhook Endpoint

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.

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.

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

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.

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.horisen.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.

* 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.

^[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.