Skip to content



The preferred partner for using Whatsapp is 360dialog

Adapter limitations

Incoming (user-sent) messages:

  • Contact cards are not handled
  • Location pins drop the address, name and url field
  • Live locations are not supported. Instead an event called $unsupported_message is sent into the bot.

Outgoing (platform-sent) messages:

  • Stickers are converted into image attachments. Sticker metadata is kept inside attachment.metadata
  • No support for outgoing contact cards

Sending template messages

Template messages are messages that can be sent outside the 24h window of Whatsapp interaction. They need to be pre-approved by Whatsapp and are managed in the Facebook Business manager.

In Bubblescript, sending templates is supported through the show template("text", ...) construct:

  show template("text", template_id: "order_prompt", parameters: %{"1" => "John"})

This assumes a text template named order_prompt is available in Whatsapp, that has one parameter (for instance the template contents could be "Hi {{1}}, your order is ready").

Interactive messages

Two types of interactive messages are supported, buttons and list.


The Bubblescript buttons template is sent as a Whatsapp interactive message:

_buttons = [
  %{title: "Order", type: "event", event: "order", payload: 1234},
  %{title: "Browse", type: "event", event: "browse"}
show template("buttons", buttons: _buttons, text: "What do you want to do next?")

Only buttons of type event are supported. When a button is clicked, the corresponding event is fired. An event payload can be added as well, which will be sent along. However, the payload must be kept very small, do not send big objects or lists as Whatsapp will give an error.

Item picker

The default item picker is supported natively on whatsapp. However, it only supports picking single items, picking multiple items is not possible.

List template

An alternative way of showing whatsapp's list picker is through using the list template.

Note that a text: argument has to be given to the list template, in contrast with other channels that support lists (Web/FB messenger).

  _items = [
    %{title: "Item number 1", subtitle: "This is is something about nr 1"},
    %{title: "Number 2", subtitle: "This is number 2"},
    %{title: "Number 3", subtitle: "The final item"}
  _button = [type: "event", title: "Choose", event: "choose"]
  show template("list", elements: _items, text: "Please choose an item", button: _button)

The list button has to be of the type event. The given event is used to indicate that a list item has been selected, where the payload is the element index in the list.

In the above example, when the second item in the list is chosen, the event "choose" is fired, with a payload of 1.


It is also possible to use Twilio API for Whatsapp.

To connect your bot to Whatsapp, you need an account at Twilio and set up a phone number for use with Whatsapp. Enter the application and authorization tokens from Twilio in the Botsquad configuration, and finally, in the sender configuration at twilio, set up the webhook to point at your Botsquad's bot endpoint.

Adapter limitations

Incoming (user-sent) messages:

  • Contact cards are converted into file attachments

Outgoing (platform-sent) messages:

  • No support for outgoing contact cards

Deliver status tracking

The delivery of whatsapp messages can be tracked in realtime using REST API webhooks, for both Twilio and 360dialog adapters.