API Reference

OverviewSMSVoice CallingVoice MessagingConversations APIIntegrations APIOmnichannel WidgetNumbersPartner AccountsVerifyMMSHLRBalanceLookupContactsGroups

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.

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.

POST /v2/platforms/whatsapp/templates

Request

ParameterTypeDescriptionRequired
namestringThe name of template.Yes
languageHSMLanguageThe language of the template.Yes
componentsArray of HSMComponentAn array of template components.Yes
categoryHSMCategoryThe template category.Yes

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/image.jpeg"]
}
},
// OR
// {
// "type": "HEADER",
// "format": "TEXT"
// "text": "Sample header {{1}}!"
// "example": {
// "header_text": ["example1", "example2"]
// }
// },
{
"type": "BODY",
"text": "Hello {{1}}! This is a sample template."
"example: {
"body_text": [["John"], ["Anna"]]
}
},
{
"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": "ACCOUNT_UPDATE"
}'

The template looks like the following.

Sample template with components

Response

ParameterTypeDescription
namestringTemplate name.
languageHSMLanguageThe language of template.
categoryHSMCategoryThe template category.
componentsArray of HSMComponentAn array of template components.
statusHSMStatusThe template status, in this case: NEW
{
"name": "sample_whatsapp_template",
"language": "en",
"status": "NEW",
"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": "ACCOUNT_UPDATE",
"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
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": "ACCOUNT_UPDATE",
"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": "ACCOUNT_UPDATE",
"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.
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": "ACCOUNT_UPDATE",
"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.
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

AttributeTypeDescription
namestringThe name of the template.
languageHSMLanguageThe template language.
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": "ACCOUNT_UPDATE",
"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

Delete template by name and language

It deletes a template with a specific language.

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

Request

AttributeTypeDescription
namestringThe name of the template.
languageHSMLanguageThe template language.
curl -X DELETE "https://integrations.messagebird.com/v2/platforms/whatsapp/templates/sample_whatsapp_template/en" \
-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

Objects Reference

Template object

AttributeTypeDescription
idstringTemplate unique UUID
namestringTemplate name. Must be less than 100 characters and can contain only letters, numbers and underscore.
languageHSMLanguageTemplate language
statusHSMStatusTemplate status
componentsList of HSMComponentList of components
categoryHSMCategoryTemplate category
rejectedReasonHSMRejectedReasonRejection reason. Available if the template is rejected
createdAtDatetimeCreation timestamp
updatedAtDatetimeLast updated timestamp

HSMLanguage 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

HSMRejectedReason object

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

HSMStatus 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

HSMCategory 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

HSMComponent object

AttributeTypeDescriptionRequired
typeHSMComponentTypeComponent typeYes
formatHSMComponentFormatComponent formatOnly for header components
textstringText of the message to be sentOnly for body components
buttonsList of HSMComponentButtonList of buttonsOnly for buttons components
example HSMExampleExample for the component that shows the intended use of the componentNo

HSMComponentType object

ValueDescription
BODYBody component
HEADERHeader component
FOOTERFooter component
BUTTONSButtons component

HSMComponentFormat object

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

HSMComponentButton object

AttributeTypeDescriptionRequired
typeHSMComponentButtonTypeButton 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

HSMComponentButtonType object

ValueDescription
PHONE_NUMBERPhone call button
URLURL button
QUICK_REPLYQuick reply button

HSMExample object

AttributeTypeDescriptionRequired
header_textArray of stringExample values for HEADER type components, TEXT formatNo
body_textArray of Array of stringExample set of values for the body text variablesNo
header_urlArray of stringExample values for HEADER type components, IMAGE formatNo

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