How bots can help

Using bots to handle simple customer enquiries or easily automated tasks such as checking an order status, or a product’s stock level makes sense from both the business and customers’ perspectives, as it’s cheaper for the business to service and more efficient for the customer.

This pages covers the various approaches for integrating your chosen bot platform with us, so that your bot can interact with your users across all of our channels.

Common uses for bots

Establish identity

Bots can run customers through a series of questions to establish a user’s identity if you have opted not to link chat to your authentication mechanisms, or if you want to add an additional level of identity checking to a sensitive process.

You could have the bot update the customer’s profile using the Profile service so that your chat agents have the information to hand when continuing the conversation.

Handle basic enquiries

Most bot platforms can incorporate calling other systems’ web services into their flows in order to retrieve data, or perform actions. Using a combination of your own and our web services there’s no limit to what you can do.

Hand off to customer support

To provide the highest level of customer support, you can use both bots and teams of chat agents to handle your customers’ enquiries. To cut costs down and increase efficiency the bot is usually used as the first team a new customer enquiry is routed to.

If the bot establishes that it can’t handle the enquiry, then it can transfer the conversation to a chat agent team using our chat API so they can take over the conversation. You can set up as many teams as you need, and transfer the conversation as appropriate.

🚧

Ensure the customer knows they are talking to a bot

It’s recommended that you make it clear, maybe in the welcome message, that the customer is talking to a bot, as if they think they are talking to a human and then discover they aren't it can cause frustration.

How to integrate

Create a bot adaptor

We can be integrated to almost any bot platform; you just need to develop a small adaptor layer that converts between the bot’s messaging API and our API.

There is a choice of API's to use and this depends on whether you want to use our Chat tool for live chats or not, in addition to your bot.

Options:

• Chat API - if you want to use a combination of bots and chat agent teams.
• One API - if all of your communication is through your bot.

Use the Chat API

With the Chat API, communication with the customer involves both bots and human agents working in collaboration to meet your customers’ needs. The Chat API can be used to send and receive messages from your teams to the customer across all supported channels.

The Chat API allows teams to have conversations assigned to them to be resolved, and agents are assigned to teams. A bot can be associated with a team to handle all the conversations for that team. The bot can transfer a conversation to another team whenever it feels it is appropriate, and often this is a team of humans to take over when the bot cannot handle the customer’s needs.

Access token for the bot

To ensure the bot can access the necessary APIs for a typical integration, we recommend that the access token you create for the bot includes the following permissions:

• chat:ra
• chat:ro
• chat:wa
• chat:wo
• chat:da
• chat:do

Learn more about creating access tokens in Permissions.

User and conversation correlation

Most bot frameworks, and the Chat API, support a single conversation with a user at a time, and therefore the conversation correlation is simply to the unique user ID the bot uses to represent the user, and the Chat ID the bot is communicating with.

If you need to store additional details in order to correlate an outbound message from us back into the bots conversation, then you can add additional details using the metadata property when sending a chat message using the Chat API.

Inbound and outbound messaging

Message sent to your bot are delivered to your bot adaptor using our webhooks. These webhooks can be configured to deliver various event types in real-time.

For the bot integration we recommend the the follow:

• Chat events
  chat.closed
  chat.deleted
• Chat message events
  chatMessage.sent
  Used to receive message events; we recommend adding the direction filter for inbound messages only.

When you receive a chatMessage.sent event on your webhook reception page, you need to take the content and make a call to your chosen bot framework to inject an inbound message into the user’s conversation. If the inbound event contains metadata (payload.metadata) then use this to map the inbound message to the correct user and conversation, otherwise, use the chat ID (payload.context.chatId).

Example inbound chat message:

{
    "eventId": "1ca84072-1b44-446c-9000-9746191ca2eb",
    "accountId": 1234,
    "apiSpaceId": "4ba42f12-6e0c-49ab-a41f-f8d7a782a2df",
    "name": "chatMessage.sent",
    "payload": {
        "metadata": {},
        "context": {
            "from": {
                "id": "c5ce8276-a624-4e04-aada-3cbb59bc9cca"
            },
            "chatId": "973880db-75b4-49e5-8c06-2bb030d70319",
            "teamId": "Customer_Services",
            "sentBy": "session:c5ce8276-a624-4e04-aada-3cbb59bc9cca",
            "sentOn": "2019-12-10T12:22:00.315Z",
            "direction": "inbound"
        },
        "parts": [
            {
                "name": "body",
                "type": "text/plain",
                "data": "Hi"
            }
        ],
        "id": "826a3689-fe34-4ce1-82bd-7452a13feae2"
    },
    "revision": 10,
    "timestamp": "2019-12-10T12:22:00.316Z"
}

When the bot wants to send a message to the user, the bot adaptor layer must convert the outbound bot message to a call to our Chat Message API with the following data:

• The bots message should be mapped to the parts array.
• Usually only a single part needs to be mapped to the correct MIME Type for the content.
• The chat correlation information mapped to the chatId field from either the user ID or meta data as discussed above.
• Ensure you set isAutomatedSend to true for bot sends to ensure that they do not skew your response analytics for your human team.

Example call to the API from your bot:

{
  "from": {
    "profileId": "ExampleBot",
    "name": "Example bot"
  },
  "parts": [
    {
      "name": "Text",
      "type": "text/plain",
      "data": "Howdy!",
      "size": 9
    }
  ],
  "alert": {
    "title": "Example bot",
    "body": "Howdy!"
  },
  "direction": "outbound",
  "isAutomatedSend": true,
  "body": "Howdy!"
}

{
  "from": {
    "profileId": "ExampleBot",
    "name": "Example bot"
  },
  "parts": [
    {
      "name": "https://media2.giphy.com/media/8vR1IMa3kzvvdEuEkL/giphy.gif",
      "type": "image/gif",
      "url": "https://media2.giphy.com/media/8vR1IMa3kzvvdEuEkL/giphy.gif"
    }
  ],
  "alert": {
    "title": "Example bot",
    "body": "You have received a picture"
  },
  "direction": "outbound",
  "isAutomatedSend": true
}

Typing indicators

If your bot supports the ability to indicate it is typing then you can indicate this by calling the following calls on the Chat API. Call the HTTP POST method to indicate the bot is typing, and the HTTP DELETE method to cancel the typing indicator.

Close chats

When you identify that a chat is complete with a customer, the bot can close the chat by calling the Chat API's close chat method.

Transfer chats

If your bot determines that a chat requires transferring to a human-based team in order to resolve the customer’s enquiry, then the bot can make a call to the Chat API's assign chat method with the teamId that the chat should be transferred to.

You can access a list of available teams by calling the Chat API's chat config method if you need to.

Use the Enterprise Communications API

Using this integration, all communication with the customer is bot driven, but may be across one or more channels. Our Enterprise Communications API is used to send and receive messages from the bot to the user.

Access token for the bot

To ensure the bot can access the necessary APIs for a typical integration we recommend that the access token you create for the bot include the following permissions:

• content:w
• chan:r
• msg:any:s
• msg:r
• msg:branch
• prof:ra

Learn more about creating access tokens in Permissions.

User and conversation correlation

Most bot frameworks support a single conversation with a user at a time, and therefore the conversation correlation is simply to the unique user ID the bot uses to represent the user and the profile ID the bot is communicating with.

Matching user identifier schemes

If your bot is configured to use the same unique identifier for users as you use with our profile ID, then correlation is simply to copy the bot user ID to the to.id field in the calls to the Enterprise Communications API.

Differing user identifier schemes

If the bot’s user ID does not match those used by us, for example, if you’re using anonymous web chat to start the conversation, then you must do some mapping to ensure you can correlate messages.

The bot frameworks often allow you to specify additional user metadata, or channel specific user IDs, you must ensure that the profile ID is stored against the bot user so that it can be retrieved to use for sending.

You must also provide the bot’s unique user ID so that inbound messages can be assigned to the user correctly when received from us. We recommend using our Enterprise Communications API's metadata field to pass any data needed to map an inbound messages to the bot user and conversation. The metadata passed is included on all inbounds and receipts associated with the outbound message automatically by us.

Inbound and outbound messaging

Messages sent to your bot are delivered to your bot adaptor using our webhooks. These webhooks can be configured to deliver various event types in real-time. For the bot integration we recommend the Enterprise Communications API Message events, which include inbound messages and receipts for the messages your bots send.

When you receive a message.inbound event on your webhook reception page, you must take the content and make a call to your chosen bot framework to inject an inbound message into the user’s conversation. If the inbound event contains metadata (payload.correlation.metadata), then use this to map the inbound message to the correct user and conversation, however, no metadata indicates that this is a new user or conversation with the bot, and therefore you may need to do some initialisation.

In addition to the user mapping and conversation correlation data, you need to retain the channel type the last message was received on so that the bot can reply using the correct channel. This information is held in the payload.channel field. The bot frameworks often allow you to specify additional user metadata, or channel specific user IDs. You must ensure that the channel ID is stored against the bot user so that it can be retrieved to select the correct channel when sending messages.

Example inbound message

{
  "eventId": "020b8e91-a116-47c6-b7e9-dab878e5761a",
  "accountId": 1234,
  "apiSpaceId": "fb42e8af-5fc3-40d4-a38c-034535c0a385",
  "name": "message.inbound",
  "payload": {
    "from": {
      "fbMessengerId": "1924625277645988",
      "profileId": "{Our unique user id}"
    },
    "channel": "fbMessenger",
    "body": "Hi there",
    "channelData": {
      "pageId": "118143536805220",
      "body": {
        "sender": {
          "id": "1924625277645988"
        },
        "recipient": {
          "id": "118143536805220"
        },
        "timestamp": 1496157103192,
        "message": {
          "mid": "mid.$cAAAnV7v5AVdiiy7sWFcWemjwmFUt",
          "seq": 611,
          "text": "Hi there"
        }
      }
    },
    "id": "8e14bc40-cf93-44bf-be7b-d5dfa77cb53e",
    "receivedOn": "2017-05-30T15:11:44.451Z",
    "correlation": {
      "messageId": "63351f02-4e90-49d8-8b2a-c635d3cd219c",
      "metadata": {
        "botUserId": "{The bot platforms unique user id}"
      }
    }
  },
  "revision": 0,
  "etag": "\"2e-gLoREj4XI35uB44EZ2pYIeiIhls\"",
  "timestamp": "2017-05-30T15:11:45.169Z"
}

When the bot wants to send a message to the user, the bot adaptor layer needs to convert the outbound bot message to a call to the our Enterprise Communications API with the following data:

• The bots message should be mapped to the body field.
• The correlation information mapped to either the id or metadata fields.
• The channel identifier should be mapped from your bot’s metadata into the rules array to select the correct messaging channel to use.

Example call

{
  "body": "Your message from the bot",
  "to": {
    "id": "{Our unique user id}"
  },
  "rules": [
    "fbMessenger" // The channel is extracted from the bots metadata
  ],
  "metadata": {
    "botUserId": "{The bot platforms unique user id}"
  }
}

Attachments

If your bot wants to send images, other media types, or files then it must use the Enterprise Communications API’s multi-part message option to do this.

When using this, part one should be the associated message text that accompanies the media or file, and the subsequent parts are the media or files. The media or files can be sent in the call to send using either Base64 encoded data or referring to a URL that links to the media or file.

Example call with media or files:

{
  "to": {
    "id": "{Our unique user id}"
  },
  "rules": [
    "fbMessenger" // The channel is extracted from the bots metadata
  ],
  "messageParts": [
    {
      "name": "Body text",
      "type": "text/plain",
      "data": "Is this the laptop you were interested in?"
    },
    {
      "name": "Item picture",
      "type": "image/png",
      "url": "http://cdn.dnky.co/3rdparty/comapi/images/laptop.png"
    }
  ],
  "metadata": {
    "botUserId": "{The bot platforms unique user id}"
  }
}