How bots can help

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

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.

We give your bots a voice!

The following are common uses for bots:
##Establish identity
Bots can run customers through a series of questions to establish a users identity if you have opted not to link chat to your authentication mechanisms, or your want to add an additional level of identity checking to a sensitive process. You could have the bot update the customers profile using the Profile service as appropriate so that your chat agents have that information to hand when continuing the conversation.

Handling basic enquiries

Most bot platforms can incorporate calling other systems web services into their flows in order to retrieve data, or perform actions, and therefore using a combination of your own and our web services the sky is the limit for what you can do.

Handing 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 inquiries. To cut costs down and increase efficiency the bot is usually used as the first team a new customer inquiry is routed to. If the bot establishes it cannot 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 setup as many teams as required and simply transfer the conversation as appropriate.

🚧

Ensure the customer knows they are talking to a bot

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

Creating a bot adaptor

We can be integrated to almost any bot platform with little work. You simply need to develop a small adaptor layer that will convert between the bots 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. Your choices are:

• Chat API - Use this API if you will be using a combination of bots and chat agent teams
• One API - Use this API if you all your communication will be via your bot

Using the Chat API

In this integration communication with the customer will involve bots and human agents working in collaboration to meet your customers needs. The Chat API will 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. The bot would be associated with a team and would handle all the conversations for that team. The bot will be able to transfer a conversation to another team whenever it feels it is appropriate, and often this will be a team of humans to take over when the bot cannot handle the customers needs.

The following guidance explains how to achieve this:
###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:

• chat:ra
• chat:ro
• chat:wa
• chat:wo
• chat:da
• chat:do
  The easiest way to create this is to open the Advanced options section in the Access Tokens page when creating a new token in the integration section in the portal, and then select the Chat section.

User / 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 do need to store the 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

Inbound messages to the bot

Message sent to your bot will be 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 - Used to indicate a chat has completed
• chat.deleted - Used to indicate a chat has completed
• Chat Message events
• chatMessage.sent - Used to receive message events; recommend adding the direction filter for inbound messages only

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

An example of an inbound message event you would receive is:

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

Outbound messages from the bot

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

• The bots message should be mapped to the parts array.
• Usually only a single part will be needed 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.

An example of what your call may look like to the Enterprise Communications API from your bot adaptor is:

{
  "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 / thinking then you can indicate this by calling the following calls on the Chat API. Simply call the HTTP POST method to indicate the bot is typing / thinking and the HTTP DELETE method to cancel the typing indicator.

Closing Chats

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

Transferring Chats

If your bot determines that a chat requires transferring to another human based team in order to resolve the customers enquiry then the bot should make a call to the Chat API's assign chat method with the teamId the chat should be transferred to. A list of available teams can be obtained by calling the Chat API's chat config method if required.

👍

Done

Now you understand the principles of integrating your chosen bot framework we hope you can now create your adaptor layer to give your bot a multi channel voice using us

Using the Enterprise Communications API

In this integration all communication with the customer will be bot driven, but may be across one or more channels. Our Enterprise Communications API will be used to send and receive messages from the bot to the user. The following guidance explains how to achieve this:

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
  The easiest way to create this is when creating a new token in the integration section in the portal select the One API Access – All Channels + Branch template.

User / 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 bots user id does not match those used by us e.g. if you are using anonymous web chat to start the conversation, then you will need to do some mapping to ensure you can correlate messages.

The bot frameworks will often allow you to specify additional user meta data or channel specific user ids, you will need to ensure that the profile id is stored against the bot user so that it can be retrieved to facilitate the bot sending messages.

It will also be necessary for us to know the bots unique user id so that inbound messages can be assigned to the user correctly when received from us. We recommend using our Enterprise Communications APIs metadata field to pass any data needed to map an inbound messages to the bot user and conversation. The metadata passed will be included on all inbounds and receipts associated with the outbound message automatically by us.

Inbound and outbound messaging

Inbound messages

Message sent to your bot will be 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 will need to take the content and make a call to your chosen bot framework to inject an inbound message into the users conversation. If the inbound event contains metadata (payload.correlation.metadata) then use this to map the inbound message to the correct user / conversation, but no metadata indicates this is a new user / conversation with the bot, and therefore you may need to do some initialisation.

In addition to the user mapping / conversation correlation data discussed above it will be necessary to retain the channel type the last message was received on (held in the payload.channel field), so that the bot can reply using the correct channel. The bot frameworks will often allow you to specify additional user meta data or channel specific user ids, you will need to 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.

An example of an inbound message event you would receive is:

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

Outbound messages

When the bot wants to send a message to the user then the bot adaptor layer will need 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 as discussed above.
• The channel identifier should be mapped from your bots meta data into the rules array to select the correct messaging channel to use.

An example of what your call may look like to the Enterprise Communications API from your bot adaptor is:

{
  "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 will need to use the Enterprise Communications APIs multi-part message option to do this. When using this part 1 should be the associated message text that accompanies the media or file, and the subsequent parts are the media / files. The media / files can be sent in the call to send using either Base64 encoded data or referring to a URL that links to the media / file.

An example of what your call to the Enterprise Communications API might look like is:

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

👍

Done

Now you understand the principles of integrating your chosen bot framework we hope you can now create your adaptor layer to give your bot a multi channel voice using us