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:

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

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

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

Timestamp object properties:

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

Contact object properties:

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.
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.
channel_opt_status	string	Channel opt status.