Botmaker API
Search…
English
WhatsApp API
Powered By GitBook
WhatsApp API
How to send and receive WhatsApp messages?
Botmaker offers you official access for sending and receiving WhatsApp messages for it's almost 1.5 billion users around the world.
You'll be able to send messages without the need of programming, through the manual operation or activating your Bot. Also it is possible accessing Botmaker API for connecting your apps.

Initial considerations

  • Your account's approval process only happens one time. When approved, you'll be immediately able to start using our sandbox for drawing your customer service, whether it's manual or automatic.
  • Once integrated to Botmaker, there's two ways of starting a chat with your customers:
    • Users can start chatting with your brand: for this, you can publish your WhatsApp number on ads, websites, or landing pages, using WhatsApp's link - wa.me/your_number/?text=Hi!. You can learn more here.
    • You can start chatting with your users - even if they haven't talked with you before. In this case, it's important that you ask for user's opt-in on your website, on a form, via email, etc. You can learn more here.
    ​
  • WhatsApp protect it's users against SPAM. Users can contact you for any reason, but in case you want to contact him using a template, it should be for one the approved reasons. Bellow, there are all the template categories:
    • Account Update
    • Alert Update
    • Appointment Update
    • Issue Resolution
    • Payment Update
    • Personal Finance Update
    • Reservation Update
    • Shipping Update
    • Ticket Update
    • Transportation Update
WhatsApp doesn't allows sending marketing or comercial themed notifications.

Receiving messages

It's possible to notify a system of every message send to you by your users. For it, you should set a webhook.
  • Contact our support sending your endpoint. For example: https://example.com/income​
    • Your endpoint must be a http code 200, and have a valid certified https. Also, it needs to be available all the time and answer in less than 10 seconds.
  • Once sent, we are going to activate it. We'll let you know when it's concluded. You'll start receiving messages following Google's PubSub policies: signed messages, 7-day messages preservation, etc. Learn more here.
  • The following example shows a typical user message:
    1
    {
    2
    "CHAT_PLATFORM_ID": "message_platform", // for instance whatsapp
    3
    "MESSAGE": "Hola!", // the user message text
    4
    "CREATION_TIME": "a_date", // ISO 8601 for message time, for instance 2018-09-03T14:30:24.578Z
    5
    "FROM_NAME": "user_name", // name of user if possible
    6
    "CUSTOMER_ID": "user_id", // unique id of user
    7
    "_id_": "message_id", // unique id of message
    8
    "FROM": "phone_number", // user phone number
    9
    "SESSION_CREATION_TIME": "session_id", // chat session id
    10
    ​
    11
    // other less important fields are also inclused in the message
    12
    ...
    13
    }
    Copied!
  • Multimedia files are supported (voice messages, docs, images, etc):
    1
    {
    2
    "FROM_NAME": "user_name", // name of user if possible
    3
    "IMAGES_URLS": [
    4
    "https://botmaker.com/hostedImageByUser.png"
    5
    ],
    6
    ...
    7
    }
    Copied!

Sending messages

It's possible to use Botmaker's API for sending messages to your users though your system. For this, we'll send you a API access token.
  • Contact our support asking for your API access token. Once you have it, it'll be possible to call HTTP Post on our API rest with a JSON:
    1
    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'
    2
    ​
    3
    # your_access_token: ey...
    4
    # your_phone: +55135433...
    5
    # user_phone: +5512324314..
    6
    # message_to_send: Hi!
    Copied!
  • The answer you'll receive is a http code 200 with a JSON indicating the ID of the generated message:
    1
    {
    2
    "id": "id_del_mensaje"
    3
    }
    4
    ​
    Copied!
Every time a message is sent to the user, it'll be checked your Botmaker account balance. If the account is close to have no credit, the service will give you a http code 403 - Forbidden, indicating that there is no credit available to send that message:
1
{
2
"error": {
3
"code": 101,
4
"message": "Insufficient credit"
5
}
6
}
Copied!
Every time a message is sent to the user, it'll be checked if the message is going to be rejected by WhatsApp, since the user didn't talked with you on the last 24 hours. See Template Messages section for more info.
1
{
2
"error": {
3
"code": 201,
4
"message": "User window is over 24 hours"
5
}
6
}
Copied!

Template Messages

WhatsApp allows you sending messages for your users while they are inside the 24 hour window - windows are opened after user's last sent message. Outside the window, messages must be sent using the endpoint intent and following the next.
Remind that every template must be approved by Facebook before you start sending them.
  • With it approved, call the endpoint:
    1
    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'
    2
    ​
    3
    # your_token: your access token
    4
    # your_phone_number: whatsapp number of yours
    5
    # user_phone_number: whatsapp number of user
    6
    # rule_name: botmaker rule name
    Copied!

Multimedia Messages

Botmaker allows you sending every multimedia formats supported by WhatsApp and other channels. For this, you should use the common service for sending messages and specify the media URL:
1
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","audioURL": "audio_to_send", "imageURL": "image_to_send", "fileURL", "file_to_send"}' 'https://go.botmaker.com/api/v1.0/message/v3'
2
​
3
# your_access_token: ey...
4
# your_phone: +55135433...
5
# user_phone: +5512324314..
6
# audio_to_send: https://....my_audio.mp3
7
# image_to_send: https://....my_photo.jpeg
8
# file_to_send: https://....my_file.pdf
Copied!
Choose one or more media formats. Here is the list with all the files supported by WhatsApp.

Message read or delivered status

Your endpoint will receive updates on the status of the message you just sent.
  1. 1.
    Delivered indicates that the message was delivered.
  2. 2.
    Read indicates that the message was read.
1
{
2
"CHAT_PLATFORM_ID": "message_platform", // for instance whatsapp
3
"CREATION_TIME": "a_date", // ISO 8601 for message time, for instance 2018-09-03T14:30:24.578Z
4
"CUSTOMER_ID": "user_id", // unique id of user
5
"_id_": "message_id", // unique id of message
6
"FROM": "phone_number", // user phone number
7
"STATUS": "el_cambio_status" // message read or delivered
8
}
Copied!
These status won't be received depending on the user's WhatsApp privacy settings.

Applying messages formats

It's possible to apply basic formats on the texts that are going to be sent for your users. For more info, click here.
Last modified 2yr ago
Copy link
Contents
Initial considerations
Receiving messages
Sending messages
Template Messages
Multimedia Messages
Message read or delivered status
Applying messages formats