Messaging

Messaging API is a messaging service that allows you to send a New Notification Message to a specific delivery channel. This API unifies delivery channels (SMS, Email, Push, RCS, WhatsApp) to send the desired notification message through a single method.

When sending a notification message through the Messaging API, it will be sent to its respective delivery channel. For example, if you send an SMS message through Messaging API, this API will take care of processing and routing the message to its respective delivery channel (SMS). This process happens every time a message is sent to its respective channel through this API.

This API helps you to quickly create and configure sending a new notification message to your customers globally in real time. The main advantage of our API is its simplicity of implementation, an easy and simple way to use!

Sending a WhatsApp Message

This API is a tool that seeks to respond to the need of medium and large companies to communicate with customers through the WhatsApp platform.

WhatsApp is the most popular OTT app in many parts of the world. With the Messaging API, you can reach more than 1.5 billion WhatsApp users. You can send notifications and have two-way conversations. If you're trying to reach – and better converse with – users in LATAM, EMEA, and APAC, you need to consider using WhatsApp.

To use the Messaging API, you must first request an activation. We’ll qualify your application and send it to WhatsApp for approval. A representative will get back to you as soon as possible to give you all the necessary information about the activation process.

• During the flow, you’ll be asked for your Facebook Business Manager ID. To start, first make sure that you have a personal Facebook account to confirm your identity. Then, go to “Facebook Business settings”, click Business information, and you’ll see your ID below “Business Manager ID”. Your ID is required to connect your business account with WhatsApp. Make sure you have a verified business account.

• During the flow, you’ll be asked if you already have a WhatsApp Business Account Id (WABA). In case you don't have a WABA Id, our support team will provide you the WABA Id.

📘

NOTE

• The WABA Id field is optional.

• WhatsApp takes approximately 2 weeks to approve a WhatsApp Business Account.

For more information on how to set up a Facebook Business Manager asset go to WhatsApp Business API.

The messaging API supports sending two types of WhatsApp messages:

• Template Message (Text & Media)

• Regular Message

Creating a Template Message

A WhatsApp message template is a message format that you can use over and over again to message users once they have opted-in and given their consent to receive messages. In order to send messages using a template, it must be pre-approved by Whatsapp. WhatsApp reviews and approves each message template, typically in 48 hours or less, to maintain high-quality content and avoid spam.

Contact your account manager to request new templates.

Before requesting new templates message, we recommend you go to the Creating a Template Message section from the WhatsApp Business API to learn how to set the requirements to create the Message Template.

There are two (2) types of WhatsApp Messages Templates:

• Text Message Template

• Media Message Template

Text Message Template

Create and send a simple text template. This type of template allows you to predefine the configuration of text message and personalized fields (placeholders).

The body of a message template should only contain text, personalized fields and emojis. There is no limit to the number of parameters allowed in the body but when sending the message template, the total number of characters may not exceed 1024. If using parameters in the body, they may contain many characters as long as the total body length does not exceed the aforementioned 1024 characters.

The requirements before sending the Text Message Template to the recipients via WhatsApp Business API are the following:

• Create the Text Message Template from the Digital Engagement Platform, in the Templates section.

• Once you have created the text message template, you'll need to submit it for WhatsApp approval. This can be done directly from the Digital Engagement Platform where the message template is created.

• It takes WhatsApp up to 48 hours to review a message template.

• After a text message template is created and approved, you can send it to recipients via API by copying each value of the template message to the request body.

For more information to create a WhatsApp message template via Digital Engagement Platform go to the WhatsApp Templates section.

🚧

WARNING

You must carefully copy each value according to its corresponding parameter you set when creating the text template via UI (Digital Engagement Platform) to the request body.

The request body contains the following data:

HTTP Request : POST / notification

{
  "channel": "WHATSAPP",
  "request": {
    "from":"1000000001",
    "to":"+1000000002",
    "templateName":"code_shipping",
    "templateLanguage":"en",
    "message": "Hi! your discount code is {{code}}",
    "placeholders":{
       "code":"34871"
    }
  }
}

The parameters presented in the request body example when sending a Text Message Template are the following:

When you send a Text Message Template, the response body contains the following data:

{
  "meta": {
    "timestamp": 1642531254980,
    "transactionId": "077da1d0-e089-487e-aed0-59534ba2d9f5",
    "explain": "Send Notification"
  }
}

Parameters presented in the response body example when sending a Text Message Template are the following:

Media Message Template

Media message templates expand the content you can send recipients beyond the standard message template type to include headers, media and buttons. That is, this type of template allows you to predefine the configuration of text message, media and buttons features and personalized fields (placeholders) that provide additional information.

Media Message Templates contain 3 main components:

• Header (Text & Media)

• Text Message (body)

• Buttons (Call to Action & Quick Reply)

Header : This type of template includes an optional header.

The Header contains the media, which can be text, an image, video or pdf file and it is located at the top of the message. You can use headers to provide additional information to end users.

Headers can contain the following:

• Text: Should only contain text and emojis. A text header has a limit of 60 characters including emojis.

📘

NOTE

When creating a media message template with a media header, you do not specify the actual files that will be used; you only specify the type of file that will be used. Actual files to be sent are specified as links when sending the template.

• Image: Images must be less than 5MB and the format must be .jpg or .png.

• Video: Video must be less than 5MB and the format must be .mp4, .3gpp (Only H.264 video codec and AAC audio codec are supported).

• Document: Documents must be less than 5MB and the format must be .pdf

📘

NOTE

You are only able to edit the Multimedia Header (Image, Video or Document) in the request body when sending the message template to the recipient.

Text Message: The body of a message template should only contain text, personalized fields (placeholders) and emojis. There is no limit to the number of parameters allowed in the body but when sending the message template, the total number of characters may not exceed 1024. If using parameters in the body, they may contain many characters as long as the total body length does not exceed 1024 characters.

Buttons: This type of template includes optional buttons.

There are two kinds of buttons that may be added to a media message template: call to action and quick reply.

• Call To Action: A call to action button allows the customer to call a specific phone number or go to a specific URL. Up to two (2) distinct buttons are allowed, you can’t place 2 phone buttons or 2 URL buttons.

  Format options include Phone Number, URL and Dynamic URL. This lets you add a phone number or website URL to your message. If you choose a URL, you can choose from a Static (fixed) website URL or a Dynamic website URL, which creates a personalized link for each campaign you use the template on by adding a variable at the end of the link. The suffix value you set here acts as a default, when you send this template, you can set another value or leave it as it is.

📘

NOTE

You are able to edit the URL Suffix (Dynamic URL) in the request body when sending the message template to the recipient.

• Quick Reply : Messages include up to 3 options —each option is a button. This type of message offers a quicker way for users to make a selection from a menu when interacting with a business. For example, we are going to add two buttons to the message content:

  Button text* = Yes, Button payload: agree
  Button text* = No, Button payload: NotAgree

  If the end user selects the button ‘Yes’, the platform will interpret it as ‘agree’ → agree (Yes).

  You set the value of the Button payloads to Keyword Senders (Auto-Reply, Opt-Out, Help Response, Join Response).

📘

NOTE

You are able to edit the Button payload in the request body when sending the message template to the recipient.

The requirements before sending the Media Message Template to the recipients via WhatsApp Business API are the following:

• Create the Media Message Template from the Digital Engagement Platform, in the Templates section.

• Once you have created the media message template, you'll need to submit it for WhatsApp approval. This can be done directly from the Digital Engagement Platform where the message template is created.

  It takes WhatsApp up to 48 hours to review a message template.

• After a media message template is created and approved, you can send it to recipients via API by copying each value of the template message to the request body.

For more information about creating a WhatsApp message template via the Digital Engagement Platform go to the WhatsApp Templates section.

🚧

WARNING

You must carefully copy each value according to its corresponding parameter you set when creating the media template via UI (Digital Engagement Platform) to the request body.

You are only able to set a value for a Multimedia Header (Image, Video or Document), a URL Suffix (Dynamic URL) for a Call To Action Button, or values for Button Payloads from Quick Reply Buttons in the request body. You can not edit Text Headers, phone numbers (Call to Action), Static URLs (Call to Action), the template content, among others in the request body because these values have been approved by WhatsApp.

📘

NOTE

The total number of API Calls (requests) that the user can make to the POST /notification endpoint in a certain time has been limited. That is, in case the user exceeds the limit of requests (messages sent) that can be made in a specific time, he/she will not be able to send another request until the established time is up. Once the time has elapsed, the request counter is reset and the request can be sent to the endpoint again.

In this example, the user can send 2 requests in 300 seconds (5 minutes). When a third request is sent within the 5 minute range, the HTTP Status Code “429” will be generated and the following parameter will be displayed from the Response body: "errors": { "reason": Too Many Requests" }. This code tells you that the user has sent too many requests in a given amount of time. Once the required time has elapsed, the request counter is reset to 2, so the user will be able to send two requests again in 5 minutes.

To find out if the user exceeds the limit of required requests and the time he/she needs to wait to send the next request, we recommend consulting the Response Header (additional information about the body of the resource). The parameters presented in the response header are the following:

ratelimit-limit: 2
ratelimit-policy: 2;w= 300
ratelimit-remaining: 1
ratelimit-reset: 5m0s

• RateLimit-Limit: return the number of requests left for the client in the time window
• RateLimit-Remaining: return the remaining quota in the current window
• RateLimit-Reset: return the time remaining in the current window, specified in seconds
• RateLimit-Policy: return the quota policy. The quota policy expression can be found in paragraph 2.1 of the IETF draft. The format is, for example, for 2 requests in 300 seconds.

The request body contains the following data:

HTTP Request : POST / notification

{
  "channel": "WHATSAPP",
  "request": {
    "from":"1000000001",
    "to":"+1000000002",
    "templateName":"code_shipping",
    "templateLanguage":"en",
    "message": "Hi! your discount code is {{code}}",
    "templateHeader":{  
    "type": "image",  
    "url": "https://example.com?media=image"
    },
    "placeholders":{
       "code":"34871"
    },
    "templateButtons":[
       {
          "type":"cta",
          "values":[
             {
                "index":0,
                "value":"ertyhgf456"
             }
          ]
       },
       {
          "type":"quick-reply",
          "values":[
             {
                "index":1,
                "value":"Unsubscribe"
             }
          ]
       }
    ]
  }
}

The parameters of the request body are divided into three (3) main sections to send a media message template:

• Main parameters: Outline the essential information needed to send a media WhatsApp template. It highlights the importance of identifying the template, specifying the sender and recipient, and ensuring the template is sent in the correct language. These parameters are crucial for delivering the message accurately and effectively.
• Components parameters: Outline the essential information to explain how to customize and personalize the content of a media WhatsApp template. It covers setting up the header with either a placeholder or media URL, specifying the header type, and configuring placeholder(s) in the text message body. These parameters ensure that the message is accurately tailored to the recipient, using the appropriate content and placeholders defined in the template.
• Buttons Component parameters: It details the requirements for setting up the Call to Action and Quick Reply buttons, including specifying their type, defining their values (like URL suffix and keywords), and positioning them correctly within the template. These parameters ensure that the buttons work as intended, providing a seamless interactive experience for the recipient.

Main Parameters

Components parameters

You are only able to edit the placeholder of the header text, the value for a Multimedia Header (Image, Video, or Document), and placeholder(s) that includes the text message body.

Buttons Component parameters

You are only able to edit If the created template includes a “Buttons” component with either a dynamic URL (call to action type button) or quick reply type buttons.

When you send a Media Message Template, the response body contains the following data:

{
  "meta": {
    "timestamp": 1642531254980,
    "transactionId": "077da1d0-e089-487e-aed0-59534ba2d9f5",
    "explain": "Send Notification"
  }
}

Parameters presented in the response body example when sending a Media Message Template are the following:

Regular Message

If a WhatsApp user has sent your application a message — whether it’s a reply to one of your outbound messages, or they have initiated communication themselves — your application has a 24-hour window to send that user any messages, without using a template. These are known as conversational messages.

If your application sends a message to a WhatsApp user outside a 24-hour session, the message must use an approved template as described in the previous section.

You can add text and media files as attachments to conversational messages.

Regular Messages contain 2 main components you can add as attachments to conversational messages:

• Text (message)

• Media (files)

📘

NOTE

The total number of API Calls (requests) that the user can make to the POST /notification endpoint in a certain time has been limited. That is, in case the user exceeds the limit of requests (messages sent) that can be made in a specific time, he/she will not be able to send another request until the established time is up. Once the time has elapsed, the request counter is reset and the request can be sent to the endpoint again.

In this example, the user can send 2 requests in 300 seconds (5 minutes). When a third request is sent within the 5 minute range, the HTTP Status Code “429” will be generated and the following parameter will be displayed from the Response body: "errors": { "reason": Too Many Requests" }. This code tells you that the user has sent too many requests in a given amount of time. Once the required time has elapsed, the request counter is reset to 2, so the user will be able to send two requests again in 5 minutes.

To find out if the user exceeds the limit of required requests and the time he/she needs to wait to send the next request, we recommend consulting the Response Header (additional information about the body of the resource). The parameters presented in the response header are the following:

ratelimit-limit: 2
ratelimit-policy: 2;w= 300
ratelimit-remaining: 1
ratelimit-reset: 5m0s

• RateLimit-Limit: return the number of requests left for the client in the time window
• RateLimit-Remaining: return the remaining quota in the current window
• RateLimit-Reset: return the time remaining in the current window, specified in seconds
• RateLimit-Policy: return the quota policy. The quota policy expression can be found in paragraph 2.1 of the IETF draft. The format is, for example, for 2 requests in 300 seconds.

Text: The body of a message template should only contain text and emojis. There is no limit to the number of parameters allowed in the body but when sending a simple message, the total number of characters may not exceed 1024. Using parameters in the body may contain many characters as long as the total body length does not exceed 1024 characters.

When you send a Regular Text Message, the request body contains the following data:

HTTP Request : POST /whatsapp/messages

{
  "channel": "WHATSAPP",
  "request": {
    "message": "Welcome to EliPackage",
    "to": "+1000000002",
    "from": "1000000001",
    "type":"text"
  }
}

The parameters presented in the request body example when sending a Regular Text Message are the following:

When you send a Regular Text Message, the response body contains the following data:

{
  "meta": {
    "timestamp": 1642531254980,
    "transactionId": "077da1d0-e089-487e-aed0-59534ba2d9f5",
    "explain": "Send Notification"
  }
}

Parameters presented in the response body example when sending the Regular Text Message are the following:

Media: You can attach multimedia files to a simple message, which can be an image, audio, video, or a pdf file via URL.

Supported content types and sizes:

When you send a Regular Media Message, the request body contains the following data:

HTTP Request : POST /whatsapp/messages

{
  "channel": "WHATSAPP",
  "request": {
    "message": "https://<URL_IMAGE>",
    "to": "+1000000002",
    "from": "1000000001",
    "type":"image"
  }
}

The parameters presented in the request body example when sending a Regular Media Message are the following:

When you send a Regular Media Message, the response body contains the following data:

{
  "meta": {
    "timestamp": 1642531254980,
    "transactionId": "077da1d0-e089-487e-aed0-59534ba2d9f5",
    "explain": "Send Notification"
  }
}

Parameters presented in the response body example when sending the Regular Media Message are the following: