How to use Botmaker API?
In this article, you will learn how to use Botmaker API.
Estimated reading time: 10 minutes
Data model
Customer
In a data model, a customer symbolizes a user or customer who has interacted with the bot. All interactions that take place on the same channel (WhatsApp, Webchat, Messenger, Twitter, Google Assistant, etc.) will continue to refer to the same customer.
The customer consists of the following data:
-
BUSINESS_ID:** ID of the bot to which the user belongs. For the same bot, all clients will have the same ID number.
-
CREATION_TIME:**Date of creation of the client, i.e. of its first interaction.
-
CHAT_PLATFORM_ID:** The platform on which the user interacted. It can be WhatsApp, Webchat, Messenger, Twitter, Google Assistant, Microsoft Teams, etc.
-
CHAT_CHANNEL_ID:** The channel through which the user interacts on the platform. It is an ID formed by the platform + the channel ID. Different Facebook pages for example.
-
PLATFORM_CONTACT_ID:** Specific ID generated by the channel platform used. Together with the channel ID, it allows identifying the user individually.
-
BOT_MUTED:** Indicates if the bot is muted for this user. When the bot is muted, it will not send automatic responses to the user. The bot is downgraded again after 60 minutes of user inactivity.
-
PENDING_MSGS:** Number of messages that the bot did not understand and are pending to be read by a human agent.
-
FIRST_NAME and LAST_NAME**: First and last name of the user respectively.
-
**LAST_SEEN:** Date when the user last spoke.
-
PICTURE_URL:**User's picture in the channel to which they belong.
-
Variables:** The user is also composed of variables, which are data obtained in interactions with the bot.
These values are part of the client and will appear in the API with the last value obtained from a given variable.
Variables are configured (as in programming languages) to store their possible values and can be viewed or modified on the platform, in the variables section.
- Tags : Tags that are applied to a user for later identification. The tag can be considered as a boolean variable (on or off).
A user has a tag for the following reasons:
-
The user discusses a specific topic with the bot, which automatically tags the user for that topic.
-
The bot tags the user specifically for later viewing of metrics or audience generation to send push messages.
Messages
You can send messages to users using the agent's console, generating mass notifications and scheduling sending by different triggers. You can also use the Botmaker API to trigger messages programmatically from a system.
It is important to keep in mind that when using this type of service, it is recommended to have a webhook integrated with your account in order to receive all the messages sent by users.
For more information on this topic, please refer to the following article: How to integrate webhooks?
**message/v3**
[https://go.botmaker.com/api/v1.0/message/v3]
The purpose of this endpoint is to send a message to a user within a conversation.
These are some of the message object fields.
-
chatPlatform - Platform through which the communication with the user is being carried out.
-
chatChannelNumber - Account phone number or channel ID within the platform.
-
platformContactId - User's phone number or ID on the platform.
-
messageText - Text message to send.
-
audioURL - URL to the audio file to send.
-
fileURL - URL to the document to send.
-
videoURL - URL to the video file to send.
-
imageURL - URL to the image file to send.
-
clientPayload - Free text field. Typically used to place a custom ID and track the message response. Because once we assign a value to it, we will receive this field in our webhook with the assigned value in every message from the user until it is replaced by a new value. It is important that if this parameter is used, the value of this field is changed in each message sent.
Example:
The following is an example of how the service should be used with a call via HTTP Post to the Rest API with 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!
**Note:**The 'messageText' parameter is not combinable with the multimedia parameters. That is, I can send a text message, or I can send a multimedia file where there will be no 'messageText' parameter.
Intents
Botmaker allows you to send all types of multimedia messages supported by WhatsApp and other channels. To do this, you will need to create a template or custom message.
For more information, you can read the following articles:
How to send templates and notifications through Notifications engine?
How to create templates via API?
** /intent/v2 **
https://go.botmaker.com/api/v1.0/intent/v2
It is intended to activate a template or intent for a specific user, with the user's contact number as a parameter for identification. It has the possibility of adding additional parameters to feed the variables of the particular user.
These are some of the fields of the intent object.
-
chatPlatform : Platform through which the communication with the user is being carried out.
-
chatChannelNumber : Phone number of the account or channel ID within the platform.
-
platformContactId : User's phone number or ID in the platform.
-
ruleNameOrId : ID or name of the intent you want to send to the user.
-
params : List of variables and the values you want to assign for the user. It can be empty.
Example :
The following is an example of how the service should be constructed with a call via HTTP POST to the Rest API with a JSON:
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": {
"varName": "varValue"
}
}'
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
Metrics
The Botmaker API allows obtaining a variety of information from the user through Metrics methods. With all this information, and by processing it, it is possible to generate different types of metrics.
For more information on this topic, you can refer to the following articles:
Remember to visit our Help Center for further information.
Written by: Botmaker Team
Updated: 03/21/2022