WhatsApp Business API Guide


Introduction

Syniverse CPaaS Messaging API now supports access to WhatsApp Business API for Businesses to enable customer engagement via one of the most widely used messaging channels in the world. The WhatsApp Business API channel with access to close to 2 billion active monthly users in over 180 countries is now part of Syniverse’s cloud-based Omni-Channel messaging solution and available via the same API endpoint that you use to consume other channels like for SMS, MMS, Facebook Messenger, Push Notification & WeChat.

Businesses can enable engagement use cases by programmatically sending and receiving WhatsApp messages from their systems (CRM, customer care tools, POS etc.) thereby creating workflows that provides value to the end-users. Integrating and consuming WhatsApp Business API via the Syniverse CPaaS Omni-channel WhatsApp channel is easy and quick.

 

 

 

                                                                                                            

 

 

What can you do with the SCG WhatsApp Business Messaging Channel?

  • Send and receive messages from to and from end-users with a WhatsApp application including text, media and documents
  • Engage your customers in a 24/7 customer care conversational messaging using a chatbot or an application.
  • Send pre-approved templated notification messages to your customers
  • Reach over 2 Billion monthly active end-users in close to 180 countries. Exclusions. The WhatsApp Business Solution may not be used to send any messages to or from the following countries and regions: Crimea, Cuba, Iran, North Korea, and Syria
  • Engage users on a variety of use cases ranging from OTP, Critical Alert update, Payment update, Shipping update, Issue resolution, Reservation update etc.

 

Key components to using WhatsApp Business API Channel

WhatsApp Business Messaging Channel is currently available to Businesses on the Syniverse CPaaS platform who has executed a WhatsApp Business Messaging Service agreement with Syniverse

What you will need to use WhatsApp Business API

Facebook Business Manager

All Customers must have or be able to create a Facebook Business Manager account and verify it to use WhatsApp Business API. WhatsApp Business API uses your Facebook Business Manager account to identify your business and associate your phone numbers with it. WhatsApp requires all Businesses to submit Business Verification in their Facebook Business Manager account.

For more information on how create a Facebook Business Manager, please see Creating a Facebook Business Manager

WhatsApp Business Account (WABA)

Once you have a Facebook Business Manager Account created and have your Business Manager ID, the next step is to register for a WhatsApp Business account (WABA). Syniverse will assist you with the registration of a WABA.

Types of Business Accounts

There are two types of WhatsApp business accounts:

  • Official Business Account
  • Business Account

Facebook at its sole discretion, decides if a registration is approved for an Official Business Account or as a Business Account. Customers can choose which one of the accounts types they want and submit the necessary details and Syniverse will make every effort to request the account on behalf of the customer.

Please the details below on the differences between an Official Business Account and a regular Business Account:

 

Name

Description

Official Business Account

WhatsApp has verified that an authentic, notable brand owns this account.

An official business account has a green checkmark badge in its profile and chat thread headers. The name of the business is visible even if the user hasn't added the business to their address book.

Very few businesses will be official business accounts.

Business Account

By default, any account using the WhatsApp Business API or WhatsApp Business App is a business account. WhatsApp verifies authenticity of a brand for every account on the WhatsApp Business API.

 

 

How Your Business Appears to Users

Depending on your business account type, users will see different things. If a user has already saved the business number in their address book, the name from their address book will always be displayed. The phone number will still be visible in the contacts view.

Official Business Account

If your WhatsApp account is an official business account, the display name will be visible in the chat list, chat screens, chat groups, and contacts view instead of the phone number. There will be a green checkmark beside the displayed name in the contacts view.

                                                                                                    

 

Business Account

If your WhatsApp account is a business account, the display name will only be shown in the contacts view in smaller text; all other views will show the phone number. You can help customers learn more about your company by filling out your business info, including business website, address, and hours.

                                                                                                   

 

For a WABA account, you will work with your assigned Syniverse Implementation manager, who will gather the necessary details of what you will need to submit to get your WABA account setup.

 

Registering a number for WhatsApp Business API

Syniverse offers 2 options for registration of WhatsApp Business API numbers. In both cases, customer will need to have an E.164 formatted number that has not been used on WhatsApp before and capable of either receiving a call or text messaging.  Number is used to programmatically send and receive WhatsApp business messaging. The Syniverse platform will use this number to create a private sender ID for the customer’s WABA account.

  • Option 1: Customer can source a number directly from Syniverse to use as a WhatsApp Business API number. With this option, Syniverse can currently only provide US, UK and Canadian numbers and will help you with registration, activation of the number and creation of a Syniverse WhatsApp Business API Sender ID
  • Option 2: Customer can provide their own numbers to be used for WhatsApp Business API messaging. The number must meet the following criteria:
    • Must be an active phone number in E.164 format.
    • Must be able to receive a voice call or a SMS.
    • With this option, Businesses will need to cordinate directly with their Account team or assigned Implementation Manager to complete registration and activation of the number including the creation of a WhatsApp Business API Sender ID.

Once a number has been selected or assigned, Syniverse will register this number with WhatsApp along with a display name under your newly created WABA. For more information, see details on Phone Number and Display name registration 

WhatsApp Business API Sender ID

A WhatsApp Business API Sender ID is required to send messages on the Syniverse CPaaS platform. How this will be created depends on the WhatsApp Phone number registration option that the customer chooses.

If a customer choses option 1 (see above), Syniverse will create the Sender ID on behalf of the Business using the number assigned by Syniverse to the customer. Your assigned Implementation manager will work with you on timelines and details of the Sender ID.

For customer that chose option 2, please refer to “How to create a WhatsApp Business API Sender ID

 

Engaging your customers using WhatsApp Business API

Once the Business have all the necessary credentials created and approved, they can now proceed to engaging users using WhatsApp Business API channel using the Syniverse CPaaS API.

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.

Customer Engagement using WhatsApp Business API

There are some Business engagement rules that all businesses need to be familiar with. Please ensure you have read and understand these rules.

Businesses can engage their customers who have WhatsApp application clients on their devices using 2 types of engagement methods:

  1. Send Notifications (Template messaging)
  2. Have a 2-way conversation (Customer care or Conversational Messaging)

If your customer initiates messaging with you, it opens up ("24-hour Conversational Chat Window") in which you can communicate continuously with end-user for up to 24 hours following the last message that that customer sends to you (Conversational Messaging). Any additional message you send to that customer beyond the 24-hr. window must be a Notification (WhatsApp Template Messaging), for which an approved template is required.

WhatsApp Notification Messaging (Template Messages)

WhatsApp Business Messaging supports sending Business-intiated messages that uses a WhatsApp pre-approved templates for outbound notifications like delivery alerts, appointment reminders.

All Notification messages are billable as sent messages per our listed pricing for each applicable country. Each delivered Notification message is billed based upon the country code of the recipient. For example, a +44-country code phone number belonging to a recipient is charged at the United Kingdom price. Syniverse will charge you for each Notification (Templated Message) that is sent in addition to any applicable WhatsApp fee (Pass-thru fees.) For more information on WhatsApp Notification fees, visit https://developers.facebook.com/docs/whatsapp/pricing

Templated Message is required if you need to engage a user outside of the “24 hr Conversational Chat window”. Messages sent without a pre-approved template will be rejected. Below is a list of categories that a template can be created for:

  • Appointment Update
  • Auto Reply
  • Alert Updates
  • Account Update
  • Issue Resolution
  • Payment Update
  • Shipping Update
  • Ticket Update
  • Reservation Update
  • Personal Finance Update
  • Transportation Update

 

Syniverse will assist Customers in creating Messages Template that matches their supported use case.  Syniverse APIs currently do not support WhatsApp media message templates and buttons. Please check back later with us on when these features will be available.

Typically, a Template approval by WhatsApp could take up to 48 hours. WhatsApp templates are stored on WhatsApp servers and need to be referenced when sending message using the Syniverse CPaaS APIs. Each WhatsApp business account can only have up to 250 templates.

See information about Message templates and how to use them. To apply to have templates created, see instructions here

 

WhatsApp Customer Care (Conversational Messaging)

WhatsApp Business Messaging offers a session-like conversational chat messaging known as “Customer Care” messages, where any messages can be sent and received in response to a user-initiated message to your Chatbot or Service application. The Customer care messaging has a 24-hour window starting from when you first received the most recent message to your Chatbot or application from a user. During this 24 hr Customer care window you can communicate with users in freeform without the need of a Template.

For you to send message outside of the 24-hour chat window, you must use a pre-approved template (see Notification Messaging section above).

For information on how to send a WhatsApp Message, please visit: Sending WhatsApp Messages

 

WhatsApp Template Messages Support

This section provides detailed description of SCG support of WhatsApp Template Messages including details for sending Template Messages.

WhatsApp developer documentation is located here.

WhatsApp Templates Support

  1. Text-based Templates
  2. Media Templates
  3. Interactive Templates
  4. Highly Structured Message (HSM) Templates*

*HSM Templates are not recommended to use due to the announced by Facebook plans to deprecate them in WhatsApp Business API v2.39.

Supported Media Content Types in Template Messages

Media

Content Type

Image image/jpeg, image/png
Video video/mp4, video/3gpp
Document application/pdf

 

Audio, documents and media content of Media Types other than enlisted above are NOT supported.

More information about supported Media Types can be found in WhatsApp Documentation.

Media Content in Templates

SCG supports (3) types of Media Content referenced in Media Templates.

Media Content

Limitations

Attachment Only one attachment is allowed in a Template Message
Media URL Only one Media URL is allowed in a Template Message
Embedded URL Only one Embedded URL is allowed in a Template Message

 

These limitations are due to the fact that only one Media file is currently supported by WhatsApp API in Media Template Messages.

More information about Media Templates can be found here.

Supported Media Content Size Limits

Media

Size

Limitations

Image 5 MB SCG allows up to 5 MB  of Media size per one Attachment or Media URL.
Video 16 MB The 16 MB limit is only applicable to a Media Template message with an embedded URL. Attachments and Media URL feature are limited to 5 MB.
Document 64 MB The 64 Mb limit is only applicable to a Media Template message with an embedded URL. Attachments and Media URL feature are limited to 5 MB.

 

SCG Attachments and Media URL are limited to 5 MB size per each Attachment or Media URL.

More about Media Templates with embedded URLs can be found below.

Supported Interactive Templates

All (3) types of buttons available in WhatsApp Interactive Messages are supported:

  • Static URL buttons (can only be defined during Template creation and cannot be changed in Template Messages and hence do require anything to be specified during the actual message sending)
  • Dynamic URL buttons
  • Quick Reply buttons

Template Message Syntax

In order to simplify, condense and generalize the use of WhatsApp Template Message, SCG supports its own syntax for Template Message sending.

There are (2) keywords and several attributes, which are used in order for a Template Message to be sent.

The parse keyword is used to describe a name and other metadata information of a given WhatsApp Template.

The set keyword is used to define Template Parameter.

Parameter Attributes are applicable to the set construct and are used to refine a given Template Parameter.

Sample of a Media Template message using the SCG API

curl -X POST 'https://api-int.syniverse.com/scg-external-api/api/v1/messaging/message_requests' -H 'int-companyId: <your company id>' -H 'int-appId: <your application id>' -H 'int-txnId: <your transaction id>' -H 'Content-Type: application/json' -H 'Authorization: Bearer <your bearer token>' --data-raw '{
"from":"<your sender id>",
"to":["<your recipient 1>", "<your recipient 2>"],
"body":"#parse(\"whatsapp:ns=12345678_1234_1234_1234_12345678:name=dentist_appointment:lang=en_US\") #set($header_img=\"https://akme.com/get/my-image-12345678jpg\") #set(John) #set($dt=2021-12-22 10:30)",
"message_type":"WHATSAPP"
}'

 

Please note that all Template Parameters and Metadata is encoded in the API message body. White spaces before the #set constructs are optional and put only for a better visual representation.

Sample of Media Template Message with its Parameters in a WhatsApp Message body

#parse("whatsapp:ns=12345678_1234_1234_1234_12345678:name=dentist_appointment:lang=en_US") #set($header_img="https://akme.com/get/my-image-12345678jpg") #set(John) #set($dt=2021-12-22 10:30)

The sample above consists of one parse construct, which describes what the Template will be used and what language it should be sent in. Also there are (3) set constructs.

Supported Elements of the parse expression

Below is the list of allowed elements of the parse expression. These elements can appear in the parse expression only. 

Supported element

Mandatory

Default value

Description

whatsapp:ns Yes   WhatsApp namespace identifier. Case-sensitive.
name Yes   Template name as it is named in WhatsApp Manager in Facebook Portal. Case-sensitive.
lang No en_US The language code as defined by WhatsApp documentation, the Supported Languages section. Case-sensitive.

 

The parse expression must obey the following rules.

  • White spaces are not allowed within the parse expression anywhere except in between the quote symbols and the parentheses;
  • The metadata information within the parentheses has to be quoted either by double or single quote symbols; 
  • Only the lang element is optional, if it is not specified, then the 'en_US' is assumed;
  • The parse expression is case-sensitive, all the element keys have to be lower-case, the element values as specified in Template WhatsApp Manager. The language code as defined by WhatsApp documentation, the Supported Languages section.

Samples of correct parse expressions

#parse("whatsapp:ns=12345678_1234_1234_1234_12345678:name=dentist_appointment:lang=en_US")
#parse( "whatsapp:ns=12345678_1234_1234_1234_12345678:name=account_update:lang=es_MX" )
#parse('whatsapp:ns=12345678_1234_1234_1234_12345678:name=price_alert') // en_US is assumed
#parse( 'whatsapp:ns=12345678_1234_1234_1234_12345678:name=apartment_confirmation' ) // en_US is assumed

Supported Template Parameter Types

The following Parameter Types are supported by SCG

  • Header Text parameter
  • Header Currency parameter
  • Header Date and Time parameter
  • Header Image parameter
  • Header Video parameter
  • Header Document parameter
  • Body Text parameter
  • Body Currency parameter
  • Body Date and Time parameter
  • Dynamic URL buttons
  • Quick Reply buttons

The Header section can contain only one parameter, either a textual parameter (text, currency, date and time) or a media parameter (image, video, document).

The Message Body section can contain only textual parameters (text, currency, date and time).  The number of parameters is restricted by the maximum length of the body content, which is defined here.

The footer section cannot have parameters.

The Button section can have either up to (2) Call To Action buttons OR up to (3) Quick Reply buttons. Buttons of these two types cannot be used together.

If Call To Action buttons are used, then it is possible to define optionally one Call Phone Number button, which cannot be parameterized in a Template Message. Also optionally, only one Visit Website button is allowed. The Visit Website button is of two types:

  • Static URL Visit Website button - cannot be parameterized in Template Message.
  • Dynamic URL Visit Website button - this type of buttons allows to parameterize the ending (suffix) of the URL. For example, 'https://acme.com/held-desk' would be a fixed part of the URL defined in a Template itself, while the '?user-id=1234' is a dynamic suffix, which can be defined in a Template Message.

Quick Reply buttons allow to parameterize the payload of Quick Reply buttons. For example, a Quick Reply button defined in a Template as 'Satisfied', may be parameterized to '8 score' payload in a Template Message. This payload will be send once the button is clicked.

Template Message Header Parameters

Parameter Type

Syntax

Description

Header Text parameter #set($HEADER_TXT=<a text>) A textual parameter in the Message Header
Header Currency parameter #set($HEADER_CUR=<A currency value>) A currency parameter in the Message Header
Header Date and Time parameter #set($HEADER_DT=<A date and time value>) A date and time parameter in the Message Header
Header Image parameter #set($HEADER_IMG=<URL or 'id' reference>) An image parameter in the Message Header
Header Video parameter #set($HEADER_VIDEO=<URL or 'id' reference>) A video parameter in the Message Header
Header Document parameter #set($HEADER_DOC=<URL or 'id' reference>) A document parameter in the Message Header

Limitations on the Header Parameters

  • Only one of the Header Parameters is supported in the Message Header. This is a limitation of WhatsApp API.
  • The limitations on the Header Text length is described here.
  • Media Parameters (an image, a video or a document) can only be specified for a Message Header.
Supported Attributes in Header Media Parameters

Media Parameter Attribute

Description

Limitations

$HEADER_IMG A URL or 'id'. If a URL is specified, then it should point to an image, which should be taken for a Template Message Header. The Content-Type header of the URL response should be either 'image/jpeg' or 'image/png', as described in the "Supported Media Content Types in Template Messages" section.
$HEADER_VIDEO A URL or 'id'. If a URL is specified, then it should point to a video, which should be taken for a Template Message Header. The Content-Type header of the URL response should be either 'video/mp4' or 'video/3gpp', as described in the "Supported Media Content Types in Template Messages" section.
$HEADER_DOC A URL or 'id'. If a URL is specified, then it should point to a document, which should be taken for a Template Message Header. The Content-Type header of the URL response should be 'application/pdf', as described in the "Supported Media Content Types in Template Messages" section.
$PROVIDER An attribute, which is applicable to all Media Parameters Not supported in the current release.
$FILENAME An attribute, which is used to specify a filename for a document to download by the recipient. Only applicable for a Document Header Parameter.

 

Template Message Body Parameters

Parameter Type

Syntax

Description

Body Text parameter #set($TXT=<a text>) A textual parameter in the Message Body. A simplified version for the Body Text Parameter is possible, namely #set(<a text>)
Body Currency parameter #set($CUR=<A currency value>) A currency parameter in the Message Body
Body Date and Time parameter #set($DT=<A date and time value>) A date and time parameter in the Message Body

Limitations on the Body Parameters

  • No Media Parameters are supported in Message Body. This is a limitation of WhatsApp API.
  • The limitations on the Body Text length described here.
  • There no limitation on a number of the Text, Currency and Date and Time parameters.

 

Template Message Button Parameters

Two types of Buttons are supported by WhatsApp and SCG.

  • Dynamic URL buttons
  • Quick Reply buttons

 

Template Message Button Parameters

Parameter Type

Syntax

Description

Quick Reply Button parameter #set($QUICK_REPLY=<A payload value>) A Quick Reply parameter in the Message Buttons section.
Dynamic URL parameter #set($URL_BUTTON=<A URL suffix value>) A Dynamic URL Button parameter in the Message Buttons section.

Limitations on a number of Buttons allowed in Interactive Templates can be found here.

Supported Attributes in Button Parameters

Button Parameter Attribute

Description

Limitations

$INDEX An index of a Button as defined in Template. Applicable to both Quick Reply and Dynamic URL buttons. This parameter is optional. Allowed values are 0, 1, 2. The numbers in this attribute should go in a consecutive order. 

 

Template Message Date/Day and Time Parameters

Date/Day and Time Parameters can either be specified for the Header section, and only one Parameter is allowed in the Header. Or, a number of Date and Time Parameters can be specified for the Body section.

Supported Attributes in Date/Day and Time Parameters

Date/Day and Time Parameter Attribute

Description

Limitations

$HEADER_DT A Date/Day and Time Parameter for the Header section Only one Parameter is supported for the Header section.
$DT A Date/Day and Time Parameter for the Body section More than one Parameter is supported for the Body section.
Supported Date and Time formats

Format

Description

Sample

Notes

yyyy-MM-dd'T'HH:mm Year, month, day, 24-hour time, minutes #set($dt=2021-11-21T09:27) Hours have to be with a leading zero if necessary.
yyyy-MM-dd H:mm Year, month, day, 24-hour time, minutes #set($dt=2021-11-21 9:27) Leading zero in hours is optional
yyyy-MM-dd h:mm a Year, month, day, 12-hour time, minutes AM/PM #set($dt=2021-11-21 9:30 AM) Leading zero in hours is optional
MM/dd/yyyy H:mm Month, day, year, 24-hour time, minutes #set($dt=11/21/2021 09:30) Leading zero in hours is optional
MM/dd/yyyy h:mm a Month, day, year, 12-hour time, minutes AM/PM #set($dt=11/21/2021 9:30 PM) Leading zero in hours is optional
yyyy-MM-dd'T'HH:mm:ss Year, month, day, 24-hour time, minutes, seconds #set($dt=2021-11-21T09:27) Hours have to be with a leading zero if necessary, seconds are ignored
yyyy-MM-dd H:mm:ss Year, month, day, 24-hour time, minutes #set($dt=2021-11-21 9:27:30) Leading zero in hours is optional, seconds are ignored
yyyy-MM-dd h:mm:ss a Year, month, day, 12-hour time, minutes AM/PM #set($dt=2021-11-21 9:30:45 AM) Leading zero in hours is optional, seconds are ignored
MM/dd/yyyy H:mm:ss Month, day, year, 24-hour time, minutes #set($dt=11/21/2021 09:30:15) Leading zero in hours is optional, seconds are ignored
MM/dd/yyyy h:mm:ss a Month, day, year, 12-hour time, minutes AM/PM #set($dt=11/21/2021 9:30:20 PM) Leading zero in hours is optional, seconds are ignored

Please note, that white-spaces are not allowed, seconds are ignored by the current implementation of WhatsApp API. Date and Time values can be optionally surrounded by single or double quotes. 

Supported Date formats

Format

Description

Sample

yyyy-MM-dd Year, month, day #set($dt=2021-11-21)
MM/dd/yyyy Month, day, year #set($dt=11/21/2021)

Please note, that white-spaces are not allowed. Date and Time values can be optionally surrounded by single or double quotes. 

Supported Day and Time formats

Format

Description

Sample

Notes

EEEE H:mm Day (Monday, Tuesday,.. Sunday), 24-hour time, minutes #set($dt=Tuesday 9:45) Day has to be a full English name for a day, starting with upper-case letter. The rest characters are lower-case. Leading zero in hours is optional.
EEEE h:mm a Day (Monday, Tuesday,.. Sunday), 12-hour time, minutes, AM/PM #set($dt=Tuesday 09:27 PM) Day has to be a full English name for a day, starting with upper-case letter. The rest characters are lower-case. Leading zero in hours is optional.
EEE H:mm Day (Mon, Tue,.. Sun), 24-hour time, minutes #set($dt=Tue 16:45) Day has to be a shortened English name for a day, starting with upper-case letter. The rest characters are lower-case. Leading zero in hours is optional.
EEE h:mm a Day (Mon, Tue,.. Sun), 12-hour time, minutes, AM/PM #set($dt='Wed 09:27 PM') Day has to be a shortened English name for a day, starting with upper-case letter. The rest characters are lower-case. Leading zero in hours is optional.
e H:mm Day (1, 2, 3,.. 7), 24-hour time, minutes #set($dt=1 16:45) Number of day in a week starting from 1. 1 - Sunday, 2 - Monday, etc. Leading zero in hours is optional.
e h:mm a Day (1, 2, 3,.. 7), 12-hour time, minutes, AM/PM #set($dt='2 9:27 PM') Number of day in a week starting from 1. 1 - Sunday, 2 - Monday, etc. Leading zero in hours is optional.

Please note, that white-spaces are not allowed. Day and Time values can be optionally surrounded by single or double quotes. 

Supported Day formats

Format

Description

Sample

Notes

EEEE Day (Monday, Tuesday,.. Sunday) #set($dt=Tuesday) Day has to be a full English name for a day, starting with upper-case letter. The rest characters are lower-case. 
EEE Day (Mon, Tue,.. Sun) #set($dt=Tue) Day has to be a shortened English name for a day, starting with upper-case letter. The rest characters are lower-case.
e Day (1, 2, 3,.. 7) #set($dt=1) Number of day in a week starting from 1. 1 - Sunday, 2 - Monday, etc. 

Please note, that white-spaces are not allowed. Day value can be optionally surrounded by single or double quotes. 

Template Message Currency Parameters

Currency Parameters can either be for the Header section, and only one Parameter is allowed there. Or, a number of Currency Parameters can be specified for the Body section.

Supported Attributes in the Currency Parameters

Currency Parameter Attribute

Description

Limitations

$HEADER_CUR A Currency Parameter for the Header section Only one Parameter is supported for the Header section.
$CUR A Currency Parameter for the Body section More than one Parameter is supported for the Body section.
Supported Currency formats

Format

Description

Sample

Notes

ISO 4217 3-letter currency code, the sign optionally, number The currency code as specified by ISO 4217 standard, optional white-space and a number #set($cur=USD 1000) Negative values are supported
Currency symbol, the sign optionally, number The currency symbol as defined here, optional white-space and a number #set($cur=$-1000) Negative values are supported

Currency value can be optionally surrounded by single or double quotes. The maximum amount of a currency value is 9,223,372,036,854,775.

Template Message Samples

A message sample with Body Text and Date and Time parameters

curl -X POST 'https://api-int.syniverse.com/scg-external-api/api/v1/messaging/message_requests' -H 'int-companyId: <your company id>' -H 'int-appId: <your application id>' -H 'int-txnId: <your transaction id>' -H 'Content-Type: application/json' -H 'Authorization: Bearer <your bearer token>' --data-raw '{
"from":"<your WhatsApp Sender Id>",
"to":["wa:+<your recipient WhatsApp Id>"],
"body":"#parse(\"whatsapp:ns=<your WhatsApp namespace>:name=scg_account_update:lang=en_US\")#set(John)#set($dt=2021-11-11 10:27)",
"message_type":"WHATSAPP"
}'

 

A message sample with Body Text and Date and Time parameters, Spanish-Mexican language and a Date Body Parameter in 12-hour time.

curl -X POST 'https://api-int.syniverse.com/scg-external-api/api/v1/messaging/message_requests' -H 'int-companyId: <your company id>' -H 'int-appId: <your application id>' -H 'int-txnId: <your transaction id>' -H 'Content-Type: application/json' -H 'Authorization: Bearer <your bearer token>' --data-raw '{
"from":"<your WhatsApp Sender Id>",
"to":["wa:+<your recipient WhatsApp Id>"],
"body":"#parse(\"whatsapp:ns=<your WhatsApp namespace>:name=scg_account_update:lang=es_MX\")#set($TXT=Mike)#set($dt=2021-10-29 10:56 AM)",
"message_type":"WHATSAPP"
}'

 

A message sample with a Text Body Parameter, which contains the ' symbol and leading and trailing spaces. Also a Date Body Parameter in month / day / year format.

curl -X POST 'https://api-int.syniverse.com/scg-external-api/api/v1/messaging/message_requests' -H 'int-companyId: <your company id>' -H 'int-appId: <your application id>' -H 'int-txnId: <your transaction id>' -H 'Content-Type: application/json' -H 'Authorization: Bearer <your bearer token>' --data-raw '{
"from":"<your WhatsApp Sender Id>",
"to":["wa:+<your recipient WhatsApp Id>"],
"body":"#parse(\"whatsapp:ns=<your WhatsApp namespace>:name=scg_account_update:lang=en_US\")#set($TXT=\" Sarah O'\''Connor \")#set($dt=12/31/2021)",
"message_type":"WHATSAPP"
}'

 

A message with a Text Body Parameter containing leading and trailing spaces. Also Day and Time Body Parameter.

curl -X POST 'https://api-int.syniverse.com/scg-external-api/api/v1/messaging/message_requests' -H 'int-companyId: <your company id>' -H 'int-appId: <your application id>' -H 'int-txnId: <your transaction id>' -H 'Content-Type: application/json' -H 'Authorization: Bearer <your bearer token>' --data-raw '{
"from":"<your WhatsApp Sender Id>",
"to":["wa:+<your recipient WhatsApp Id>"],
"body":"#parse(\"whatsapp:ns=<your WhatsApp namespace>:name=scg_account_update:lang=en_US\")#set($TXT='\'' if leading and trailing spaces are important '\'')#set($dt=Monday 09:00)",
"message_type":"WHATSAPP"
}'

 

A message with a simplified version of Text Body Parameter containing the '$txt' keyword, which is displayed as a regular text. A Day and Time Body Parameter in 12-hour format.

curl -X POST 'https://api-int.syniverse.com/scg-external-api/api/v1/messaging/message_requests' -H 'int-companyId: <your company id>' -H 'int-appId: <your application id>' -H 'int-txnId: <your transaction id>' -H 'Content-Type: application/json' -H 'Authorization: Bearer <your bearer token>' --data-raw '{
"from":"<your WhatsApp Sender Id>",
"to":["wa:+<your recipient WhatsApp Id>"],
"body":"#parse(\"whatsapp:ns=<your WhatsApp namespace>:name=scg_account_update:lang=en_US\")#set(\"you can just omit $txt actually\")#set($dt=Mon 09:00 PM)",
"message_type":"WHATSAPP"
}'

 

A message with a Currency Header Parameter with ISO 4217 3-letter currency code. A simplified Text Body Parameter.  A Date and Time Body Parameter in year - month - day format and a Currency Body parameter with a currency code separated by a space from a number. German language.

curl -X POST 'https://api-int.syniverse.com/scg-external-api/api/v1/messaging/message_requests' -H 'int-companyId: <your company id>' -H 'int-appId: <your application id>' -H 'int-txnId: <your transaction id>' -H 'Content-Type: application/json' -H 'Authorization: Bearer <your bearer token>' --data-raw '{
"from":"<your WhatsApp Sender Id>",
"to":["wa:+<your recipient WhatsApp Id>"],
"body":"#parse(\"whatsapp:ns=<your WhatsApp namespace>:name=scg_bank_account_update_hbf_params_1:lang=de\")#set($header_cur=EUR123.3)#set(Roman)#set($dt=2021-11-01)#set(1234567654321)#set($cur=INR 234.7)",
"message_type":"WHATSAPP"
}'

 

Currency Parameters with currency symbols. A Date and Time Body Parameter in 12-hour format.

curl -X POST 'https://api-int.syniverse.com/scg-external-api/api/v1/messaging/message_requests' -H 'int-companyId: <your company id>' -H 'int-appId: <your application id>' -H 'int-txnId: <your transaction id>' -H 'Content-Type: application/json' -H 'Authorization: Bearer <your bearer token>' --data-raw '{
"from":"<your WhatsApp Sender Id>",
"to":["wa:+<your recipient WhatsApp Id>"],
"body":"#parse(\"whatsapp:ns=<your WhatsApp namespace>:name=scg_bank_account_update_hbf_params_1:lang=de\")#set($header_cur=¥123.3)#set(Roman)#set($dt= '\''11/21/2021 09:30:23 PM'\'' )#set(1234567654321)#set($cur=₹234)",
"message_type":"WHATSAPP"
}'

 

A Media message with Attachment and Day and Time Body Parameter. Please notice the '#set($header_img=id)' is a placeholder for the Attachment.

curl -X POST 'https://api-int.syniverse.com/scg-external-api/api/v1/messaging/message_requests' -H 'int-companyId: <your company id>' -H 'int-appId: <your application id>' -H 'int-txnId: <your transaction id>' -H 'Content-Type: application/json' -H 'Authorization: Bearer <your bearer token>' --data-raw '{
"from":"<your WhatsApp Sender Id>",
"to":["wa:+<your recipient WhatsApp Id>"],
"body":"#parse(\"whatsapp:ns=<your WhatsApp namespace>:name=dentist_appointment:lang=en\")#set($header_img=id)#set(Laura)#set($dt=1 09:00)",
"message_type":"WHATSAPP",
"attachments": [
    "cTBTDvfvlReWSBijYbDXU6"
]
}'

 

A Media Message with PDF with specified filename and Text Body Parameter with a first and a last name. The '$header_doc=id' is mandatory for attachments.

curl -X POST 'https://api-int.syniverse.com/scg-external-api/api/v1/messaging/message_requests' -H 'int-companyId: <your company id>' -H 'int-appId: <your application id>' -H 'int-txnId: <your transaction id>' -H 'Content-Type: application/json' -H 'Authorization: Bearer <your bearer token>' --data-raw '{
"from":"<your WhatsApp Sender Id>",
"to":["wa:+<your recipient WhatsApp Id>"],
"body":"#parse(\"whatsapp:ns=<your WhatsApp namespace>:name=scg_res_update_document_1:lang=en_US\")#set($header_doc=id;$filename=ticket.pdf)#set(Raul Albiol)",
"message_type":"WHATSAPP",
"attachments": [
    "G64M8Gn0z6LmaDYrXP5em"
]
}'

 

A Media Message with Video using an embedded URL. The URL is quoted by singe quote symbols.

curl -X POST 'https://api-int.syniverse.com/scg-external-api/api/v1/messaging/message_requests' -H 'int-companyId: <your company id>' -H 'int-appId: <your application id>' -H 'int-txnId: <your transaction id>' -H 'Content-Type: application/json' -H 'Authorization: Bearer <your bearer token>' --data-raw '{
"from":"<your WhatsApp Sender Id>",
"to":["wa:+<your recipient WhatsApp Id>"],
"body":"#parse(\"whatsapp:ns=<your WhatsApp namespace>:name=scg_res_update_video_1:lang=en_US\")#set($header_video='\''https://video-den4-1.xx.fbcdn.net/v/t42.1790-2/256307284_929201878008066_1243405808585166680_n.mp4?_nc_cat=111&ccb=1-5&_nc_sid=985c63&efg=eyJ2ZW5jb2RlX3RhZyI6InN2ZV9zZCJ9&_nc_ohc=NiO0exJ3nCcAX8uDWw5&_nc_ht=video-den4-1.xx&oh=04d909230c46f669f07e026d5088cfc1&oe=61929150'\'')#set(Miguel)",
"message_type":"WHATSAPP"
}'

 

A Template Message with a document referenced via an embedded URL, the document file name is specified.

curl -X POST 'https://api-int.syniverse.com/scg-external-api/api/v1/messaging/message_requests' -H 'int-companyId: <your company id>' -H 'int-appId: <your application id>' -H 'int-txnId: <your transaction id>' -H 'Content-Type: application/json' -H 'Authorization: Bearer <your bearer token>' --data-raw '{
"from":"<your WhatsApp Sender Id>",
"to":["wa:+<your recipient WhatsApp Id>"],
"body":"#parse(\"whatsapp:ns=<your WhatsApp namespace>:name=scg_res_update_document_1:lang=en_US\")#set($header_doc=https://download.support.xerox.com/pub/docs/FlowPort2/userdocs/any-os/en/fp_dc_setup_guide.pdf;$filename=document.pdf)#set(Rolland)",
"message_type":"WHATSAPP"
}'

 

A Template Message with a document referenced as a Media URL. Only one Media UR is allowed.

curl -X POST 'https://api-int.syniverse.com/scg-external-api/api/v1/messaging/message_requests' -H 'int-companyId: <your company id>' -H 'int-appId: <your application id>' -H 'int-txnId: <your transaction id>' -H 'Content-Type: application/json' -H 'Authorization: Bearer <your bearer token>' --data-raw '{
"from":"<your WhatsApp Sender Id>",
"to":["wa:+<your recipient WhatsApp Id>"],
"body":"#parse(\"whatsapp:ns=<your WhatsApp namespace>:name=scg_res_update_document_1:lang=en_US\")#set($header_doc=id;$filename=publication2.pdf)#set(Jack)",
"message_type":"WHATSAPP",
"media_urls": [
    "https://www.eurofound.europa.eu/sites/default/files/ef_publication/field_ef_document/ef21055en.pdf"
]
}'

 

A Template Message with Dynamic URL Button Parameter

curl -X POST 'https://api-int.syniverse.com/scg-external-api/api/v1/messaging/message_requests' -H 'int-companyId: <your company id>' -H 'int-appId: <your application id>' -H 'int-txnId: <your transaction id>' -H 'Content-Type: application/json' -H 'Authorization: Bearer <your bearer token>' --data-raw '{
"from":"<your WhatsApp Sender Id>",
"to":["wa:+<your recipient WhatsApp Id>"],
"body":"#parse(\"whatsapp:ns=<your WhatsApp namespace>:name=scg_buttons_url_one:lang=en_US\")#set(Roma)#set($url_button=?param1=val1&var=or-any-othersuffix)",
"message_type":"WHATSAPP"
}'

 

An Interactive Template Message with (3) Quick Reply buttons. First (2) buttons have their payload parameterized. 

curl -X POST 'https://api-int.syniverse.com/scg-external-api/api/v1/messaging/message_requests' -H 'int-companyId: <your company id>' -H 'int-appId: <your application id>' -H 'int-txnId: <your transaction id>' -H 'Content-Type: application/json' -H 'Authorization: Bearer <your bearer token>' --data-raw '{
"from":"<your WhatsApp Sender Id>",
"to":["wa:+<your recipient WhatsApp Id>"],
"body":"#parse(\"whatsapp:ns=<your WhatsApp namespace>:name=issue_resolution:lang=en\")#set(Tom)#set($quick_reply=SI)#set($quick_reply=NO)",
"message_type":"WHATSAPP"
}'

 

Please note, the 1st Button (Satisfied) has its Payload defined as 'SI', while the 3rd Button (Very Satisfied) was not specified as a Parameter, hence its title was sent as is. The 1st Button click response has been encoded as 'SI (Satisfied)'.

 

Pricing

Please contact Syniverse Sales or your Account Representative for pricing information or information on how to get started with WhatsApp Business API messaging.