WhatsApp

Before you Begin

Before you begin, see the initial setup doc for this integrator to get help with the information needed to configure Apteco.

Download the Syniverse Broadcaster Setup Pages.

This guide assumes you have created the Response Database and have set up your FastStats Email Response Gatherer (FERG) folders, BULK insert folder, contact your support department if you need more information.

You do not need to create a Response Database if your system includes PeopleStage.

WhatsApp

In collaboration with Syniverse, we are increasing our integration portfolio with the addition of the WhatsApp. PeopleStage can now send Business initiated messages directly to a WhatsApp conversation initiated by the user, with the user having given their consent to receiving communications from WhatsApp.

The integration supports the following use cases.

These messages are pre-approved by WhatsApp, and can be enriched with personalised content using the data held within your Apteco system.

WhatsApp Business API campaigns can be set up in PeopleStage and scheduled to run as part of a single stage - single channel campaign, or as part of a multi stage - multi channel customer journey.

Recipients can Opt-outClosed An Opt-out is a request to be removed from an marketing communication deployment list for a specific group of messages, or all lists owned by the sender. at any time, and be automatically excluded by PeopleStage, if required. Statistics such as opt out, seen, and delivered can be gathered and reported on within PeopleStage to understand engagement with the Business message.

Download the Syniverse WhatsApp Business API overview.

See the Integrations Matrix for the Syniverse configuration help.

Creative Template

Before you Begin

You must have admin permissions to access this function and define the WhatsApp Creative Template.

You need your WhatsApp Business API Template information which includes the:

  • Template Name(s)

  • Message Content for each template

  • List Name(s)

  • The number of variables and variable(s) to map in the FastStats system, for example FirstName

For more information on what can be included in a template see the developer documentation for the WhatsApp Business API.

  1. Open the Creative Template Editor.

  2. Select - File > Administration > Creative Template Editor.

  3. Click New Creative Template

  1. Select WhatsApp.

  1. Enter the approved template name in the Name field.

  2. Enter the approved creative message in the content area.

  3. Use double curly brackets and the variable number to add a variable place-holder, for example {{1}}.

  4. Click Save.

 

Using the Syniverse Channel in PeopleStage

The steps below describe how to create the channel.

Configuring the Syniverse Channel

You must create a Channel in PeopleStage to use with WhatsApp.

Channel Settings

Blue Highlighted text indicates a required field.

Name Description
Channel Name (required) Enter a name for the channel, e.g. WhatsApp Syniverse
Allow In Transactional Broadcasts Never
Produce output for tests Not Used

 

Output Settings

Blue Highlighted text indicates a required field.

Name Description
Broadcaster (required) Select Syniverse from the drop-down
Email Variable Not used
Variable Description Override Not used
Mobile Number Variable (required) Select the Mobile number variable from the drop-down
Advanced Email Variable Settings The Email Variable drop down enables the check-box option to "Select email variable during campaign creation". This is for use with PeopleStage. Do not use this channel option in Orbit
Variable Description Override Optional
Reply Email Address The reply email address that is used for the message
Reply Mobile Number (required) The mobile number that receives notifications when the channel is used, this integration doesn't work without this number. Needs to include the + number format
Number of Retries 0 (zero)
Response File Key Type Email
Message Content Type (required) PeopleStage WhatsApp Template

Values shown may be for example only, the options differ for each broadcaster.

File Settings

Leave the default settings on this tab for, Syniverse.

Parameter Settings

Broadcast Parameters

A blue highlight indicates a Required field

Parameter Name Parameter Value
Message Type (required) Select a Syniverse messaging channel option: SMS or WABA (WhatsApp Business API).
Access Token (required) The authorised Access Token for your Syniverse Application
Base Url (required) The base url for the Syniverse Api call. e.g. https://api.syniverse.com
Base Path (required) The base path for Syniverse Api call. e.g. scg-external-api/api/v1/
WhatsApp Namespace (required) The WhatsApp Namespace for messaging via the WhatsApp Business API
Language Code (required) Enter a valid language code that is associated with the approved template(s)
Sender Id (required) The Sender Address available from your Syniverse WhatsApp Business API Application
Auto Exclude Opt-Out Automatically exclude those optout of receiving messages from the WhatsApp Business number. Default True. Syniverse SMS doesn't require this parameter.
App Id Application Id of the Syniverse App.
Urn Field Name Overrides the Urn field name used in your FastStats system.
Communication Key Field Name Overrides the communication key field name used your FastStats system.
File Mapping A list of pipe delimited fields (these headings overwrite any defined in your output sequence). e.g. Urn|FirstName|LastName|Company|Email|Message|Discount*
Encoding UTF8

Additional Variables

Common variables used in this section are Forename, Surname, etc. The purpose here is to map any additional FastStats variables to the broadcaster's variables. For example the Forename variable in FastStats may be named FirstName in the broadcaster. This ensures any broadcaster templates that use one of the additional variables are populated correctly.

A blue highlight indicates a Required field.

Variable Description
Variable Click to search the FastStats system for the additional variable.
Variable Description Override Optional, use this field to override the variable header description to match the name in the broadcaster, e.g Forename - FirstName.
Formatting Default is Unformatted, you have the option to apply a naming convention to the variable, either UPPERCASE, lowercase, or TitleCase.
Unclassified as blanks Select how to handle unclassified selector data, use the setting as specified in the system From Design or send no content Empty.
Append Additional Variables Directly Deselected by default, select this option to change how the additional variables are added to the list, either at the End or Beginning. When not set the variables append to the end of the list.

Channel

The WhatsApp for Business API channel must be created by a system administrator.

  • Once configured it is accessible in the deliveries are of the Library

Delivery Step

Create a campaign to use with WhatsApp or add an additional Delivery step to an existing campaign.

  1. Drag the Syniverse WABA channel onto the delivery step.

  2. Click Refresh Channel Message Names to select from the available WABA Creative Templates.

  3. Specifying a separate List name is not required for this channel.

    WABA Delivery

  4. Click on the Preview and Test button to test whether the message name is recognised by Syniverse and that the WhatsApp channel is working correctly before publishing.

  5. When clicking on the Preview and Test button, a Preview screen appears. It is here, you can see a preview of the text in the message and send a test message to yourself to check everything works correctly.

Note: It is advised that you do this before publish to ensure that the message is delivered as expected.

It is currently not possible for Apteco PeopleStage to validate whether the template name specified for a WhatsApp Business API message is correct and approved by WhatsApp (Meta). If you select an incorrectly named or unapproved message name within the Delivery Step in PeopleStage, PeopleStage appears to work but the message isn’t sent by Syniverse. Syniverse then reports an error in sending the message in the platform.

We are working with our partners and WhatsApp to introduce error checking functionality to resolve this issue.

Note: For the reason above, it is advised that you utilise the Preview and Test before publish to ensure that the message is delivered as expected.

Once set up and tested, Add a campaign schedule and Publish the Campaign Live as per any other channel in PeopleStage.

WABA Campaign

Response Gatherer

FastStats Email Response Gatherer - Syniverse

You must create an XML file containing the configuration settings to use with the Email Response Gatherer; the XML file is specified in an argument when you run the EmailResponseGatherer.exe

You can use the Response Gatherer with multiple integrations by using an XML and matching batch file for each integration.

  1. Browse to the directory where you installed the Email Response Gatherer and open the EmailResponseConfig.exe, enter your Connection String and click Test.

  2. Select Syniverse from the Broadcaster drop-down list.

  3. Enter the FTP Username and Password to use with the WABA API.

  4. Use Add to add all the required parameters for the Broadcaster.

  5. Use the File menu to save the XML file to the batch and XML file folder.

Common Response Gatherer Settings

Blue Highlighted text indicates a required field.

Field Settings
Connection String (Required) The connection string to the response database for your system
Timeout (secs) The timeout (in seconds) for the connection and query steps, the default is 1200 seconds
Bulk insert folder (Required) The location to store the results to optimise the processing of campaigns that generate large volumes of data, SQL Server can BULK COLLECT from this location
PeopleStage Connection String Used for certain broadcasters, to retrieve metadata from the PeopleStage database. Not applicable with WhatsApp.

A blue highlight indicates a Required field.

Name Value
Broadcaster * Select Syniverse from the drop down menu. The username and password relates to the ftp access and is often called the API username and password, available from Syniverse
Username* Enter your username
Password* Enter your password
ACCESSTOKEN* Authorised Access Token of the Syniverse Application. This is unique access token provided by Syniverse
BASEURL The base url for Syniverse Api call. Default is https://api.syniverse.com
BASEPATH The base path for Syniverse Api call. Default is scg-external-api/api/v1/
MESSAGEPERIOD This value refers to the period in which you want to check for responses. This can be in days (xD) or months (xM). The default value is 7 days (7D).
MESSAGESTARTDATE Use this to specify a certain start date
MESSAGEENDDATE Use this to specify a certain end date
OPTOUTKEYWORDS Enter the Opt-Out keyword(s) you have defined for individuals to opt out of receiving future WhatsApp messages. Delimited with a comma if there are multiple keywords. e.g. STOP, OPTOUT
AdditionalFields Allows you to specify a pipe (|) delimited list of the additional fields you wish to include in the Response Details table. This only acts as a filter, i.e. you can only specify fields that are included in the extract file. Enter Language for this integration
ConstantFields Pipe delimited field of key value constants, seperated by # e.g. Key1#Value1|Key2#Value2. Enter Broadcaster#Syniverse|System#Media for this integration
EXECUTIONTAG WABA
EXECUTIONBUFFER Adds a buffer in minutes to the start of the response window. Use this to create an overlap to allow for delayed response notifications. -1 recommended for this integration

You need to set FERG to run on a scheduled basis provide it with the broadcaster’s communication details (in a .xml configuration file) and the location to output the log files.

This example uses Windows Task Scheduler however you can use any similar application or create Command Line (.cmd) files manually.

See our Syniverse configuration help