Bot Integration 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 Business Messenger Easy Dialog app, can be generated with Botpress or some custom third-party API. So, when someone sends a message to Easy Dialog, if automatic response is enabled, they will receive a message back generated by the bot.

This feature can be enabled or disabled through the Business Messenger application Settings section. The bot can be set up from the Settings > Bot Integration API Settings page.

BM Bot Integration

The first option is a checkbox for enabling/disabling automatic responses. If this option is checked, then API type, that will be in use, has to be selected. It can be chosen between Botpress and Custom option.

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

For now, only a few types of the Botpress outbound messages are supported:
- Text messages
- Image messages
- Single choice messages

Also, multi-message responses are supported.

Custom Adapter

Integrating the Bot Integration 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 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).

BM Bot Integration

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:

{
  "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"
        }
      }
    }
  ]
}
{
  "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"
              }
            }
          ]
        }
      }
    }
  ]
}
{
  "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/"
                  }
                }
              ]
            }
          ]
        }
      }
    }
  ]
}
{
  "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"
        }
      }
    }
  ]
}

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 below, is used for the integration of external systems regarding Inbound and Outbound Traffic. This endpoint should understand our payloads.

2. Method Overview

Endpoint for custom adapter for Bot Integration API.

POST/custom-bot-api
Custom adapter for Bot Integration API.Read More

3. Method Details

Endpoint for custom adapter for Bot Integration API.

POST/custom-bot-api
Custom adapter for Bot Integration API.Up

Method Overview

The method creates a webhook.

URL Parameters

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

Data Parameters

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"
                  }
                }
              ]
            }
          ]
        }
      }
    }
  ]
}

4. Data Models

Data Models define the structure of a JSON document.

4.1 Data

Data describe the data related to the custom webhook endpoint.

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

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"
              }
            }
          ]
        }
      }
    }
  ]
}

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.

TextMessage object properties:

Name Type Description
content string The message content.

JSON example

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

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

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.

AudioMessage object properties:

Name Type Description
name string Audio name.
url string HTTP URL for the media file.

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.

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.

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": ""
          }
          //,...
        ]
    }

}

LocationMessage object properties:

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

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.

SuggestionsMessage object properties:

Name Type Description
suggestions array An array of Suggestion object.

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.

ReplyWithSuggestion object properties:

Name Type Description
postback string The message postback.

OpenUrlSuggestion object properties:

Name Type Description
url string Open website.

DialNumberSuggestion object properties:

Name Type Description
number string A number.

ComposeMessageSuggestion object properties:

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

ShowMapLocationSuggestion object properties:

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

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": ""
    }
}

CardMessage object properties:

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

CardCarouselMessage object properties:

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

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 Exemple

{
    "cardCarouselMessage": {
        "layout": {},
        "content": [
            {
                "media": {},
                "title": "Card 1",
                "description": "",
                "suggestions": [ /* Array of suggestions */ ]
            },
            {
                "media": {},
                "title": "Card 2",
                "description": "",
                "suggestions": [ /* Array of suggestions */ ]
            }
        ]
    }
}

Timestamp object properties:

Name Type Description
date string Time and date of the message.
timezone_type integer Time zone type.
timezone string Time zone.

MessageDestination object properties:

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

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.