How to access the Botmaker API for WhatsApp?

Here you will learn how to access the Botmaker API for WhatsApp.

Estimated Reading Time: 15 minutes

Messages sent by users can be instantly viewed in the Botmaker Operator Console, where it is possible to respond manually or via bots. It is also possible to notify a system of these messages. If you wish to receive each message, you can set-up a webhook on your systems as such:

Access the Botmaker Operator Console and select “Settings, Channels, WhatsApp”. If you prefer, head directly to https://go.botmaker.com/#/platforms.
On the endpoint area of the message, insert your endpoint URL. For example https://example.com/income
Your endpoint must be in HTTP 200 code, have a valid HTTP certificate, be available at all times, and be able to respond in less than 10 seconds.

Once activated, you will start receiving messages according to the Google PubSub policies, signed messages, 7-day message preservation, etc.

The following example shows a typical message from a user:

{
  "CHAT_PLATFORM_ID": "message_platform", // for instance whatsapp 
  "MESSAGE": "Hello!",                     // the user message text
  "CREATION_TIME": "a_date",              // ISO 8601 for message time, for instance 2018-09-03T14:30:24.578Z
  "FROM_NAME": "user_name",               // name of user if possible
  "CUSTOMER_ID": "user_id",               // unique id of user
  "_id_": "message_id",                   // unique id of message
  "FROM": "phone_number",                 // user phone number
  "SESSION_CREATION_TIME": "session_id",  // chat session id

  // other less important fields are also included in the message
  ...
}`

We also support multimedia files (voice messages, audios, documents, images, etc.), for example:

{
   "FROM_NAME": "user_name",               // name of user if possible
   "IMAGES_URLS": [
     "https://botmaker.com/hostedImageByUser.png"
   ],
   ...
}`

Sending messages to users

It is possible to send messages to users using the operator’s console, generating notifications en masse and programming their delivery with different incentives. The Botmaker API can also be used to activate program messages from a system.

To do this, you must obtain an API access token by following these steps:

Enter channel settings.
Select BotMaker API – Credentials.
Generate a token or use one that’s already generated. It is imperative that you do not lose this token, save it.

With the token at your disposal, making the HTTP publication called API rest within a JSON will be possible:

curl -X POST --header 'Content-Type: application/json' --header 'Accept: application/json' --header 'access-token: your_access_token' -d '{"chatPlatform": "whatsapp", "chatChannelNumber": "your_phone", "platformContactId": "user_phone","messageText": "message_to_send"}' 'https://go.botmaker.com/api/v1.0/message/v3'

# your_access_token: Hey...
# your_phone: +55135433...
# user_phone: +5512324314..
# message_to_send: Hi!

The response will be an HTTP 200 code with a JSON that indicates the ID of the generated message:

{
  "id": "id_del_mensaje"
}`

Every time a message is sent to the user, a balance verification will be performed in your Botmaker account. If the account credit is about to run out, an HTTP 403 code – Forbidden, will be returned which indicates there is insufficient credit to send a message in the JSON reply:

{
  "error": {
    "code": 101,
    "message": "Insufficient credit"
  }
}`

Every time a message is sent to the user, a verification will take place to determine if WhatsApp will reject the message, because the user has not spoken to you on the platform in the last 24 hours. Consult the message templates section for more information:

{
  "error": {
    "code": 201,
    "message": "User window is over 24 hours"
  }
}`

Message templates

WhatsApp allows users to send messages within 24 hours after the last message sent by them. Outside of this period, messages must be submitted using the endpoint intent and performing the following steps:

Access the templates area and send them.
Once approved, the intent will be created with your name.

Simply make the call to the endpoint:

curl -X POST --header 'Content-Type: application/json' --header 'Accept: application/json' --header 'access-token: your_token' -d '{"chatPlatform": "whatsapp", "chatChannelNumber": "your_phone_number", "platformContactId": "user_phone_number", "ruleNameOrId": "rule_name", "params": {"my_template_var":"var_value"}}' 'https://go.botmaker.com/api/v1.0/intent/v2'

# your_token: your access token
# your_phone_number: whatsapp number of yours
# user_phone_number: whatsapp number of user
# rule_name: botmaker rule name`

Multimedia messages

Botmaker allows you to send all kind of multimedia messages compatible with WhatsApp and other channels. To do this, you must create a message in rules following the instructions in the page “How to create replies on an intent page?”.

You can also call the rule activation service from your system. For example:

curl -X POST --header 'Content-Type: application/json' --header 'Accept: application/json' --header 'access-token: your_token' -d '{"chatPlatform": "whatsapp", "chatChannelNumber": "your_phone_number", "platformContactId": "user_phone_number", "ruleNameOrId": "rule_name", "params": {"param_key_1":"param_value_1"}}' 'https://go.botmaker.com/api/v1.0/intent/v2'`

# your_token: your access token
# your_phone_number: whatsapp number of yours
# user_phone_number: whatsapp number of user
# rule_name: botmaker rule name

Alternatively, you can use the frequent messaging service and specify the URL of the media file you want to send.


# your_access_token: Hey...
# your_phone: +55135433...
# user_phone: +5512324314..
# file_caption: a text description next to the file
# audio_to_send: https://....my_audio.mp3  
# image_to_send: https://....my_photo.jpeg
# file_to_send: https://....my_file.pdf`

Choose one or more media formats to send a message. Here is a list of all supported file formats. WhatsApp currently does not support videos and GIFs for this type of operation at the moment.

Changes in status of sent messages

After sending a message to a user, your endpoint will receive notifications of delivery or read receipt of that message.

Delivered indicates that the message was sent - double checkmark in WhatsApp
Read indicates that the targeted user has read the message - double blue colored checkmark in WhatsApp.

{
  "CHAT_PLATFORM_ID": "message_platform", // for instance whatsapp 
  "CREATION_TIME": "a_date",              // ISO 8601 for message time, for instance 2018-09-03T14:30:24.578Z
  "CUSTOMER_ID": "user_id",               // unique id of user
  "_id_": "message_id",                   // unique id of message
  "FROM": "phone_number",                 // user phone number
  "STATUS": "el_cambio_status"            // message read or delivered
}`

If the user has disabled the “read receipt” option in their privacy settings, these notifications will not be received.

Formatting messages via the API.

It is possible to apply simple text formatting to messages that will be sent to users, for example, “Hello, John.” For more information, consult the WhatsApp Formatting Documentation.

How to access the Botmaker API for WhatsApp?

Here you will learn how to access the Botmaker API for WhatsApp.

Estimated Reading Time: 15 minutes

Sending messages to users

Message templates

Botmaker

Articulos relacionados

Tags