API Reference

OverviewSMSSMS batch APIVoice CallingVoice MessagingConversations APIContacts API (v2)Integrations APIFile Storage APIOmnichannel WidgetNumbersPartner AccountsVerifyMMSHLRBalanceLookupContactsGroupsIntentFAQNamed Entity RecognitionLanguage Detection

Integrations API

The MessageBird's Integration API provides endpoints for creating and fetching message templates.

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.

Notification icon

Currently the template management is only supported to WhatsApp platform.

Notification icon

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.

Notification icon

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

Notification icon

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

ParameterTypeDescriptionRequired
namestringThe name of template.Yes
languageTemplateLanguageThe language of the template.Yes
componentsArray of TemplateComponentAn array of template components.Yes
categoryTemplateCategoryThe template category.Yes
wabaIdstringThe ID of the WABA for which the template should be created. If not supplied, the first WABA linked to your account will be usedNo

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.

Sample template with components

Response

ParameterTypeDescription
namestringTemplate name.
languageTemplateLanguageThe language of template.
categoryTemplateCategoryThe template category.
componentsArray of TemplateComponentAn array of template components.
statusTemplateStatusThe template status, in this case: NEW
wabaIdstringThe Template WABA ID.
namespacestringThe 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
CodeDescription
201Template created, it can't be used yet because must be approved by Facebook.
400The HTTP request is malformed, the details should be available in the HTTP response body.
401The request is not authenticated, please check your access key.
429Too many requests, please retry using standard exponential backoff
500Internal server error, please retry using standard exponential backoff

List templates

List all your templates.

GET /v3/platforms/whatsapp/templates

Request

ParameterTypeDescriptionRequired
offsetintegerThe number of objects to skip from the first.No. Default: 0
limitintegerThe number of maximum objects to return on each request. Maximum: 50No. Default: 50
wabaIdstringOptional filter for templates belonging to a specific WABA. Do not specify channelId if wabaId was provided.No
channelIdstringOptional 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

ParameterTypeDescription
offsetintegerThe number of objects skipped.
limitintegerThe number of maximum objects returned on each request.
countintegerNumber of templates returned.
totalCountintegerThe number of total templates that can be retrieved through pagination.
itemsArray of TemplateList 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

AttributeTypeDescription
namestringThe name of the template.
wabaIdstringOptional 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.
channelIdstringOptional 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
CodeDescription
200Success
400The HTTP request is malformed, the details should be available in the HTTP response body.
401The request is not authenticated, please check your access key.
404Template not found.
429Too many requests, please retry using standard exponential backoff
500Internal 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

AttributeTypeDescriptionRequired
namestringThe name of the template.Yes
languageTemplateLanguageThe template language.Yes
wabaIdstringOptional 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
channelIdstringOptional 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
CodeDescription
200Success
400The HTTP request is malformed, the details should be available in the HTTP response body.
401The request is not authenticated, please check your access key.
404Template not found.
429Too many requests, please retry using standard exponential backoff
500Internal 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

AttributeTypeDescription
namestringThe name of the template.
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
CodeDescription
202Template scheduled for deletion
400The HTTP request is malformed, the details should be available in the HTTP response body.
401The request is not authenticated, please check your access key.
404Template not found.
422WhatsApp sample templates cannot be deleted.
429Too many requests, please retry using standard exponential backoff
500Internal server error, please retry using standard exponential backoff
Response codes
CodeDescription
202Template scheduled for deletion
400The HTTP request is malformed, the details should be available in the HTTP response body.
401The request is not authenticated, please check your access key.
404Template not found.
422WhatsApp sample templates cannot be deleted.
429Too many requests, please retry using standard exponential backoff
500Internal server error, please retry using standard exponential backoff

Objects Reference

Template object

AttributeTypeDescription
idstringTemplate unique UUID
namestringTemplate name. Must be less than 100 characters and can contain only letters, numbers and underscore.
languageTemplateLanguageTemplate language
statusTemplateStatusTemplate status
componentsList of TemplateComponentList of components
categoryTemplateCategoryTemplate category
rejectedReasonTemplateRejectedReasonRejection reason. Available if the template is rejected
wabaIdstringWABA ID
namespacestringWABA Namespace
createdAtDatetimeCreation timestamp
updatedAtDatetimeLast updated timestamp

TemplateLanguage object

ValueLanguage
afAfrikaans
sqAlbanian
arArabic
azAzerbaijani
bnBengali
bgBulgarian
caCatalan
zh_CNChinese (CHN)
zh_HKChinese (HKG)
zh_TWChinese (TAI)
hrCroatian
csCzech
daDanish
nlDutch
enEnglish
en_GBEnglish (UK)
en_USEnglish (US)
etEstonian
filFilipino
fiFinnish
frFrench
deGerman
elGreek
guGujarati
heHebrew
hiHindi
huHungarian
idIndonesian
gaIrish
itItalian
jaJapanese
knKannada
kkKazakh
koKorean
loLao
lvLatvian
ltLithuanian
mkMacedonian
msMalay
mrMarathi
nbNorwegian
faPersian
plPolish
pt_BRPortuguese (BR)
pt_PTPortuguese (POR)
paPunjabi
roRomanian
ruRussian
srSerbian
skSlovak
slSlovenian
esSpanish
es_ARSpanish (ARG)
es_ESSpanish (SPA)
es_MXSpanish (MEX)
swSwahili
svSwedish
taTamil
teTelugu
thThai
trTurkish
ukUkrainian
urUrdu
uzUzbek
viVietnamese

TemplateRejectedReason object

ValueDescription
ABUSIVE_CONTENTAbusive content
INVALID_FORMATInvalid format
NONENone
PROMOTIONALPromotional
TAG_CONTENT_MISMATCHTag content mismatch
NON_TRANSIENT_ERRORNon transient error

TemplateStatus object

ValueDescription
NEWNew template. It can't be used yet
APPROVEDApproved template. It can be used to send template messages
PENDINGApproval pending. It can't be used yet
REJECTEDThe template was rejected by Facebook
PENDING_DELETIONThe template is pending for deletion
DELETEDThe template is deleted

TemplateCategory object

ValueDescription
OTPOne time password
TRANSACTIONALTransactional
MARKETINGMarketing
Notification icon

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

ValueDescription
ACCOUNT_UPDATEAccount updates
PAYMENT_UPDATEPayment updates
PERSONAL_FINANCE_UPDATEPersonal finance update
SHIPPING_UPDATEShipping update
RESERVATION_UPDATEReservation updates
ISSUE_RESOLUTIONIssue resolution updates
APPOINTMENT_UPDATEAppointment updates
TRANSPORTATION_UPDATETransportation updates
TICKET_UPDATECustomer support ticket updates
ALERT_UPDATEAlert updates
AUTO_REPLYAuto reply

TemplateComponent object

AttributeTypeDescriptionRequired
typeTemplateComponentTypeComponent typeYes
formatTemplateComponentFormatComponent formatOnly for header components
textstringText of the message to be sentOnly for body components
buttonsList of TemplateComponentButtonList of buttonsOnly for buttons components
exampleTemplateExampleExample for the component that shows the intended use of the componentNo

TemplateComponentType object

ValueDescription
BODYBody component
HEADERHeader component
FOOTERFooter component
BUTTONSButtons component

TemplateComponentFormat object

ValueDescription
TEXTText component format
IMAGEImage component format
DOCUMENTDocument component format
VIDEOVideo component format

TemplateComponentButton object

AttributeTypeDescriptionRequired
typeTemplateComponentButtonTypeButton typeYes
textstringText to be displayed on the button. Required whenYes
urlstringThe URL which the user will be redirected when clicking the buttonOnly for URL buttons
phone_numberstringThe phone number which will be called when clicking the buttonOnly for phone number buttons
exampleArray of stringA list of example values that shows the intended use of the buttonURL and QUICK_REPLY buttons

TemplateComponentButtonType object

ValueDescription
PHONE_NUMBERPhone call button
URLURL button
QUICK_REPLYQuick reply button

TemplateExample object

AttributeTypeDescriptionRequired
header_textArray of stringExample values for HEADER type components, TEXT formatRequired for TEXT format when variables are used
body_textArray of Array of stringExample set of values for the body text variablesNo
header_urlArray of stringExample values for IMAGE-VIDEO-DOCUMENT type componentsRequired for IMAGE-VIDEO-DOCUMENT format

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