Other Channels

You may deploy your bot to other custom channels like

• Mobile App

• Raspberry Pi / Arduino

• Smart Speaker

Prerequisites

In order to connect to them, you will need to set up

• The Website Chat Integration

After you have created a Website Chat Integration, you must add a unique custom domain for each channel. Unlike domains you would use for the website chat widget, a custom domain

• Does not need to be a working URL

• Is like a password

• Must not be easily guessable

Examples of good custom domains are

• https://a9sn38h.app.link ✅

• https://03jd874he983h.mywebsite.com ✅

Examples of bad custom domains are

• https://app.mywebsite.com ❌

• https://www.google.com ❌

Setup

After setting up your Website Chat Integration with custom domains, you must

• Register your Users

• Use the Send Message API to send messages as a user

You must register a new user for every person who can message your bot. You will then use the user's webchat_id to send messages as the user.

You will be using 2 models of the BotDistrikt API:

1. bot_user
2. bot_user_message

Register User

POST https://flow.botdistrikt.com/api/webchat_apps/:webchat_app_id/user

Registers a new user from your other channel. Returns the bot_user object to be used for sending messages as this user. You

Path Parameters

Name	Type	Description
webchat_app_id	number	Webchat App ID from the Website Integration page

Request Body

Name	Type	Description
domain	string	The external domain for this External Frontend
webchat_id	string	If you have your own user IDs, you can populate them here for each user. If left blank, the platform will generate one for you. For stronger security, make your user ID unguessable.
user	object	A bot_user object. You may use this to pre-populate some fields for each user.

200 Successfully created a webchat user

{
   webchat_id: "webchat.zbqr0d",
   first_name: "Webchat Guest 51033",
   last_name: "",
   active: true,
   is_group: false,
   channel: "web",
   last_message_at: "2020-02-27T09: 21:00.185Z",
   attributes: {
      webchat_id: "webchat.zbqr0d",
      source: "https://busuncle.sg"
   },
   sessions: 0,
   impressions: 0,
   clicks: 0,
   delay: 0,
   sentiment: 0,
   id: 157,
   bot_id: 4,
   _isDeleted: false,
   created_at: "2020-02-27T09: 21:00.000Z",
   updated_at: "2020-02-27T09: 21:00.000Z"
}

401 Attempted to create a webchat user with an invalid domain not included in the Website Chat's domains

{
    errors:[{
        status: 401,
        source: {},
        title:"Error",
        code: "AUTHORIZATION_REQUIRED",
        detail: "Authorization Required"
    }]
}

Send Message

POST https://flow.botdistrikt.com/api/webchat_apps/:webchat_app_id/message

Sends a message as a user with a valid webchat_id generated for a bot_user object. On success, the bot's responses are returned, which you can use to display in your other channel

Path Parameters

Name	Type	Description
webchat_app_id	number	Webchat App ID from the Website Integration page

Headers

Name	Type	Description
Authorization	string	The webchat_id of the bot_user sending the message

Request Body

Name	Type	Description
domain	string	The external domain for this External Frontend
user	object	The bot_user object
message	object	The bot_user_message object

200 Successfully received a webchat response

{
   webchat_responses: [
      {
         channel: "web",
         type: "text",
         response_payload: {
            type: "text",
            text: "Hey! How are you?",
            buttons: [
               {
                  type: "postback",
                  title: "Wassup!",
                  payload: "__button__Pdy7aQ"
               }
            ]
         },
         quickreplies_payload: [
            {
               type: "text",
               text: "Help me"
            },
            {
               type: "text",
               text: "Give me tips"
            }
         ],
         id: 2519,
         bot_id: 4,
         bot_user_id: 150,
         step_id: 71,
         _isDeleted: false,
         created_at: "2020-02-27T15:25:01.000Z",
         updated_at: "2020-02-27T15:25:01.000Z"
      },
      {
         channel: "web",
         type: "text",
         response_payload: "What can I do for you today?",
         quickreplies_payload: [
            {
               type: "text",
               text: "Help me"
            },
            {
               type: "text",
               text: "Give me tips"
            }
         ],
         id: 2520,
         bot_id: 4,
         bot_user_id: 150,
         step_id: 65,
         _isDeleted: false,
         created_at: "2020-02-27T15:25:01.000Z",
         updated_at: "2020-02-27T15:25:01.000Z"
      }
   ],
   webchat_quickreplies: [
      {
         type: "text",
         text: "Help me"
      },
      {
         type: "text",
         text: "Give me tips"
      }
   ],
   user: {
      email: "[e-mail]",
      active: true,
      first_name: "Abhilash",
      gender: null,
      fb_id: null,
      webchat_id: "botdistrikt.1",
      skype_id: null,
      skype_service_url: null,
      is_group: false,
      channel: "web",
      last_message_at: "2020-02-27T09:58:19.000Z",
      last_click_at: null,
      last_name: "Murthy",
      locale: null,
      country: null,
      platform: null,
      profile_pic: "https://storage.googleapis.com/botdistrikt10/bots/1/20191217_163409_eVO9oa.png",
      timezone: null,
      phone: null,
      notes: null,
      attributes: {
         webchat_id: "webchat.sd8FGx"
      },
      stats: {
         sessions: 3,
         impressions: 13,
         delay: 933,
         sentiment: 0.23076923076923078,
         last_message: "wqew",
         clicks: 0
      },
      sessions: 3,
      impressions: 13,
      clicks: 0,
      delay: 933,
      sentiment: "0.23",
      tags_string: null,
      id: 150,
      facebook_page_id: null,
      bot_id: 4,
      deletedAt: null,
      _isDeleted: false,
      created_at: "2020-02-26T14:42:37.000Z",
      updated_at: "2020-02-27T15:12:01.000Z",
      webchat_app_id: 7
   }
}

401 Attempted to send a message with invalid Authorization header or invalid domain

{
    errors:[{
        status: 401,
        source: {},
        title:"Error",
        code: "AUTHORIZATION_REQUIRED",
        detail: "Authorization Required"
    }]

Event Webhook

The Event Webhook is a webhook URL that can be configured on the Website Chat integration page. This event webhook allows you to add your own custom webhook to receives events of messages that were sent from the bot to the user.

Event Webhook

This is particularly useful if you would like to publish one-way bot-to-user messaging, as opposed to two-way interactions. Some examples of where this can be used

• Live Chat Messaging

• Broadcasts

• Replying with Stories

The headers of the request from an event webhook are as follows:

{
  'X-Botdistrikt-Source': 'human' OR 'broadcast' OR 'bot'
  'X-Botdistrikt-Source-Id': ID of the human, broadcast, or bot
}

If X-BotDistrikt-Source is human, this means a team member (live agent) sent a reply in place of the bot, and the ID of the team member (live agent) is denoted in the value of X-BotDistrikt-Source-Id

If X-BotDistrikt-Source is broadcast, this means a broadcast was published to this user from the bot, and the ID of the broadcast is denoted in the value of X-BotDistrikt-Source-Id

If X-BotDistrikt-Source is bot, this means this was just a normal synchronous bot message. This can be ignored if the Send Message response output will be used in the custom channel.