Broadcasting API

Potential use cases

Main use case: send a custom message to one of the users on a given trigger. For example, in a barbershop bot, send a message to one of the barbers when a visitor wants to book a timeslot. Users on both ends have to to be subscribed to the bot.

Another use case: make personalized broadcasts when you need to send different messages to different individual users.


Although this functionality is an API integration, we want Chatfuel to create additional value. So we have made broadcasting API into a template. Which would be different from the JSON plugin for example.

We made it possible to send any block from the bot’s structure to any user. You are able to set up user attributes during an API call right before sending the block.

However, if you still want to use a pure JSON message, you can add a JSON plugin to the block.

You have API-accepting POST requests with application/json content type:<bot_id>/users/<user_id>/send?chatfuel_token=<token>&chatfuel_block_id=<block_id>&<user_atrribute_1>=<value1>&<user_atrribute_2>=<value2>&...



  • <token> – a unique secret token obtained for each bot. You are able to find and reset the token in Settings at any time.
  • <user_id> – {{messenger user id}} attribute that you should get from a JSON plugin call prior to sending a message. {{chatfuel user id}} and {{fb_id}} works either.
  • <bot_id> – id of the bot you want to send from (you can find it in browser’s navigation bar).
  • <block_id> – id of the block you want to send to a user (you can find it in the browser navigation bar).
  • <block_name> – URL-encoded name of the block you want to send to a user.
  • <user_atrribute>=<value> – name and value of a user attribute you want to set up before rendering and sending the block.


All params starting with “chatfuel_” are reserved.

You can put params either in the body or the URL.

Here is a booking example

Block content:
Text card:
Hi {{first name}}, {{booking_user}} wants to book a timeslot {{timeslot}}.
Confirm -> confirm booking block
Decline -> decline booking block

API call:
curl -H 'Content-Type: application/json' -X POST -d '{"booking_user":"Daniel Kahneman"}' '<bot_id>/users/<user_id>/send?chatfuel_token=<token>&chatfuel_block_id=<block_id>&timeslot=12:00+25+Jan+2017&...'

You can pass a user attribute in POST data or GET parameters.

Limitations: no more than 1 request per second, per bot.