Botmaker’s platform provides extensive API documentation that can be used for various purposes. This article focuses exclusively on sending and receiving messages via API. To do this, you'll need to use the messaging API and enable a webhook so that a parallel server can receive messages from the end user.

How to Get Credentials to Access the API?

To access the API, you need to obtain an access token. Follow these steps:

Once logged into the Botmaker platform, go to Botmaker API within the Settings menu.
Select the Integrations option and then select Botmaker API.

Generate a token using the Generate Credentials button or use an existing one.

This token will be used in the header of your API requests.

How to Send a Message?

Messages are sent via the messages endpoint, specifically send messages. You can test the API via the Documentation tab.
To do this, select the endpoint in Chat Actions and then the send messages API.

To test, follow these steps:

• Enter your token in the access-token field under Authentication.
• In Body, replace the channelId with the desired channel ID. You can find this ID under the List Channels endpoint in Channels.
• Replace the contactId with the contact’s ID. If the conversation is through WhatsApp, this ID will be the customer’s phone number; on Webchat, it’s a generated ID.
• Define the message you want to send using the documentation examples such as: text message, button menu, media, location, and contact.
• The webhookPayload field can define additional variables to be sent via webhook notification to your server.

Formatting Messages

You can apply simple formatting to the text of the messages you send to users:

• Italics: Wrap your message in underscores _like this_.
• Bold: Wrap your message in asterisks *like this*.
• Strikethrough: Wrap your message in tildes ~like this~.
• Monospace: Wrap your message in triple backticks ```like this```.

API Responses

There are 3 standard API response types:

• 200: Successfully sent
• 400: Body parameter or chat ID error
• 429: Requests per second limit exceeded

You can follow the JSON examples generated directly in the API Documentation tab.

How to Receive Messages?

As soon as a user sends a message to your WhatsApp, we forward that message to your webhook. That way, you’ll receive all messages from your users in your own system.

For detailed information on how to manage your webhooks, see the article:
How to Integrate Webhooks?

Webhook Notification Format

There are 3 types of webhooks available on the platform:

• Message and Status
• WhatsApp Management
• Asynchronous API Results

Message Notifications

To receive messages, we use the Message and Status type. The information you receive depends on which data is needed for your operation.

In the configuration screen, you should be able to define the following:

• Enter the URL where the webhook will send messages: This URL is the public endpoint to communicate with your webhook. It’s where we will send events.
• Security Token: You can add one, use the suggested token, or leave it blank. If needed, we can add a token to be sent as authentication to your endpoint. It will be added in the header with the key auth-bm-token.
• Add or remove channels connected to this webhook (at least 1 required): Configure the user’s entry channel to monitor and send events to your server. At least one channel is required, and you can configure several (e.g., WhatsApp, Webchat, Instagram).
• Include the types of messages you want to send to your webhook: We will notify you of the message/event source sent to your webhook. Options include:
• • Bot Messages: All messages generated by the chatbot.
  • User Messages: All incoming messages sent by the user on any channel (WhatsApp, Webchat, Instagram).
  • Agent Messages: Messages sent by a human agent.
  • Message Status: Logs events of sent messages (Delivered, Read, Received, Error).
  • HSM Status Only: Logs status events related to templates (Delivered, Read, Received, Error).
  • Event Messages: Sends general platform events like user blocked/unblocked, bot changed, etc.
• Do you want to include change variables in the message?: Enabling this will send variables with declared values during the bot flow. Variables will only be sent at the moment they are declared.