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.
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.
-
Once a user initiated chat has commenced, and with the proviso that an Opt-in
An "Opt-in" can generally be defined as a situation where contacts themselves submit their contact details to an organization, with the expectation that they'll receive marketing communication as a result. has been captured, commercial business-led messaging can be sent directly into a WhatsApp conversation during a 24 hour window. -
Message sent at any time with approved templates in business-initiated chats for opted-in recipients only.
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-out 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.
-
Open the Creative Template Editor.
-
Select - File > Administration > Creative Template Editor.
-
Click New Creative Template
-
Select WhatsApp.
-
Enter the approved template name in the Name field.
-
Enter the approved creative message in the content area.
-
Use double curly brackets and the variable number to add a variable place-holder, for example {{1}}.
-
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 | |
| 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.
-
Drag the Syniverse WABA channel onto the delivery step.
-
Click Refresh Channel Message Names to select from the available WABA Creative Templates.
-
Specifying a separate List name is not required for this channel.
-
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.
-
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.
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.
-
Browse to the directory where you installed the Email Response Gatherer and open the EmailResponseConfig.exe, enter your Connection String and click Test.
-
Select Syniverse from the Broadcaster drop-down list.
-
Enter the FTP Username and Password to use with the WABA API.
-
Use Add to add all the required parameters for the Broadcaster.
-
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