Sending a WhatsApp Business API Message

The Syniverse CPaaS API service now supports WhatsApp Business API channel part of its Omni-channel API solution. It uses the same channel-agnostic API end-point as the other channels and utilizes majority of the resources as well as platform features available.

Please familiarize yourself with the Syniverse API reference guide, WhatsApp Business API Messaging guide and Engagement rules before invoking the APIs or using the message console to send WhatsApp messages.

WhatsApp Opt-In Requirements

One of the very first step in engaging user over WhatsApp Business API channel is to ensure the user has granted an explicit consent to receive messages from the Business over WhatsApp.  It is important to ensure Brand integrity and avoid a bad experience with your Brand.

WhatsApp requires that your Business application implement explicit user opt-ins/ consent gather in order to deliver messages over WhatsApp. You may gather this opt-in information either via a web page or a mobile app, such as during your application's sign-up flow, in your application's account settings, via SMS, etc. For more information, see https://developers.facebook.com/docs/whatsapp/guides/opt-in

Please note that sending messages to end users without an opt-in may result in users blocking your business as well as the suspension of your WhatsApp Business account. It is very important that Businesses familiarize themselves with the rules of engagement governing the use of WhatsApp Business as a communication channel. For more information on what is allowed and what’s not, please check out our article on Engagement rules.

 

Syniverse CPaaS API can currently support the following type of messages

  1. Standard Text Message Templates
  2. Text Messages
  3. Media Messages

Other features that will be available: 

  1. WhatsApp Contact Messages (Coming soon)
  2. Location Messages (Coming soon)
  3. Media messages templates
  4. Interactive message templates

Formatting in Text Messages
WhatsApp allows some formatting in messages. To format all or part of a message, use these formatting symbols:

Formatting Symbol Example

Formatting Symbol Example

Bold

Asterisk (*)

Your total is *$10.50*.

Italics

Underscore (_)

Welcome to _WhatsApp_!

Strike-through

Tilde (~)

This is ~better~ best!

Code

Three backticks (```)

```print 'Hello World';```

 

Sending a Standard Text Notification (Template) Message

Prior to invoking the API, you must have complete the following prerequisite:

  • Have a valid Sender ID
  • Have an approved Template for the notification message you are sending (Details of your approved templates would be given to you by your Syniverse account manager)
    • whatsapp:ns=WhatsApp namespace
    • elm =name of your template
    • plc= language policy 
    • cod= Language code
  • A recipient phone number (E.164 format)
  • A bearer token for your Syniverse application

Note that characteristic of each template in the table below. Please note that the parameters are case sensitive.

 

Parameter

 

Description

 

Format/value example

 

Mandatory

whatsapp:ns

HSM template message namespace

{baf8008d_66b0_d661_8877_a0548ff356890}

Yes

elm

HSM element name- The element name that indicates which template to use within the namespace. This is the Template name

appointment_reminder

Yes

plc

Language policy

deterministic

optional, default is "deterministic

cod

Language code:

"en_US", en_GB

optional, default is “en_US” See a list of supported languages below

 

If you are planning to support more than one language, you need to provide translations for all supported languages for all elements. Alternatively, customers can use the Syniverse text translation service to convert messages to upto 100 local languages

Please note that the template message body has a max character limit of 1024.  

Sending a Notification message (Template message) via API

Please note the format of the recipient address. Add the recipient's address in the "To" address field in the following format :

 {wa: <recipient_phonenumber}  e.g.{wa:+14085551212}
curl -X POST \
https://api.syniverse.com/scg-external-api/api/v1/messaging/messages\
-H 'Authorization: Bearer{TOKEN}' \-H 'Content-Type: application/json' \
-d
{
"from": "glXrXF2rFXauB2YK0RNyh7",
"to": "wa:+18471113232", "body": "#set($RECIPIENT=\"Kola\")\n#set($DATE_TIME=\"August, 30 at 5:00PM\")\n#parse(\"whatsapp:ns=8b24c6b8_f5f2_268f_acec_5olkbd0277dc:elm=appointment_reminder:plc=deterministic:cod=en_US\")",
}

  

It is also important to note that for new accounts, there are message limits that are tied to Business behavior on the platform. It is very important that a Business maintains a good status on the platform by making sure the user's experience is optimal.  This behaviour is determined by Facebook and consequently determines the message rate limit assigned to each WhatsApp Business API account.  See Message rate limit 

Sending a media WhatsApp Business API Message

Please note that sending media template messages is currently not available . Customers can send media messages in response to a user-initiated message (MO). To send a non-templated media message, you have the option of...

…. using Media url

Insert a media url link using the {"media_urls"} attribute. Ensure the media url value is an absolute URL. URL redirects are not supported

curl -X POST \

https://api.syniverse.com/scg-external-api/api/v1/messaging/messages
 \-H 'Authorization: Bearer Token'
\ -H 'Content-Type: application/json' \
-d '{"from":"H4kWf18Wz985Xya2tMyFs","to":["wa:+14085551212"],
"body":"Check out these pictures!",
"media_urls":["https://drive.google.com/uc?id=1Ef6ZyETMzSZQ2vIXaDUsBUgxWR173jtk"]}'

 

Supported Media type

Media

Supported Content-Types

audio

audio/aac, audio/amr

document

Any valid MIME-type

image

image/jpeg, image/jpg, image/png

video

video/mp4, video/3gpp.  Note: Only H.264 video codec and AAC audio codec is supported

 

Supported Post-processing media size

Media Type

Max Size

audio

5 MB

document

5 MB

image

5 MB

video

5 MB

 

Sending Customer Care messaging

This type of messaging is typically in response to a user-initiated message. Please see for information in our guide on Customer care messages.

 

curl -X POST 'https://api.syniverse.com/scg-external-api/api/v1/messaging/messages'
Content-Type: application/json' -H' Authorization: Bearer Token' --data-raw
'{
"from": "glXrXF2rFXauB2YK0RNyh7",
"to": "wa:+14085551212",
"body": "Thank you for your business"
}'

Please note that a single WhatsApp message can support upto 4096 characters of text message.

 

Send WhatsApp message with fallback to SMS

Businesses that are consuming the SCG Omni-channel messaging API can trigger fallback to SMS in the event that the user they are trying to engage is not on WhatsApp. To trigger this fallback, the following must be true:

  • Message is a templated message
  • Must have a valid SMS Sender address (Shortcode, Toll-free number or 10 DLC number)
  • Recipient's mobile number must be the same for both WhatsApp and SMS
  • Must have created a Channel with your SMS sender ID and WhatsApp Business API Sender ID for sending messages. For more info on how to create a private channel, please check out the article on creating private channels
curl -X POST \

https://api.syniverse.com/scg-external-api/api/v1/messaging/messages \
-H 'Authorization: Bearer Token' \ -H 'Content-Type: application/json' \
-d '{"from":"channel:x20mIKQ7uzUuESUBsHhUp8","to":["contact:ng7F8Vawd1Crs3wE20h5j3"],
"sender_id_sort_criteria":["DELIVERY_ADDRESS"],
"contact_delivery_address_priority":["WHATSAPP","MDN"],
" body":"#set($RECIPIENT=\"Kola\")\n#parse(\"whatsapp:ns=8b24c6b8_f5f2_268f_acec_5olkbd0277dc:elm=scg_appt\")",
"failover":"SMS"}'

 

Supported Languages

The following are the supported languages for message templates.

Language

Code

Afrikaans

af

Albanian

sq

Arabic

ar

Azerbaijani

az

Bengali

bn

Bulgarian

bg

Catalan

ca

Chinese (CHN)

zh_CN

Chinese (HKG)

zh_HK

Chinese (TAI)

zh_TW

Croatian

hr

Czech

cs

Danish

da

Dutch

nl

English

en

English (UK)

en_GB

English (US)

en_US

Estonian

et

Filipino

fil

Finnish

fi

French

fr

German

de

Greek

el

Gujarati

gu

Hausa

ha

Hebrew

he

Hindi

hi

Hungarian

hu

Indonesian

id

Irish

ga

Italian

it

Japanese

ja

Kannada

kn

Kazakh

kk

Korean

ko

Lao

lo

Latvian

lv

Lithuanian

lt

Macedonian

mk

Malay

ms

Malayalam

ml

Marathi

mr

Norwegian

nb

Persian

fa

Polish

pl

Portuguese (BR)

pt_BR

Portuguese (POR)

pt_PT

Punjabi

pa

Romanian

ro

Russian

ru

Serbian

sr

Slovak

sk

Slovenian

sl

Spanish

es

Spanish (ARG)

es_AR

Spanish (SPA)

es_ES

Spanish (MEX)

es_MX

Swahili

sw

Swedish

sv

Tamil

ta

Telugu

te

Thai

th

Turkish

tr

Ukrainian

uk

Urdu

ur

Uzbek

uz

Vietnamese

vi

Zulu

zu

 

Was this article helpful?
0 out of 0 found this helpful

0 Comments

Article is closed for comments.