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
- Standard Text Message Templates
- Text Messages
- Media Messages
Other features that will be available:
- WhatsApp Contact Messages (Coming soon)
- Location Messages (Coming soon)
- Media messages templates
- 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_! |
|
Tilde (~) |
This is ~better~ best! |
|
|
|
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 |
0 Comments