Messaging

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

You can send four types of notification messages through the Notification method:

• SMS

• Email

• Push notification

• RCS

• WhatsApp

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, easy and simple way to use!

Sending an SMS

SMS notifications (Short Message Service) are out-of-band text messages that are sent when an event occurs. An event, in this case, can refer to something as exciting as an app update to something as urgent as a weather alert. SMS notifications are very useful for organization as a marketing tool and public safety purposes as well. They’re limited to 160 characters.

Before sending your first SMS message, you must set up the short code or long code from which the message will be sent.

A Short Code is a special telephone number designed for high-throughput, two-way messaging. Short codes are used to send and receive SMS messages to and from mobile phones. That is, an SMS shortcode is a 5 digit number to which an SMS text message can be sent. Shortcodes are often used by businesses to allow customers to opt-in to their SMS campaigns, alert services, or to enter SMS competitions.

A Long Code is a standard phone number used to send and receive voice calls and SMS messages. Phone numbers are typically called “long codes” (10-digit numbers in many countries) when comparing them with SMS short codes (5-6 digit numbers). With a long code, you can only send one message per second. Therefore long code text marketing does not work if you want to message groups of more than 200 people.

You are able to send a new SMS message through the Notification method.

When you send an SMS message, the request body contains the following data:

HTTP Request : POST /notification

{
  "channel": "SMS",
  "request": {
    "from": "12345",
    "to": "+580000000005",
    "message": "text demo",
    "requestDR": true,
    "type": "MT"
  },
  "callbacks": [
    "http://www.mycallback.com?id=123"
  ]
}

The parameters presented in the request body example when sending the SMS message are the following:

📘

NOTE

In this API, we use the term MT because we will only send an SMS message to customers. If you desire to receive SMS messages (MO), go to the Receive SMS section.

Once the SMS notification message has been sent, the response body contains the following data:

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

The parameters presented in the response body example when sending the SMS notification message are the following:

The Messaging API publishes the Outbound SMS in the Send SMS API queue, for this reason, the response generates the “meta” segment.

Sending an Email

Email (electronic mail) is the exchange of computer-stored messages by telecommunication. The email was one of the first activities performed over the internet and is still the most popular use. A large percentage of the total traffic over the internet is email. Email can be used in various ways, either personally or within an organization, as well as one on one or among a large group of people.

You are able to send a new Email message through the Notification method.

When you send an Email message, the request body contains the following data:

HTTP Request : POST / notification

{
  "channel": "EMAIL",
  "request": {
    "from": "[email protected]",
    "to": "[email protected]",
    "message": "Hi, this is a Oberyn demo!",
    "subject": "Email Subject"
  },
  "callbacks": [
    "http://www.mycallback.com?id=123"
  ]
}

The parameters presented in the request body example when sending the SMS message are the following:

Once the Email notification message has been sent, the response body contains the following data:

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

The parameters presented in the response body example when sending the Email notification message are the following:

The Messaging API publishes the Email message in the Email API queue, for this reason the response generates the “meta” segment.

Sending a Push notification

A push notification is the delivery of information to a computing device from an application server where the request for the transaction is initiated by the server rather than by an explicit request from the client. While 'push notification' is most often used to refer to notifications on mobile devices.

Each native mobile application platform (iOS, Android) has its own set of development guidelines and standards, as well as its own OSPNS (Operating System Push Notification Service). Most of these OSPNS allow push notifications to include text, images, app badges, and sounds. The OSPNS routes the notification from the application provider to the application user’s device.

To add push notifications to an application, the application publisher registers with the push notification service of the OS for which they’re developing . Then their OS service provides an API to the app publisher so that the app can communicate with the service. The app publisher then adds the SDK to their application, then uploads the app to the appropriate app store. That is, in order to send push notifications to devices, it is necessary to register your application through the Google and iOS servers. Once your application is configured with the servers (Google / iOS), credentials will be generated. These credentials are the permissions granted to be able to send push notifications to the application configured by the client. The next step is to add our SDK to your app, this will allow you to send push notifications and get device tokens from users' devices once they have downloaded and registered your app. Now, you can send a new push notification message through the notification method.

When you send an Push notification message, the request body contains the following data:

HTTP Request : POST / notification

{
  "channel": "PUSH",
  "request": {
    "platform": "ANDROID",
    "to": "fxxxYXf7nfQ:APA91bG2Kzd...",
    "title": "Free shipping for a month!",
    "message": "body notification.",
    "credentialId": "5f1640b0869b170ce8c95825"
  },
  "callbacks": [
    "http://www.mycallback.com?id=123"
  ]
}

The parameters presented in the request body example when sending the Push message are the following:

The parameters presented in the response body example when sending the Push notification message are the following:

The Messaging API publishes the Push message in the Push notification API queue, for this reason the response generates the “meta” segment.

Sending a RCS

RCS (Rich communication services) is a protocol between both mobile operators and phones. The overall aim of RCS is for it to eventually replace SMS and MMS messaging, the formats we're all familiar with as they have been around for years. That is, RCS is a set of communication standards for SMS, MMS, and calling that make text messages look and feel more like dedicated messaging apps like WhatsApp, Telegram, Facebook Messenger, among others. Basically, it aims to bring "texting" up to the modern standards with features we expect from messaging apps.

Before you can send messages to users, you need to register as a partner with RCS Business Messaging. As a partner, you can create agents for brands that you manage and send messages through those agents.

An agent is an conversational entity that interacts with users by sending messages and reacting to users' responses. Messages between a user and an agent appear in an RCS-enabled messaging app, such as the Messages app, on the user's device. The Messages app displays branding and profile information for your agent, including name, logo, description, contact information, and URLs.

RBM agents use the RCS Business Messaging API to send messages, events, and other requests to users. When you create an agent, you enable access to the RBM API and define your agent's name and region.

The steps to create an Agent are the following:

1. Open the Business Communications Developer Console and sign in with your RBM Platform Google account.

2. Click Create Agent.

3. Enter your agent's name and region, then click Create agent.

4. When your agent is available, click your agent's name.

To send messages and events as your agent, you need to authenticate API calls with a service account key. The Business Communications Developer Console creates a service account for you, but you need to create a unique key to access your agent.

The steps to create a service account key to access the RBM API as your agent, and configure your agent to receive messages.

1. Open the Business Communications Developer Console and sign in with your RBM Platform Google account.

2. In the left navigation, click Service account.

3. Click Create key, then click Create. Your browser downloads a service account key for your agent. Store the key in a secure location on your development machine. The key can't be recovered if lost.

Once you have created and configured the agent, copy your AgentID, you will need it to send the RCS message to the recipient.

We provided you the ability to create a simple text message and standalone rich card with suggestions sent from the agent to the final user.

Each of the following documents will give you example requests for the message types, and rendered messages on handsets.

Messaging API supports sending two types of RCS messages:

• Text

• Standalone Rich Card

Even we provided you the ability to send the message via SMS in case the message couldnt be delivered by RCS.

Text

The simplest messages are made of text. Text messages are best suited to communicate information without the need for visuals, complex interaction, or response. Simple use cases like notifications, alerts or conversational chats can be composed in Text.

When you send a simple Text RCS message, the request body contains the following data:

HTTP Request : POST / notification

{
  "channel": "RCS",
  "request": {
    "to": "+580000000005",
    "message": "text demo",
    "messageType": "TEXT",
    "agentId": "604af472d06abe3a6f5c852e"
  }
}

The parameters presented in the request body example when sending the simple Text RCS message are the following:

The parameters presented in the response body example when sending the simple Text RCS notification message are the following:

The Messaging API publishes the RCS message in the RCS API queue, for this reason the response generates the “meta” segment.

Standalone Rich Card

A Standalone Rich Card is a small snippet, usually an image, that's linked to additional actions. This card can contain a suggested reply or a suggested action (suggestion).

Standalone Rich cards can contain the following items:

• Image/video

• Title text

• Description text

• A list of suggested replies and suggested actions (maximum 4)

When you send a Standalone Rich Card RCS message, the request body contains the following data:

HTTP Request : POST / notification

{
  "channel": "RCS",
  "request": {
    "messageType": "STANDALONECARD",
    "title": "sample title",
    "cardImageUrl": "https://example.url.site/logo.png",
    "mediaHeight": "SHORT",
    "cardOrientation": "HORIZONTAL",
    "alignment": "RIGHT",
    "to": "+580000000005",
    "agentId": "604af472d06abe3a6f5c852e",
    "suggestions": [
      {
        "type": "REPLY",
        "text": "Yes"
      },
      {
        "type": "REPLY",
        "text": "No"
      }
    ]
  }
}

The parameters presented in the request body example when sending the Standalone Rich Card RCS message are the following:

The parameters presented in the response body example when sending the standalone rich card RCS notification message are the following:

The Messaging API publishes the RCS message in the RCS API queue, for this reason the response generates the “meta” segment.

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.

The steps before sending a Whatsapp notification message are the following:

1. In order 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.

2. Create a Sender Id to be able to send messages.

• Once the account is approved, the support team will provide you with a provider id and the WABA Id (in case you have not entered the WABA Id). This provider Id helps you create a Sender.

For more information on how to set up a Facebook Business Manager asset and create a Sender 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

When you create a Sender and the approval of the account is successful, the value of the "data.state" parameter is "ACTIVE". You can now perform the next step: creating a Message Template.

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. Once WhatsApp has approved the message template, our support team will provide you the namespace identifier (Id) of the Message Template "templateNamespace".

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. Remember , once WhatsApp has approved your first message template, our support team will provide you a namespace identifier (Id) of the Message Templates in your account. "templateNamespace".

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": {
    "message": "Hi! your discount code is {{CODE}}",
    "to": "+1000000002",
    "from": "1000000001",
    "placeholders": {
      "CODE": "224477"
    },
    "templateNamespace": "31291098",
    "templateName": "code_shipping"
  }
}

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. Remember , once WhatsApp has approved your first message template, our support team will provide you a namespace identifier (Id) of the Message Templates in your account. "templateNamespace".

For more information about creating 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 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.

The request body contains the following data:

HTTP Request : POST / notification

{
  "channel": "WHATSAPP",
  "request": {
  "from": "1000000001",
  "to": "+1000000002",
  "body": "Hi! your discount code is {{code}}",
  "templateNamespace": "31291098",
  "templateName": "code_shipping",
  "templateLanguage": "en_US",
  "placeholders": {
    "code": "224477"
  },
  "templateHeader":{
    "type": "image",
    "url": "https://example.com?media=image.png"
  },
  "templateButtons": {
    "type": "cta",
    "values": [
      {
        "index": 0,
        "value": "info"
      }
     ]
    }
  }
}

Parameters present in the request body example when sending a Media Template Message are the following:

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)

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: