API Reference

MessageBird's WhatsApp Business allows you to send and receive WhatsApp messages for alerts, notifications, customer support, as well as two-factor authentication. You’ll be able to add all WhatsApp Business features through a single API.

The WhatsAPP API uses HTTP verbs and a RESTful endpoint structure with an access key that is used as the API Authorization. Request and response payloads are formatted as JSON using UTF-8 encoding and URL encoded values.

Template Messages for WhatsApp

Template messages are used to start a conversation with a customer or reply to a customer's message outside the 24-hour window.

They use one of your pre-approved WhatsApp Templates (alerts, appointment reminders, shipping notifications, etc) and need to be submitted and approved by WhatsApp before they can be used. You can submit WhatsApp Templates via the WhatsApp Template Manager on the MessageBird Dashboard.

As they are common reusable messages a business may want to send, this allows a firm to send just the template identifier along with the appropriate parameters instead of the full message content. It also allows for localization of the message and decreases the possibility of being blocked on the first contact as the message is pre-approved by WhatsApp.

To initiate a conversation with a client, WhatsApp requires you to use a pre-approved message template called a Message Template (previously called a Highly Structured Message or HSM).

Message Templates are message formats for common reusable messages a business may want to send. This allows a firm to send just the template identifier along with the appropriate parameters instead of the full message content. It also allows for localization of the message and decreases the possibility of being blocked on the first contact as the message is pre-approved by WhatsApp.

How to Send a Message Template (HSM)

A Message Template (HSM message) content can be provided anywhere where other message content is allowed, via POST /v1/send, POST /conversations/start or POST /conversations/{id}/messages (the {id} refers to the conversation ID).

Check out the steps on how to submit your Message Template (HSM messages) for pre-approval by WhatsApp and our step-by-step quickstart on how to write and send a WhatsApp Templates.

Example template message

Hi {{1}}, your order has been shipped and should arrive {{2}}

Example request using POST /send

curl -X POST "https://conversations.messagebird.com/v1/send" \
  -H "Authorization: AccessKey test_gshuPaZoeEG6ovbc8M79w0QyM" \
  -H "Content-Type: application/json" \
  -d '{
    "to": "+31612345678",
    "type": "hsm",
    "from": "aa4c8e7cee664341a22ef9bfd9f52477",
    "content":{
      "hsm": {
        "namespace": "5ba2d0b7_f2c6_433b_a66e_57b009ceb6ff",
        "templateName": "order_update",
        "language": {
        "policy": "deterministic",
        "code": "en"
        },
        "params": [
          {"default": "Bob"},
          {"default": "tomorrow!"}
        ]
      }
    }
  }'

Example response

{
  "message": {
    "id": "2e15efafec384e1c82e9842075e87beb",
    "status": "accepted"
  }
}

Example request using POST /conversations/start

curl -X POST "https://conversations.messagebird.com/v1/conversations/start" \
  -H "Authorization: AccessKey test_gshuPaZoeEG6ovbc8M79w0QyM" \
  -H "Content-Type: application/json" \
  -d '{
    "to": "+31612345678",
    "type": "hsm",
    "channelId": "aa4c8e7cee664341a22ef9bfd9f52477",
    "content":{
    "hsm": {
      "namespace": "5ba2d0b7_f2c6_433b_a66e_57b009ceb6ff",
      "templateName": "order_update",
      "language": {
      "policy": "deterministic",
      "code": "en"
      },
      "params": [
        {"default": "Bob"},
        {"default": "tomorrow!"}
      ]
    }
  }'

Example response

{
    "id": "2e15efafec384e1c82e9842075e87beb",
    "contactId": "a621095fa44947a28b441cfdf85cb802",
    "contact": {
      "id": "a621095fa44947a28b441cfdf85cb802",
      "href": "https://rest.messagebird.com/1/contacts/a621095fa44947a28b441cfdf85cb802",
      "msisdn": 316123456789,
      "firstName": "Jen",
      "lastName": "Smith",
      "customDetails": {
        "custom1": null,
        "custom2": null,
        "custom3": null,
        "custom4": null
      },
      "createdDatetime": "2018-06-03T20:06:03Z",
      "updatedDatetime": null
    },
    "channels": [
      {
        "id": "aa4c8e7cee664341a22ef9bfd9f52477",
        "name": "My WhatsApp",
        "platformId": "whatsapp",
        "status": "active",
        "createdDatetime": "2018-08-28T11:56:57Z",
        "updatedDatetime": "2018-08-29T08:16:33Z"
      }
    ],
    "status": "active",
    "createdDatetime": "2018-08-13T09:17:22Z",
    "updatedDatetime": "2018-08-29T07:35:48Z",
    "lastReceivedDatetime": "2018-08-29T07:35:48Z",
    "lastUsedChannelId": "619747f69cf940a98fb443140ce9aed2",
    "lastUsedPlatformId": "whatsapp",
    "messages": {
    "totalCount": 24,
    "href": "https://conversations.messagebird.com/v1/conversations/2e15efafec384e1c82e9842075e87beb/messages",
    "lastMessageId": "9d5d5921f5b34f8db415a2397eb762f9",
    }
  }

How to Send a Media Template Message

Media templates must be pre-approved by WhatsApp. Media templates can be submitted to WhatsApp by sending an email to our Customer Support team (support@messagebird.com), who will ask for the required template data. Once this is received, the Support team will then confirm with you if the template has been approved by WhatsApp. Please note: media template submissions are not currently possible through the WhatsApp Template Manager.

The Media Template Message content must be provided in the content.hsm property via POST /send, POST /conversations/start or POST /conversations/{id}/messages. Currently, we support two media types - document and image.

Example media template message

Header:
Document content

Body:
Sorry for the delay. Your flight {{1}} is rescheduled to {{2}}. You can find the attachment document here.

Footer:
Best Regard, Messagebird

Example request using POST /send

curl -X POST "https://conversations.messagebird.com/v1/send" \
  -H "Authorization: AccessKey test_gshuPaZoeEG6ovbc8M79w0QyM" \
  -H "Content-Type: application/json" \
  -d '{
    "to": "+31612345678",
    "type": "hsm",
    "from": "aa4c8e7cee664341a22ef9bfd9f52477",
    "content": {
      "hsm": {
        "namespace": "20332cd4_f095_b080_d255_35677159aaff",
        "templateName": "test_media_complex",
        "language": {
          "policy": "deterministic",
          "code": "en"
        },
        "components": [
          {
            "type": "header",
            "parameters": [
              {
                "type": "document",
                "document": {
                  "url": "https://example.com/flight.pdf"
                }
              }
            ]
          },
          {
            "type": "body",
            "parameters": [
              {
                "type": "text",
                "text": "TK 1073"
              },
              {
                "type": "text",
                "text": "18.04.2020"
              }
            ]
          }
        ]
      }
    }
  }'

Example response

{
  "message": {
    "id": "2e15efafec384e1c82e9842075e87beb",
    "status": "accepted"
  }
}

Example request using POST /conversations/start

curl -X POST "https://conversations.messagebird.com/v1/conversations/start" \
  -H "Authorization: AccessKey test_gshuPaZoeEG6ovbc8M79w0QyM" \
  -H "Content-Type: application/json" \
  -d '{
    "channelId": "aa4c8e7cee664341a22ef9bfd9f52477",
    "to": "+31612345678",
    "type": "hsm",
    "content":{
    "hsm": {
      "namespace": "20332cd4_f095_b080_d255_35677159aaff",
      "templateName": "test_media_complex",
      "language": {
        "policy": "deterministic",
        "code": "en"
      },
      "components": [
        {
          "type": "header",
          "parameters": [
            {
              "type": "document",
              "document": {
                "url": "https://example.com/flight.pdf"
              }
            }
          ]
        },
        {
          "type": "body",
          "parameters": [
            {
              "type": "text",
              "text": "TK 1073"
            },
            {
              "type": "text",
              "text": "18.04.2020"
            }
          ]
        }
      ]
    }
  }
}'

Example response

{
  "id": "2ec3d1e8725f41b1933906426738e6a5",
  "conversationId": "2e15efafec384e1c82e9842075e87beb",
  "channelId": "aa4c8e7cee664341a22ef9bfd9f52477",
  "platform": "whatsapp",
  "status": "pending",
  "type": "hsm",
  "direction": "sent",
  "content": {
    "hsm": {
      "namespace": "20332cd4_f095_b080_d255_35677159aaff",
      "templateName": "test_media_complex",
      "language": {
        "policy": "deterministic",
        "code": "en"
      },
      "components": [
        {
          "type": "header",
          "parameters": [
            {
              "type": "document",
              "document": {
                "url": "https://example.com/flight.pdf"
              }
            }
          ]
        },
        {
          "type": "body",
          "parameters": [
            {
              "type": "text",
              "text": "TK 1073"
            },
            {
              "type": "text",
              "text": "18.04.2020"
            }
          ]
        }
      ]
    }
  },
  "createdDatetime": "2018-08-29T13:53:44.642664784Z",
  "updatedDatetime": "2018-08-29T13:53:44.673850825Z"
}

MessageBird WhatsApp Sandbox

The MessageBird WhatsApp Sandbox allows you to try and prototype WhatsApp Business in a developer environment without going through the approval process.

Check out our quickstart for Getting Started with MessageBird's WhatsApp Sandbox in 6 easy steps.

A Message Template (HSM message) content can be provided anywhere where other message content is allowed, via POST /conversations/start or POST /conversations/{id}/messages

The id in the URL refers to the conversation ID.

Check out our quickstart for Getting Started with MessageBird's WhatsApp Sandbox in 6 easy steps.

Webhooks with the MessageBird WhatsApp Sandbox

You can now use Conversations Webhooks endpoint with the WhatsApp Sandbox to enable the delivery of real-time notifications to any endpoint on your own server.

The WhatsApp Sandbox currently supports the following webhook events:

Name	Description
message.created	A new message has been created. Triggered for both sent and received messages.

Head over to Webhooks for more details.

Please keep in mind that we do not support message.updated events for the sandbox channel at this time.

WhatsApp errors

Code	Message
301	The message failed to send. Please check your message is valid, including any media, and/or try again later.
302	The contact is not registered on WhatsApp.
470	Failed to send message because you are outside the support window for freeform messages to this user. Please use a valid message template.
308	Message rejected because it exceeded the TTL before it was sent to WhatsApp.

Is this page useful?

Next upApi

Questions?

We’re always happy to help with code or other doubts you might have! Check out our Quickstarts, API Reference, Tutorials, SDKs, or contact our Support team.

Cookie Settings