Creating a Custom HTTP Bot
The Custom HTTP Bot allows software developers to create their own messaging channel to Flow XO chatbots. With just a little bit of code you can integrate Flow XO into nearly any existing messaging workflow or channel, or into your own software tools. This article will demonstrate how to create a very simple custom chat using the excellent code sandbox service Glitch.
How it works
How it worksThe HTTP Bot is very simple. When you create a new HTTP Bot connection you will be given a bot URL unique to your bot. This is the URL that you will post messages from your users to using a JSON format. You will also provide the bot with your own HTTP(s) URL. This is the callback webhook that Flow XO will send the automated messages generated by your flows. It is up to you what you do with those messages - you can pass them to another chat platform to deliver to a user, or you can store them in a database and show them to your user on webpage, like we do in this sample.
Types of Messages
There are two categories of messages you will need to be familiar with, both of which will be represented in JSON:
- Messages you will post to Flow XO on behalf of your users. This message is very simple and consists of a user-defined channel identifier that Flow XO will use to associate the message with a single conversation, some simple user identity data that will be associated with your users Flow XO profile, a text message and optional metadata, which can contain any data you want and will be exposed in the metadata variables inside of Flow XO and available to your flow logic.
- Messages the bot sends that Flow XO will post to your webhook. This message is more complex, and will have a different shape based on whether or not it is a text message, a question, a video, a custom request, etc.
Samples of each type will be shown later in this document.
Getting Started
First, let's get you set up with a working sample application that you can start experimenting with right away. Please follow this brief video. To complete the video you will need a Flow XO account with the HTTP Bot enabled (contact support@flowxo.com if you don't have access to the HTTP bot when creating new bots in your Flow XO account) and a copy of the sample project in Glitch, which you can get by clicking this button:
Please watch this short video walkthrough of creating an HTTP bot and connecting it to the sample app:
The HTTP Bot Configuration
When you create a new HTTP Bot, there are three important pieces of information you'll need to work with
1. The HTTPS URL that you will post user messages to
2. The Secret that must be in the Authorization header of every message you send to Flow XO. If your secret was 12345, you would send a header that looks like this:
Authorization=Bearer 12345
3. The URL of your web service/webhook that Flow XO should post bot messages to.
To send a message to Flow XO, you will need to post a message to the Bot callback URL using this format. Please remember to include an Authorization header that contains the Bot Secret prefixed with "Bearer ".
{
"channel":{
"id":"some@user.com"
},
"from":{
"id":"123abc",
"name":"Some User"
},
"message":{
"text":"/samples"
},
"metadata":{
"origin":"https://melon-aquamarine-muskox.glitch.me/"
}
}
In the example above, the channel ID and the user ID can be the same. In fact, if you omit the channel section Flow XO will use the from.id as the channel identifier. There are situations where you may want them to be different, such as a group chatroom, where the channel ID would be an identifier for the group chat but the actual author of each message could be sent in the 'from' object.
The message is a simple text message. In this example, the user is sending a command "/samples"
The metadata can be anything you want. Flow XO will simply copy it into the Metadata of any trigger that is fired as a result of the message.
If you want to receive a file from the user, you can add a "file" key to yoru incoming message, like this:
{
"channel":{
"id":"some@user.com"
},
"from":{
"id":"123abc",
"name":"Some User"
},
"message":{
"text":"/samples"
},
"metadata":{
"origin":"https://melon-aquamarine-muskox.glitch.me/"
},
"file": {
"url":"https://someserver.com/myfileurl.pdf",
"type":"application/pdf"
}
}
There are various kinds of messages you might receive from Flow XO at the Bot URL you set on your bot configuration. Here is a sample conversation the demonstrates each different type of message. Documentation on these messages types will improve as our beta progresses. In the meantime the sample application provides an excellent way to observe what kinds of messages different flows will send.
In the examples below, the most important message elements are:
message_type - this will tell you the specific type of message. The options are:
- action (typing indicator)
- text
- image
- video
- card_set
- custom
options - this will hold the shortcuts configured on the specific action or, in the case of Ask a Question, the possible question answers.
message - this field will hold different information based on the message_type. For a message, it will be simply text. For an image message it will be a URL, for a video message an object describing the video. And for a card set, an array of card objects. For custom requests the raw request JSON will be in the message field.
const exampleConversation = [
//This is the initial message sent FROM your custom code to the Flow XO bot callback url:
{
"channel":{
"id":"some@user.com"
},
"from":{
"id":"123abc",
"name":"Some User"
},
"message":{
"text":"/samples"
},
"metadata":{
"origin":"https://melon-aquamarine-muskox.glitch.me/"
}
},
//The next series of messages are sent to your webhook URL.
//The bot will send typing indicators in between each message, like this:
{
"channel":"some@user.com",
"message":{
"action":"typing"
},
"options":{
},
"messageTime":"2021-03-31T21:28:15.423Z",
"metadata":{
},
"callback":"https://bm.flowxo.com/integration_http/6063af7aac462500416c2252",
"message_type":"action"
},
//This is a standard Send a Message with some shortcuts defined:
{
"channel":"some@user.com",
"message":"I am a normal send a message",
"options":{
"choices":[
{
"key":"shortcut no value",
"value":""
},
{
"key":"shortcut value",
"value":""
}
],
"choices_message":"Choose from shortcut no value or shortcut value."
},
"messageTime":"2021-03-31T21:28:16.252Z",
"metadata":{
},
"callback":"https://bm.flowxo.com/integration_http/6063af7aac462500416c2252",
"message_type":"text"
},
// Here is an image message
{
"channel":"some@user.com",
"message":"https://s3-eu-west-1.amazonaws.com/flowxo-images/images/c095627f-e15c-4f90-878e-6e9ff451fb17",
"options":{
"choices":[
{
"key":"shortcut",
"value":"hi"
}
],
"choices_message":"Choose from hi."
},
"messageTime":"2021-03-31T21:28:17.608Z",
"metadata":{
},
"callback":"https://bm.flowxo.com/integration_http/6063af7aac462500416c2252",
"message_type":"image"
},
//A video message
{
"channel":"some@user.com",
"message":{
"host":"youtube",
"video_id":"vjjshcZoQxw",
"video_url":"https://www.youtube.com/watch?v=vjjshcZoQxw"
},
"options":{
"choices":[
{
"key":"shortcut",
"value":"sval"
}
],
"choices_message":"Choose from sval."
},
"messageTime":"2021-03-31T21:28:18.879Z",
"metadata":{
},
"callback":"https://bm.flowxo.com/integration_http/6063af7aac462500416c2252",
"message_type":"video"
},
//A single card
{
"channel":"some@user.com",
"message":{
"cards":[
{
"title":"A Card!",
"text":"Card text",
"image_url":"https://s3-eu-west-1.amazonaws.com/flowxo-images/images/c095627f-e15c-4f90-878e-6e9ff451fb17",
"links":[
{
"key":"The Link Text",
"value":"https://www.flowxo.com"
}
],
"choices":[
{
"key":"card button one",
"value":"1"
},
{
"key":"card button two",
"value":"2"
}
],
"choices_message":"Choose from 1 or 2."
}
]
},
"options":{
},
"messageTime":"2021-03-31T21:28:20.609Z",
"metadata":{
},
"callback":"https://bm.flowxo.com/integration_http/6063af7aac462500416c2252",
"message_type":"card_set"
},
//A card set
{
"channel":"some@user.com",
"message":{
"cards":[
{
"title":"First card...",
"text":"Text of first card...",
"image_url":"https://s3-eu-west-1.amazonaws.com/flowxo-images/images/c095627f-e15c-4f90-878e-6e9ff451fb17",
"links":[
{
"key":"Card One Link",
"value":"https://www.flowxo.com/pricing"
}
],
"choices":[
{
"key":"card 1 shortcut",
"value":"https://www.google.com"
},
{
"key":"card 2 shortcut no val",
"value":""
}
],
"choices_message":"Choose from https://www.google.com or card 2 shortcut no val."
},
{
"title":"Card 2 Title",
"text":"Card Two Text",
"image_url":"https://s3-eu-west-1.amazonaws.com/flowxo-images/images/c095627f-e15c-4f90-878e-6e9ff451fb17",
"links":[
{
"key":"Card Two Link",
"value":"https://www.cardtwo.com"
}
],
"choices":[
],
"choices_message":""
}
]
},
"options":{
},
"messageTime":"2021-03-31T21:28:21.920Z",
"metadata":{
},
"callback":"https://bm.flowxo.com/integration_http/6063af7aac462500416c2252",
"message_type":"card_set"
},
// A question. After the question, the bot will pause until you post an answer message.
{
"channel":"some@user.com",
"message":"Multiple Choice Question",
"options":{
"choices":[
{
"key":"Option 1",
"value":"1"
},
{
"key":"Option 2",
"value":"2"
}
],
"choices_message":"Answer with 1 or 2.",
"message":"Multiple Choice Question"
},
"messageTime":"2021-03-31T21:28:23.414Z",
"metadata":{
},
"callback":"https://bm.flowxo.com/integration_http/6063af7aac462500416c2252",
"message_type":"question"
},
//The bot paused until this message was sent FROM your integration
{
"channel":{
"id":"some@user.com"
},
"from":{
"id":"123abc",
"name":"Some User"
},
"message":{
"text":"1"
},
"metadata":{
"origin":"https://melon-aquamarine-muskox.glitch.me/"
}
},
//The bots final message, a Custom Request:
{
"channel":"some@user.com",
"message":{
"custom":"request"
},
"options":{
},
"messageTime":"2021-03-31T21:28:30.818Z",
"metadata":{
"meta":"data",
"happy":"coding"
},
"callback":"https://bm.flowxo.com/integration_http/6063af7aac462500416c2252",
"message_type":"custom"
}
]
Have fun building your own Flow XO messaging channel, and please feel free to reach out to support@flowxo.com with any questions or feedback.