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 cloud code service ValTown. 
The 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. To complete these steps you will need a Flow XO account and a copy of the sample on ValTown. Go to the project page for the sample and click the "Remix" button in the top right hand side of the screen.
Create an HTTP Bot
Once you have a copy of the sample running in your own ValTown project, you will need to make a few changes to get the sample to work with your own Flow XO account. First, create a new "HTTP Bot":
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 set up the sample, you will need to copy your ValTown URL to the Bot URL in the HTTP Bot configuration inside of Flow XO. You will find your ValTown URL on the "home" tab of the sample project. Copy that URL and paste it into the Bot URL field of the HTTP Bot Configuration, and then add "/out", as shown.
Next, you need to copy the Bot callback URL and Bot Secret into the index.ts file of the ValTown project. Make sure to save your changes in ValTown as you go along (cmd-S or ctrl-S).
Now you can click "Next" in the HTTP Bot Configuration in Flow XO, and now your bot is set up and ready to go. To preview the sample in ValTown, click back on the "Home" tab
Now the sample should be up and running and you can explore the code to get a feeling for how it works. For most of you who aren't creating a UI but are using the HTTP bot to integrate with a third party messenger system that we don't yet support (like Line or WeChat), you will only need to bother with creating the "/out" endpoint to send messages from Flow XO to your preferred messenger. You will also need to subscribe to the webhooks of the system you are integrating with and POST messages from the user to Flow XO (the code you see in the "out" endpoint in the sample).
Here is some more information on how to send messages to Flow XO from your user, and the kinds of messages Flow XO will be sending to you.
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":{
"some":"metadata"
}
}
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 your incoming message, like this:
{
"channel":{
"id":"some@user.com"
},
"from":{
"id":"123abc",
"name":"Some User"
},
"message":{
"text":"/samples"
},
"metadata":{
"some":"meta"
},
"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":{
"some":"meta"
}
},
//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":{
"some":"meta"
}
},
//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.