Make a Custom Request

Because Flow XO works across messaging platforms, it's impossible to offer cross-platform support for some of the more unique features and formats that some of the platforms offer.

For example, we support Images & Cards on all platforms, giving you a generic way of sending a card regardless of the platform, and handling fallback formatting on platforms that don't support a full card format (such as Twilio SMS).

However, Facebook Messenger have an Airline Itinerary Template which is very unique to Messenger. The Bot > Make a Custom Request action makes it easy to use that feature.

Setting Up a Custom Request

You'll find the custom request action on the Bot service. So anywhere in your flow (after the trigger), you can add a new action, select Bot, and then choose Make a Custom Request from the list.

The action takes a Response Path (you'll receive this from any bot trigger and tells us how to route a message back to a user), and a Request, which is usually JSON that closely matches the request format that will be detailed in the platform's own API docs. We handle adding any routing related properties to it. There are examples below of the formats expected by each platform, and you should be able to use the examples along with their API docs to put together your request.

There is also a Metadata field which is used for specifying any options or other data about the request that we sometimes need.

Usage by Platform

NOTE: It is not necessary to use custom requests for many Messenger specific features. We offer a Messenger Actions integration that gives you a much easier way to use Telegrams bot API directly, including specifying custom keyboards. Of course the Custom Request action is still available for Telegram should you need it.

Facebook Messenger

The request is the JSON payload of the 'message' property which will be sent through the Send API. The 'recipient' property will be handled by us, along with the token. The 'notification_type' can optionally be set in metadata too.

For example, to send the Button Template from the Facebook Messenger API reference:

{
   "attachment":{
      "type":"template",
      "payload":{
         "template_type":"button",
         "text":"What do you want to do next?",
         "buttons":[
            {
               "type":"web_url",
               "url":"https://petersapparel.parseapp.com",
               "title":"Show Website"
            },
            {
               "type":"postback",
               "title":"Start Chatting",
               "payload":"this phrase will be triggered"
            }
         ]
      }
   }
}

Slack

The request should be the JSON payload for the chat.postMessage method. We will add in the token and channel for the user (replace them if already in the JSON). The metadata field is redundant for this platform.

For example, to send Message Buttons as described in Slack's API guide:

{
   "text":"Would you like to play a game?",
   "attachments":[
      {
         "text":"Choose a game to play",
         "color":"#3AA3E3",
         "attachment_type":"default",
         "actions":[
            {
               "name":"chess",
               "text":"Chess",
               "type":"button",
               "value":"chess"
            },
            {
               "name":"maze",
               "text":"Falken's Maze",
               "type":"button",
               "value":"maze"
            }
         ]
      }
   ]
}

NOTE: It is not necessary to use custom requests for most Telegram specific features. We offer a Telegram Actions integration that gives you a much easier way to use Telegrams bot API directly, including specifying custom keyboards. Of course the Custom Request action is still available for Telegram should you need it.

The request is the JSON payload for any of Telegram's Bot API methods. A 'method' property in metadata should correspond with a Telegram method (such as 'sendMessage'). We will add in the 'chat_id' (replacing it if already in the JSON).

So to send a message with Telegram's sendMessage method along with a keyboard with 2 buttons, use the request:

{
   "text":"This is some text.",
   "reply_markup":{
      "keyboard":[
         [
            "Foo",
            "Bar"
         ]
      ]
   }
}

Making sure you also set a property of 'method' to 'sendMessage' in the metadata field:

Twilio SMS

Request is a JSON payload for Twilio's Send a Message method. We will add in 'to' and 'from' (replacing them if already in the JSON). The metadata field is redundant.

For example, to send a simple message:

{
  "body": "This is the ship that made the Kessel Run in fourteen parsecs?"
}

Web Messenger

Custom requests are not supported for the web messenger and will result in an error.

FAQ

I am getting an error saying the request is not JSON

Make sure each of your properties are enclosed with double quotes. You could also try running your request through a JSON formatter & validator.

How can I handle button presses that come back to my bot?

We will attempt to convert any button press payloads/values into new messages that can be handled with Bot Triggers.

Let us know how we can improve Flow XO on our feedback site.