How to access Botmaker API for WhatsApp?
In this article, you will get information about how to access Botmaker API for WhatsApp.
Estimated reading time: 10 minutes
It is possible to send messages to users using the agent console, where you can respond manually or via bots. From the Botmaker API, you can also generate mass notifications and schedule their delivery from a system.
Note : these actions are valid for conversations generated within a 24-hour period. Otherwise, you can send templates. See our related article:How to submit templates?
How to obtain credentials to access the API?
To access the API, you need to obtain an access token by following these steps:
- Log in to Channels and Integrations>Botmaker API.
- Select Botmaker API >Generate Credentials.
- Generate a token or use one already generated. It is imperative that you do not lose this token. Save it.
- Enter this token in the access-token header of the HTTP request.
Is it possible to test the API?
Yes, to test the API, you need to go to https://go.botmaker.com/apidocs/. Click on "Authorize". When you enter the access token, all the options that the API allows will appear.
Click on "message" and then on post> message/V3.
Next, fill in the parameters:
- Copy the Example Value example,
- Add your channel and phone data, message text, etc…
With access to the token, it will be possible to make the HTTP publication called API rest inside a JSON:
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: ey…
#your_phone: +55135433…
#user_phone: +5512324314…
#message_to_send: Hi!
The response will be an http 200 code with a JSON indicating the ID of the generated message:
{
"id": "id_del_mensaje"
}`
Each time a message is sent to the user, a balance check will be performed on your Botmaker account. If the account is about to run out of balance, the service will return an http code 403 - Forbidden , indicating that there is no balance to send messages in the JSON response:
{
"error": {
"code": 101,
"message": "Insufficient credit"
}
}`
See the Message Templates section for more information:
WhatsApp Message Templates
WhatsApp allows users to send messages within 24 hours of the last message sent by them. Outside that period, you have to use templates. To send new templates for approval, you can access from Menu>Sending Notifications>Templates. Here, you can create them by clicking on the " +" at the top of the screen.
For detailed information on how to create and send WhatsApp templates, see our related article How to create and send a WhatsApp template optimizing response times?
Once the template has been approved (you can check this under Menu>Templates), you can create an intent to trigger that template as needed. Follow the steps below:
Step 1: Go to Menu>Chatbots
Step 2 : Create a new intent
Step 3 : When setting up the response to your intent, select Action>WhatsApp Notification.
Step 4 : Select the template you want to use and click " save".
Note : When creating the template, you can add variables or texts that autocomplete information in the WhatsApp parameters.
Sending templates
You can send templates in three different ways (always considering the sending through the Botmaker platform)
-
Individually from the manual chat section (Conversations>Chats>Send template)
-
Massively from the audience section (Sending notifications>Audiences)
See details on how to send templates in our article: How to submit templates? -
Using the Botmaker API. Please refer to the following article: How to create and send a WhatsApp template optimizing response times?
Webhooks: how to receive chat messages
For detailed information on how to integrate webhooks, please refer to the article: How to integrate webhooks?
Format of webhook notifications
There are 2 types of notifications:
- Message
- Message status
Message notifications
These are notifications that are received when a message arrives from the user or when the bot or an agent sends a message to the user. The structure of the request body is:
{
// format version
"v": "1.1",
// marking that it is a message notification
"type": "message",
// chat platform and channel fields:
// the name of the chat platform.
"chatPlatform": "webchat" | "whatsapp" | "messenger" | "telegram" | "twitter" | …,
// whatsapp: user's phone number
// messenger, telegram or twitter: user id in platform.
"contactId": string,
// if the channel is whatsapp, bot account number
"whatsappNumber": "551149331774",
// if the channel is not whatsapp, id of the chat in chat platform
"chatIdInChatPlatform": "AR4Q1S3P1U",
// id of the chat channel in Botmaker
"chatChannelId": string,
// end of chat platform and channel fields.
// user fields:
// user id in Botmaker
"customerId": "NDRP2LQVX2C4G8DNEQCH",
// user's first and last name
"firstName": "Pedro",
"lastName": "Skateboard",
// date and time of user creation (format YYYYY-MM-DDThh:mm:ss.sssZ).
"customerCreationTime": "2021-02-28T23:59:00.147Z",
// date and start time of the session to which the messages belong (format YYYYY-MM-DDThh:mm:ss.sssZ).
"sessionCreationTime":"2021-03-08T19:28:45.147Z",
// end user fields
// messages: array. Multiple messages may be generated in response to a user message;
// this usually happens when the bot responds
"messages": [
{
// message id in Botmaker (the status notification refers to this id)
"_id_":"PHW3S2KV4VRWL17BBM1U",
// date and time of the message
"date":"2021-03-08T19:44:14.388Z",
// message text
"message": "Hello, how are you?",
// name of who generated the message. The user or operator name, or "Bot" if it was the bot
"fromName": "Ignacio F",
// category of who sent the message
"from": "bot" | "user" | "operator",
// flag marking if it is from the user
"fromCustomer": true | undefined,
// flag marking if it was a button (the text of "message" will be the label of the button)
"isButton": true | undefined,
// flag that indicates if it has image, video, audio or document
"hasAttachment": true | undefined,
// attachment urls
"image": "https://…",
"audio": "https://…",
"video": "https://…",
"file": "https://…",
// if the message was emitted by an operator (from == "operator"), the following fields will be sent: operatorId, operatorName, operatorEmail, operatorRole
// id of the operator in Botmaker
"operatorId": "bxj99dyfxEsdopib9ZuboIG5Tqr3",
"operatorName": "Pepe",
"operatorEmail": "pepe@domain.com",
"operatorRole": "ADMIN" | "CONFIGURATOR" | "SUPERVISOR" | "OPERATOR" | "OPERATOR" | "nameRolCustom".
// queue the user is in at the time of the message
"queue": "idColaAttention" | undefined
// if the message was generated by an intent (from == "bot"), the name of the intent is sent
"intentName": "Name of an Intent".
// specific to Whatsapp
// when the user sends their geolocation.
"location": "lat & long",
// text accompanying image
"caption": string,
// for hsm/templates with buttons:
"payload": string, // payload configured by user.
"button": string, // hsm button label
"templateName": string, // name of the template with button.
},
// other messages
{ … },
{ … }
],
// variable changes that occurred when these messages were generated
// map nameVariable -> newValue
"variables": {
"varName1": "new val 1",
"varName2": "new val 2"
}
}
Message status notifications (WhatsApp only)
These are notifications of the statuses the message goes through:
-
Sent: Botmaker sent the message to WhatsApp.
-
Delivered : the message was delivered to the recipient
-
Read: the message was read
-
Failed: the message failed to be sent
-
Deleted: message deleted
The structure of the notification is:
{
// format version
"v": "1.1",
"type": "status",
// bot id in Botmaker (in case several bots are pointing to the same webhook)
"businessId": string,
// whatsapp: user's phone number
// messenger, telegram or twitter: user id in platform,
"contactId": string,
// chat channel id in Botmaker
"chatChannelId": string,
// the name of the chat platform
"chatPlatform": webchat | whatsapp | messenger | telegram | twitter, …,
// if the channel is Whatsapp, the phone number used by the bot.
"whatsappNumber": "551149331774",
// id of the user in Botmaker
"customerId": string,
// message status
"status": "delivered" | "read",
// date and time of status change (format YYYYY-MM-DDThh:mm:ss.sssZ).
"statusChangeTime": "2021-03-01T00:00:00.000Z",
// id of the message in Botmaker that changed status (this id refers to some outgoing message id, from bot or operator).
"messageId": string,
// for when the message is sent by Botmaker api
"clientPayload": string
}
Applying formatting to messages via the API
It is possible to apply simple formatting to the text of messages to be sent to users, e.g. "Hi, John". For more information, please refer to the WhatsApp Help Center - How to format your messages documentation.
Remember to visit our Help Center for more information
Written by Botmaker Team
Updated: 3/02/2022