API Reference

The Integration API uses HTTP verbs and a RESTful endpoints 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.

Base URL

All the endpoints referenced in this documentation have the following base URL:

https://integrations.messagebird.com

Authorization

You'll need to set an access key to authenticate yourself. You can create, manage, and retrieve your API keys from the MessageBird Dashboard.

To provide the access key, set the Authorization header in the form of AccessKey {accessKey}.

Formats and Headers

All API responses are in JSON. You're required to send the Accept header with the value application/json with each request.

Both POST and PUT requests to the API must contain a JSON-formatted payload in the request body.

Errors

MessageBird uses standard HTTP status codes to indicate success or failure of an API request:

Codes in the 2xx range indicate that a request was processed successfully
The 4xx range indicates that there was a client side error - for example, due to authentication or a missing or wrong parameter. Don't worry, the body of the response includes a JSON-formatted response that tells you exactly what is wrong. If you're stuck, feel free to contact support; we're happy to help you out.
A 5xx status code indicates that something went wrong on server-side, and you can retry using standard exponential backoff

Templates

Some platforms, like WhatsApp and Facebook, don't allow business to send messages outside the support window, which is 24hs after the end-user send an inbound message. The only message types allowed outside support window is template message, which must be pre-approved by the platform. Using MessageBird's Integrations API, you can create, fetch and delete your templates. With WhatsApp templates, they are created under a WhatsApp Business Account (WABA) and can only be used for phone numbers within the same WABA.

Currently the template management is only supported to WhatsApp platform.

Currently, templates created in the Facebook Templates Manager are not automatically created in Integrations API, and, therefore, they won't be available in other MessageBird products like Inbox and FlowBuilder, however, those templates can still be used for sending template messages through Conversations API.

Create template

Create a template.

Template categories are changing from March 15th - please see TemplateCategory

Templates can have maximum 1 header, 1 body, 1 footer and 2 buttons.

If you choose to provide examples for template components, then all of them should have the same number of examples. A template request with a mismatch on the number of examples provided across components will be rejected.

POST /v2/platforms/whatsapp/templates

Request

Parameter	Type	Description	Required
name	string	The name of template.	Yes
language	TemplateLanguage	The language of the template.	Yes
components	Array of TemplateComponent	An array of template components.	Yes
category	TemplateCategory	The template category.	Yes
wabaId	string	The ID of the WABA for which the template should be created. If not supplied, the first WABA linked to your account will be used	No
allowCategoryChange	boolean	This param allows Meta to assign correct category they determined to be appropriate. The param starts working from March 15, 2023	No

The following example illustrates how to create a template with an image header, a body, a footer and two buttons: a phone number button and a URL button with a variable.

curl -X "POST" "https://integrations.messagebird.com/v2/platforms/whatsapp/templates" \
     -H 'Authorization: AccessKey test_gshuPaZoeEG6ovbc8M79w0QyM' \
     -H 'Content-Type: application/json; charset=utf-8' \
     -d $'{
  "language": "en",
  "components": [
    {
      "type": "HEADER",
      "format": "IMAGE",
      "example": {
        "header_url": ["https://mycdn.com/image.jpeg"]
      }
    },
    {
      "type": "BODY",
      "text": "Hello {{1}}! This is a sample template. {{2}}",
      "example": {
        "body_text": [["John", "bye!"]]
      }
    },
    {
      "type": "FOOTER",
      "text": "Sample footer"
    },
    {
      "type": "BUTTONS",
      "buttons": [
        {
          "type": "PHONE_NUMBER",
          "text": "Call us!",
          "phone_number": "+31 0 0000-0000"
        },
        {
          "type": "URL",
          "text": "Watch",
          "url": "https://www.youtube.com/watch?v={{1}}",
          "example": ["https://www.youtube.com/watch?v=abcd"]
        }
      ]
    }
  ],
  "name": "sample_whatsapp_template",
  "category": "TRANSACTIONAL"
}'

The template looks like the following.

Response

Parameter	Type	Description
name	string	Template name.
language	TemplateLanguage	The language of template.
category	TemplateCategory	The template category.
components	Array of TemplateComponent	An array of template components.
status	TemplateStatus	The template status, in this case: NEW
wabaId	string	The Template WABA ID.
namespace	string	The Tempalte WABA Namespace.

{
  "name": "sample_whatsapp_template",
  "language": "en",
  "status": "NEW",
  "components": [
    {
      "type": "HEADER",
      "format": "IMAGE",
      "example": {
        "header_url": ["https://mycdn.com/image.jpeg"]
      }
    },
    {
      "type": "BODY",
      "text": "Hello {{1}}! This is a sample template. {{2}}",
      "example": {
        "body_text": [["John", "bye!"]]
      }
    },
    {
      "type": "FOOTER",
      "text": "Sample footer"
    },
    {
      "type": "BUTTONS",
      "buttons": [
        {
          "type": "PHONE_NUMBER",
          "text": "Call us!",
          "phone_number": "+31 0 0000-0000"
        },
        {
          "type": "URL",
          "text": "Watch",
          "url": "https://www.youtube.com/watch?v={{1}}",
          "example": ["https://www.youtube.com/watch?v=abcd"]
        }
      ]
    }
  ],
  "category": "TRANSACTIONAL",
  "createdAt": "2021-08-06T06:34:40.815772829Z",
  "updatedAt": "2021-08-06T06:34:40.815772829Z"
}

Response codes

Code	Description
201	Template created, it can't be used yet because must be approved by Facebook.
400	The HTTP request is malformed, the details should be available in the HTTP response body.
401	The request is not authenticated, please check your access key.
429	Too many requests, please retry using standard exponential backoff
500	Internal server error, please retry using standard exponential backoff

Update template

Update a given template by name and language.

Template categories are changing from March 15th - please see TemplateCategory

Templates can have maximum 1 header, 1 body, 1 footer and 2 buttons.

PUT /v2/platforms/whatsapp/templates/{name}/{language}

Request

Parameter	Type	Description	Required
components	Array of TemplateComponent	An array of template components.	Yes
category	TemplateCategory	The template category.	No
wabaId	string	The ID of the WABA for which the template should be created. If not supplied, the first WABA linked to your account will be used	Yes

The following example illustrates how to update a template with an image header, a body, a footer and two buttons: a phone number button and a URL button with a variable.

curl -X "PUT" "https://integrations.messagebird.com/v2/platforms/whatsapp/templates/sample_whatsapp_template/en" \
     -H 'Authorization: AccessKey test_gshuPaZoeEG6ovbc8M79w0QyM' \
     -H 'Content-Type: application/json; charset=utf-8' \
     -d $'{
  "components": [
    {
      "type": "HEADER",
      "format": "IMAGE",
      "example": {
        "header_url": ["https://mycdn.com/image.jpeg"]
      }
    },
    {
      "type": "BODY",
      "text": "Hello {{1}}! This is a sample template. {{2}}",
      "example": {
        "body_text": [["John", "bye!"]]
      }
    },
    {
      "type": "FOOTER",
      "text": "Sample footer"
    },
    {
      "type": "BUTTONS",
      "buttons": [
        {
          "type": "PHONE_NUMBER",
          "text": "Call us!",
          "phone_number": "+31 0 0000-0000"
        },
        {
          "type": "URL",
          "text": "Watch",
          "url": "https://www.youtube.com/watch?v={{1}}",
          "example": ["https://www.youtube.com/watch?v=abcd"]
        }
      ]
    }
  ],
  "category": "MARKETING"
}'

Response

Parameter	Type	Description
name	string	Template name.
language	TemplateLanguage	The language of template.
category	TemplateCategory	The template category.
components	Array of TemplateComponent	An array of template components.
status	TemplateStatus	The template status, in this case: NEW
wabaId	string	The Template WABA ID.
namespace	string	The Tempalte WABA Namespace.

{
  "name": "sample_whatsapp_template",
  "language": "en",
  "status": "APPROVED",
  "components": [
    {
      "type": "HEADER",
      "format": "IMAGE",
      "example": {
        "header_url": ["https://mycdn.com/image.jpeg"]
      }
    },
    {
      "type": "BODY",
      "text": "Hello {{1}}! This is a sample template. {{2}}",
      "example": {
        "body_text": [["John", "bye!"]]
      }
    },
    {
      "type": "FOOTER",
      "text": "Sample footer"
    },
    {
      "type": "BUTTONS",
      "buttons": [
        {
          "type": "PHONE_NUMBER",
          "text": "Call us!",
          "phone_number": "+31 0 0000-0000"
        },
        {
          "type": "URL",
          "text": "Watch",
          "url": "https://www.youtube.com/watch?v={{1}}",
          "example": ["https://www.youtube.com/watch?v=abcd"]
        }
      ]
    }
  ],
  "category": "MARKETING",
  "createdAt": "2021-08-06T06:34:40.815772829Z",
  "updatedAt": "2021-08-06T06:34:40.815772829Z"
}

Response codes

Code	Description
200	Template updated.
400	The HTTP request is malformed, the details should be available in the HTTP response body.
400	Template not found.
401	The request is not authenticated, please check your access key.
429	Too many requests, please retry using standard exponential backoff
500	Internal server error, please retry using standard exponential backoff

List templates

List all your templates.

GET /v3/platforms/whatsapp/templates

Request

Parameter	Type	Description	Required
offset	integer	The number of objects to skip from the first.	No. Default: 0
limit	integer	The number of maximum objects to return on each request. Maximum: 50	No. Default: 50
wabaId	string	Optional filter for templates belonging to a specific WABA. Do not specify channelId if wabaId was provided.	No
channelId	string	Optional filter for templates that can be sent via the specified channel. Do not specify wabaId if channelId was provided.	No

curl -X GET "https://integrations.messagebird.com/v3/platforms/whatsapp/templates" \
  -H "Authorization: AccessKey test_gshuPaZoeEG6ovbc8M79w0QyM" \
  -H "Content-Type: application/json"

Response

Parameter	Type	Description
offset	integer	The number of objects skipped.
limit	integer	The number of maximum objects returned on each request.
count	integer	Number of templates returned.
totalCount	integer	The number of total templates that can be retrieved through pagination.
items	Array of Template	List of templates.

{
  "count": 2,
  "limit": 50,
  "offset": 0,
  "totalCount": 2
  "items": [
    {
      "name": "sample_whatsapp_template",
      "language": "en",
      "status": "REJECTED",
      "components": [
        {
          "type": "HEADER",
          "format": "IMAGE"
        },
        {
          "type": "BODY",
          "text": "Hello {{1}}! This is a sample template."
        },
        {
          "type": "FOOTER",
          "text": "Sample footer"
        },
        {
          "type": "BUTTONS",
          "buttons": [
            {
              "type": "PHONE_NUMBER",
              "text": "Call us!",
              "phone_number": "+31 0 0000-0000"
            },
            {
              "type": "URL",
              "text": "Watch",
              "url": "https://www.youtube.com/watch?v={{1}}"
            }
          ]
        }
      ],
      "category": "TRANSACTIONAL",
      "rejectedReason": "(#192) Param components[3]['buttons'][0]['phone_number'] is not a valid phone number.",
      "createdAt": "2021-08-06T06:34:40.815772829Z",
      "updatedAt": "2021-08-06T06:35:11.74973411Z"
    },
    {
      "name": "hsm_test2121213232",
      "language": "en_US",
      "status": "REJECTED",
      "components": [
        {
          "type": "BODY",
          "text": "Hello {{1}}! Let's send out first message template"
        }
      ],
      "id": "1964838697016877",
      "category": "RESERVATION_UPDATE",
      "rejectedReason": "INVALID_FORMAT",
      "createdAt": "2021-07-26T16:10:55.718436747Z",
      "updatedAt": "2021-07-26T16:28:17.558421505Z"
    },
    {
      "name": "name121132112",
      "language": "en",
      "status": "REJECTED",
      "components": [
        {
          "type": "BODY",
          "format": "TEXT",
          "text": "hello world!"
        },
        {
          "type": "BUTTONS",
          "format": "TEXT",
          "buttons": [
            {
              "type": "QUICK_REPLY",
              "text": "Do you really?"
            }
          ]
        }
      ],
      "category": "TRANSACTIONAL",
      "rejectedReason": "component of type BODY has unexpected field(s) (format)",
      "createdAt": "2021-07-21T14:31:42.791116435Z",
      "updatedAt": "2021-07-21T14:37:13.002058598Z"
    }
  ]
}

List templates by name

List your templates given a name.

GET /v2/platforms/whatsapp/templates/{name}

Request

Attribute	Type	Description
name	string	The name of the template.
wabaId	string	Optional filter for templates belonging to a specific WABA. If not supplied, the template will be fetched using the first WABA linked to your account. Do not specify channelId if wabaId was provided.
channelId	string	Optional filter for templates that can be sent via the specified channel. If not supplied, the template will be fetched using the first WABA linked to your account. Do not specify wabaId if channelId was provided.

curl -X GET "https://integrations.messagebird.com/v2/platforms/whatsapp/templates/sample_whatsapp_template" \
  -H "Authorization: AccessKey test_gshuPaZoeEG6ovbc8M79w0QyM" \
  -H "Content-Type: application/json"

Response

An array of Template objects.

[
  {
    "name": "sample_whatsapp_template",
    "language": "en",
    "status": "REJECTED",
    "components": [
      {
        "type": "HEADER",
        "format": "IMAGE"
      },
      {
        "type": "BODY",
        "text": "Hello {{1}}! This is a sample template."
      },
      {
        "type": "FOOTER",
        "text": "Sample footer"
      },
      {
        "type": "BUTTONS",
        "buttons": [
          {
            "type": "PHONE_NUMBER",
            "text": "Call us!",
            "phone_number": "+31 0 0000-0000"
          },
          {
            "type": "URL",
            "text": "Watch",
            "url": "https://www.youtube.com/watch?v={{1}}"
          }
        ]
      }
    ],
    "category": "TRANSACTIONAL",
    "rejectedReason": "(#192) Param components[3]['buttons'][0]['phone_number'] is not a valid phone number.",
    "createdAt": "2021-08-06T06:34:40.815772829Z",
    "updatedAt": "2021-08-06T06:35:11.74973411Z"
  }
]

Response codes

Code	Description
200	Success
400	The HTTP request is malformed, the details should be available in the HTTP response body.
401	The request is not authenticated, please check your access key.
404	Template not found.
429	Too many requests, please retry using standard exponential backoff
500	Internal server error, please retry using standard exponential backoff

Fetch template by name and language

Fetch the template details given a name and language.

GET /v2/platforms/whatsapp/templates/{name}/{language}

Request

Attribute	Type	Description	Required
name	string	The name of the template.	Yes
language	TemplateLanguage	The template language.	Yes
wabaId	string	Optional filter for templates belonging to a specific WABA. If not supplied, the template will be fetched using the first WABA linked to your account. Do not specify channelId if wabaId was provided.	No
channelId	string	Optional filter for templates that can be sent via the specified channel. If not supplied, the template will be fetched using the first WABA linked to your account. Do not specify wabaId if channelId was provided.	No

curl -X GET "https://integrations.messagebird.com/v2/platforms/whatsapp/templates/sample_whatsapp_template/en" \
  -H "Authorization: AccessKey test_gshuPaZoeEG6ovbc8M79w0QyM" \
  -H "Content-Type: application/json"

Response

A Template object.

{
  "name": "sample_whatsapp_template",
  "language": "en",
  "status": "REJECTED",
  "components": [
    {
      "type": "HEADER",
      "format": "IMAGE"
    },
    {
      "type": "BODY",
      "text": "Hello {{1}}! This is a sample template."
    },
    {
      "type": "FOOTER",
      "text": "Sample footer"
    },
    {
      "type": "BUTTONS",
      "buttons": [
        {
          "type": "PHONE_NUMBER",
          "text": "Call us!",
          "phone_number": "+31 0 0000-0000"
        },
        {
          "type": "URL",
          "text": "Watch",
          "url": "https://www.youtube.com/watch?v={{1}}"
        }
      ]
    }
  ],
  "category": "TRANSACTIONAL",
  "rejectedReason": "(#192) Param components[3]['buttons'][0]['phone_number'] is not a valid phone number.",
  "createdAt": "2021-08-06T06:34:40.815772829Z",
  "updatedAt": "2021-08-06T06:35:11.74973411Z"
}

Response codes

Code	Description
200	Success
400	The HTTP request is malformed, the details should be available in the HTTP response body.
401	The request is not authenticated, please check your access key.
404	Template not found.
429	Too many requests, please retry using standard exponential backoff
500	Internal server error, please retry using standard exponential backoff

Delete templates by name

It deletes a template and all its languages.

DELETE /v2/platforms/whatsapp/templates/{name}

Request

Attribute	Type	Description	Required
name	string	The name of the template.	Yes
wabaId	string	Optional filter for templates belonging to a specific WABA. If not supplied, the template will be fetched using the first WABA linked to your account. Do not specify channelId if wabaId was provided.	No
channelId	string	Optional filter for templates that can be sent via the specified channel. If not supplied, the template will be fetched using the first WABA linked to your account. Do not specify wabaId if channelId was provided.	No

curl -X DELETE "https://integrations.messagebird.com/v2/platforms/whatsapp/templates/sample_whatsapp_template" \
  -H "Authorization: AccessKey test_gshuPaZoeEG6ovbc8M79w0QyM" \
  -H "Content-Type: application/json"

Response

It doesn't provide any response unless there's an error.

Response codes

Code	Description
202	Template scheduled for deletion
400	The HTTP request is malformed, the details should be available in the HTTP response body.
401	The request is not authenticated, please check your access key.
404	Template not found.
422	WhatsApp sample templates cannot be deleted.
429	Too many requests, please retry using standard exponential backoff
500	Internal server error, please retry using standard exponential backoff

Response codes

Code	Description
202	Template scheduled for deletion
400	The HTTP request is malformed, the details should be available in the HTTP response body.
401	The request is not authenticated, please check your access key.
404	Template not found.
422	WhatsApp sample templates cannot be deleted.
429	Too many requests, please retry using standard exponential backoff
500	Internal server error, please retry using standard exponential backoff

Objects Reference

Template object

Attribute	Type	Description
id	string	Template unique UUID
name	string	Template name. Must be less than 100 characters and can contain only letters, numbers and underscore.
language	TemplateLanguage	Template language
status	TemplateStatus	Template status
components	List of TemplateComponent	List of components
category	TemplateCategory	Template category
previousCategory	TemplateCategory	Previous category value before Meta's template approval. The param starts working from April 1, 2023
rejectedReason	TemplateRejectedReason	Rejection reason. Available if the template is rejected
wabaId	string	WABA ID
namespace	string	WABA Namespace
createdAt	Datetime	Creation timestamp
updatedAt	Datetime	Last updated timestamp

TemplateLanguage object

Value	Language
af	Afrikaans
sq	Albanian
ar	Arabic
az	Azerbaijani
bn	Bengali
bg	Bulgarian
ca	Catalan
zh_CN	Chinese (CHN)
zh_HK	Chinese (HKG)
zh_TW	Chinese (TAI)
hr	Croatian
cs	Czech
da	Danish
nl	Dutch
en	English
en_GB	English (UK)
en_US	English (US)
et	Estonian
fil	Filipino
fi	Finnish
fr	French
de	German
el	Greek
gu	Gujarati
he	Hebrew
hi	Hindi
hu	Hungarian
id	Indonesian
ga	Irish
it	Italian
ja	Japanese
kn	Kannada
kk	Kazakh
ko	Korean
lo	Lao
lv	Latvian
lt	Lithuanian
mk	Macedonian
ms	Malay
mr	Marathi
nb	Norwegian
fa	Persian
pl	Polish
pt_BR	Portuguese (BR)
pt_PT	Portuguese (POR)
pa	Punjabi
ro	Romanian
ru	Russian
sr	Serbian
sk	Slovak
sl	Slovenian
es	Spanish
es_AR	Spanish (ARG)
es_ES	Spanish (SPA)
es_MX	Spanish (MEX)
sw	Swahili
sv	Swedish
ta	Tamil
te	Telugu
th	Thai
tr	Turkish
uk	Ukrainian
ur	Urdu
uz	Uzbek
vi	Vietnamese

TemplateRejectedReason object

Value	Description
ABUSIVE_CONTENT	Abusive content
INVALID_FORMAT	Invalid format
NONE	None
PROMOTIONAL	Promotional
TAG_CONTENT_MISMATCH	Tag content mismatch
NON_TRANSIENT_ERROR	Non transient error

TemplateStatus object

Value	Description
NEW	New template. It can't be used yet
APPROVED	Approved template. It can be used to send template messages
PENDING	Approval pending. It can't be used yet
REJECTED	The template was rejected by Facebook
PENDING_DELETION	The template is pending for deletion
DELETED	The template is deleted

TemplateCategory object

The following template categories have been deprecated and will become read only on existing templates from April 1, 2023.

Value	Description
OTP	One time password
TRANSACTIONAL	Transactional
MARKETING	Marketing

The following template categories will start working from March 15, 2023. Please use the current categories when creating templates.

Value	Description
AUTHENTICATION	Authentication
UTILITY	Utility
MARKETING	Marketing

The following template categories have been deprecated and will become read only on existing templates from September 2022. Please use the new categories when creating templates.

Deprecated TemplateCategory object

Value	Description
ACCOUNT_UPDATE	Account updates
PAYMENT_UPDATE	Payment updates
PERSONAL_FINANCE_UPDATE	Personal finance update
SHIPPING_UPDATE	Shipping update
RESERVATION_UPDATE	Reservation updates
ISSUE_RESOLUTION	Issue resolution updates
APPOINTMENT_UPDATE	Appointment updates
TRANSPORTATION_UPDATE	Transportation updates
TICKET_UPDATE	Customer support ticket updates
ALERT_UPDATE	Alert updates
AUTO_REPLY	Auto reply

TemplateComponent object

Attribute	Type	Description	Required
type	TemplateComponentType	Component type	Yes
format	TemplateComponentFormat	Component format	Only for header components
text	string	Text of the message to be sent	Only for body components
buttons	List of TemplateComponentButton	List of buttons	Only for buttons components
example	TemplateExample	Example for the component that shows the intended use of the component	No
cards	Array of CarouselCard	List of cards	Only for carousel components

TemplateComponentType object

Value	Description
BODY	Body component
HEADER	Header component
FOOTER	Footer component
BUTTONS	Buttons component
CAROUSEL	Carousel component

TemplateComponentFormat object

Value	Description
TEXT	Text component format
IMAGE	Image component format
DOCUMENT	Document component format
VIDEO	Video component format

TemplateComponentButton object

Attribute	Type	Description	Required
type	TemplateComponentButtonType	Button type	Yes
text	string	Text to be displayed on the button. Required when	Yes
url	string	The URL which the user will be redirected when clicking the button	Only for URL buttons
phone_number	string	The phone number which will be called when clicking the button	Only for phone number buttons
example	Array of string	A list of example values that shows the intended use of the button	URL and QUICK_REPLY buttons

TemplateComponentButtonType object

Value	Description
PHONE_NUMBER	Phone call button
URL	URL button
QUICK_REPLY	Quick reply button

TemplateExample object

Attribute	Type	Description	Required
header_text	Array of string	Example values for HEADER type components, TEXT format	Required for TEXT format when variables are used
body_text	Array of Array of string	Example set of values for the body text variables	No
header_url	Array of string	Example values for IMAGE-VIDEO-DOCUMENT type components	Required for IMAGE-VIDEO-DOCUMENT format

CarouselCard object

Attribute	Type	Description	Required
components	Array of TemplateComponent	List of components	Yes

Is this page useful?

Next upFile Storage

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