Salesforce Marketing Cloud messaging
This integration between Salesforce Marketing Cloud and Infobip lets you use SMS, WhatsApp, Viber, and Kakao ChinguTalk in your customer journeys.
Installation
To install Salesforce Marketing Cloud, Infobip provides a package containing up to five data extensions:
- SMS Delivery Reports data extension
- SMS URL Tracking data extension
- Omni Reports data extension (for Viber, WhatsApp, Kakao)
- Viber URL Tracking (if needed)
- SampleAudience data extension
- Code Resource for OMNI reports (Viber, WhatsApp, KakaoTalk)
- Code Resource for SMS reports
To deploy the package provided by Infobip:
- Log into your Salesforce Marketing Cloud account.
- From the home page, navigate to Platform > Package Manager.
- Click the Deployment tab and then click Upload from File.
- Select the package file shared by Infobip and click Upload.
- Click Next and then click Deploy.
Once the package is deployed, the data extensions and code resources listed above are configured automatically. Their purpose is to allow message data, such as delivery reports, to be sent from Infobip to your Salesforce Marketing Cloud instance. This in turn allows your system to take action based on the data. For example, if an SMS delivery report indicates that a message failed, then your system can use that status information to retry sending the message.
Important
If you plan to use multiple business units in Marketing Cloud separately for sending messages, deploy this package in every business unit separately.
App Configuration
This section explains how to add components inside the installed package for configuring the connector and sending messages.
Add Installed Package for Integration (Admin)
Important
You must have Admin permissions to do these steps.
- From your Salesforce Marketing Cloud account, go to Setup.
- Select Platform Tools > Apps > Installed Packages.
- Click New, and then enter the package details.
- Click Save.
The next steps are for creating components inside this installed package.
API Integration Component
To add the API Integration component:
- Click Add Component, and then select API integration.
- Choose Server-to-Server Integration type and click Next.
- Choose the Server-to-Server properties.
Before creating Marketing Cloud & Journey Builder components, contact your account manager to get the required endpoints.
Marketing Cloud Component
To add a new component, choose Marketing Cloud and click Next.
Add the endpoint shared by the Infobip team.
Journey Builder Components
To add components for sending messages and receiving reports:
- When adding a new component, select Journey Builder Activity.
- Save the following configuration, add endpoint shared by Infobip team.
- For reports, create new Journey Builder Activity components and add endpoint shared by Infobip team.
Once the components are complete, give access to any user who wants to use this application inside the Journey Builder. Without these permissions, the application is hidden.
Note
The setup must be done for every business unit separately.
Configure Infobip Configuration app
Infobip Configuration is a Marketing Cloud app that allows the user to set global variables before starting to use Journey Custom Activity for sending messages. Users are allowed to change it anytime they launch an Infobip config app.
To go to the Configuration app, on the Marketing Cloud homepage, hover over the AppExchange icon, and you see the Infobip Configuration.
Add the following information to the Infobip Configuration app:
- MID – The ID of your business unit, which can be found in top right corner of the SFMC screen.
- SOAP Base URI – the tenant specific SOAP Base URI, which can be found in the API installed package.
- Auth Base URI – the tenant specific Authentication Base URI.
- Client Secret
- Client Id
Once you click Connect, the data is saved securely in the Infobip configuration data extension using encryption methods and the next section is enabled.
In the next section, update following information:
- Add API key – add API key received from Infobip, available here
- Add base URL – add custom domains for URL shortener
- Custom Domain - add the domain that you would use when adding urls*
- SMS Sender Name – your sender name for SMS channel*
- Viber Sender Name – your sender name for Viber channel*
- Kakao Sender name – your sender key for Kakao channel*
- SMS Notification URL – webhook code resource url for SMS reports
- OMNI Notification URL – webhook code resource url for other channel reports
* When adding sender names or custom domains, after typing the name, press ENTER which creates a token similar to in the screenshot below.
Important
Notification URLs are mandatory if you want to receive delivery reports in Marketing Cloud.
Sender names are mandatory in case you are using senders that are not configured for 2-way communication.
When all fields are added, click Validate and then Save changes. If everything is successful, you receive confirmation that the information has been saved.
Journey Audience
To prepare the journey audience, the following steps are important:
- Set the destination used for sending messages as the attribute type Phone
- Set the proper relationship for the Subscriber key
- Enable the Used for Sending feature
Note
Attribute names must not include any spaces because Infobip Message will not be able to process it.
For configuring the subscriber key relationship and sending feature, click Edit on the left side of the screen, then check Used for Sending and map your ContactKey field to relate to the Subscriber key. Click Save.
Your data extension is now ready for use in the Journey Builder. The next step is to map the Journey data extension to system data and message reports.
Note
Infobip connector also works with Salesforce Data entry source (Salesforce Campaign and Salesforce Data are supported).
How to Create a Journey Using Infobip Channels
This section gives an example of how to create a journey that includes an SMS, Viber, WhatsApp, or Kakao message. To get started:
- Log into Salesforce Marketing Cloud and go to Journey Builder.
- Create the new journey.
- Select whether to build a multi-step journey with Data Extension or Salesforce Data entry point.
- Select the data extension that was created for this journey.
Note
This Infobip connector also works with Salesforce Data Entry Source (Salesforce Campaign and Salesforce Data are supported).
Include a Message in a Journey
Important
Make sure that you have Administrator role or you allow the Manage Data (Email/Subscribers/Data Extension) and WebService API (Email/Admin/API Access) permissions in your user settings.
Select Infobip Message Custom Activity and enter the MID and Communication channel you would like to use. Then, click Next.
Important
You must define Data Extension before configuring the Infobip Message element. If you include Data Extension after already defining the Infobip Message element, you may experience issues with the Journey, for example, not being able to pull records from Data Extension when messages are being sent.
By default, Bulk Id in reports is defined for SMS and Viber as Infobip SMS and Infobip Viber, respectively. To change Bulk Id to a different value, provide a different activity name before the activity is configured.
SMS
Set up the message according to the form and click Next. For SMS, you can add a link to the message for URL tracking. When an end user clicks the link, a report is sent to the SMS URL Tracking data extension. You can send a test message if you want to, but the journey must be activated and you cannot use placeholders in test messages.
To add tracking and URL shortening for URLs in the SMS body, select URL Shortening & Tracking.
You can use the default domain or choose the domain from the list that was added in the Infobip Config.
To remove https:// from the URL, select Remove https:// from domain.
For India local traffic only
To define the DLT (Distributed Ledger Technology) template, select DLT Template (India local traffic only) and update the following fields:
- Principal Entity ID (mandatory) - Your assigned DLT principal entity ID
- Content Template ID (optional) - The registered DLT content template ID that matches the message you are sending
Viber
In addition to supporting text, you can include an image URL, a button name, and a button URL in a Viber message. Choose your message type from the dropdown list.
You can personalize the message by adding merge fields from the dropdown list.
Viber (deprecated)
Important
Do not use this deprecated activity. Use the new Viber activity instead.
In addition to supporting text, you can include an image URL, a button name, and a button URL in a Viber message. You can also personalize these elements.
After you click Next, then click Verify Scenario Key to finish the configuration.
WhatsApp
With WhatsApp you can send a templated message from Marketing Cloud directly to your customers. Supported templates are:
- Text Templates
- Media Templates
Check more about supported templates here.
KakaoChinguTalk
This channel lets you include these elements in a message:
- Text
- Image URL
- Image link
- Up to 5 buttons (supported types are web link and app link)
After you click Next for Kakao, then click Verify Scenario Key to finish the configuration.
Important
Custom domain URL shortening is currently only supported for SMS.
Error handling for Infobip Message Custom Activity
In situations where a user makes an error or if Marketing Cloud doesn't send all of the details for a successful request, the app returns messageStatus as outArgument in the Journey Data, rather than a hard error. A hard error would cause the record to become stuck on this activity and not continue with the journey.
So, if something is wrong with the request, the app returns success but with an additional payload that describes the error. You can use this payload to evaluate whether you wish to re-engage the record with another message.
This type of error handling is useful for validating and creating a decision split when the request record is re-engaged. For example, the following scenario describes decision split checking where the phone field is empty. In this example, you can see a data extension where one record has phone and the other record is empty.
To set up the decision split, add the data extension to a journey as an entry source and configure Infobip Message activity.
Create the decision split and choose messageStatus from Custom Activity (Infobip SMS).
You can see in this example that messageStatus is: Error: Missing phone number in request.
The result of the sample send is similar to the following:
The record with an empty phone number is injected to the NO PHONE NUMBER path.The record with a phone number follows the WITH PHONE path.
In the custom activity details, you see a Success status.
In the status detail for the record with the empty phone, you see the BadRequest status.
See the following table for the full list of possible responses for messageStatus and the channels available for that response.
messageStatus |
Channels |
---|---|
Success: Message pending |
WhatsApp, SMS, Viber, Kakao |
Error: Missing trackClicks flag |
Viber, SMS |
Error: Missing shortenUrl flag |
Viber, SMS |
Error: Missing phone number in request |
SMS, WhatsApp, Kakao, Viber |
Error: Invalid tracking url length |
Viber, SMS |
Error: Invalid text length |
SMS, WhatsApp, Viber |
Error: Invalid template name |
|
Error: Invalid scenario key |
Viber |
Error: Invalid promotional flag |
Viber |
Error: Invalid image url length |
Viber, Kakao, |
Error: Invalid from field |
WhatsApp, Kakao, Viber |
Error: Invalid custom domain length |
Viber, SMS |
Error: Invalid buttons field length |
Kakao |
Error: Invalid button url length |
Viber |
Error: Invalid button text length |
Viber, Kakao |
Error: Invalid button text length |
Kakao |
Error: Invalid androidScheme and iosScheme length |
Kakao |
Get Message Report
After you add the Infobip Message element, you can add the Infobip Get Reports element to retrieve a report from the message that was sent.
You can select the message that was configured inside the journey under Select message activity and the data extension where the report has been saved under the Select data extension drop-down list.
The available data extensions for reports are:
- SMS URL Tracking & Viber URL Tracking for fetching information if the link inside message was clicked
- SMS Delivery Reports & OMNI Reports for fetching if the message was delivered or rejected
Message status is saved under Journey Data and it is available in the decision split.
Important
In the cases where Infobip is trying to deliver a message on a device for some time, no report is created in the data extension. For this, you see Journey Data NOT_AVAILABLE for delivery reports and NOT_CLICKED for click reports.
Set Up a Decision Split
After you set up the activity for saving messageId, you can define a decision split in the flow:
- Click Edit.
- Under Attributes, click Journey Data.
- Click Custom Activity: Infobip Message Report
- Depending on the report data extension that you selected in the previous step, you see statusName for Delivery reports and the URL for URL Tracking reports.
The vailable parameters for Delivery reports are:
- statusName
- statusGroupName*
- errorName
- doneAt
- sentAt
- seenAt (for Omni reports)**
The vailable parameters for URL Tracking reports are:
- notificationType
- url***
Note
** If seenAt is not empty, add SEEN as the value in decision split. Otherwise, use NOT_SEEN.
*** For URL clicks in SMS messages, you can check the exact value of URL parameters (for example, which URL is being tracked).
For example, if https://www.infobip.com was the URL sent in the message, the decision split branch should check if the URL is equal to https://www.infobip.com. If there is no click report saved for a specific customer, check if the URL is equal to NOT_CLICKED.To see if a Viber message was viewed, check whether the seenAt value in the Omni message report is not null.
For descriptions of the possible message statuses, see the Response Status and Error Code documentation.
There are five statuses that are returned to Journey Data in a Decision Split:
- DELIVERED
- The message has been successfully processed and delivered.
- If you want to check whether the message arrived to the customer's device, DELIVERED_TO_HANDSET is returned and checked in the decision split.
- UNDELIVERABLE
- This status is returned if the message was sent to the operator but it was rejected by them or they returned UNDELIVERED status.
- Multiple statuses can be returned, so it's best to check if statusName begins with UNDELIVERABLE.
- REJECTED
- The message has been received but has either been rejected by Infobip or the operator has reverted REJECTED as final status.
- Multiple statuses can be returned, so it's best to check if statusName begins with REJECTED.
- EXPIRED
- The message has been sent and has either expired due to pending past its validity period (our platform default is 48 hours), or the delivery report from the operator has reverted the expired as a final status.
- Multiple statuses can be returned, so it's best to check if statusName begins with EXPIRED.
- NOT_AVAILABLE
- Delivery of the message is pending (message is not yet delivered, however it can technically be delivered), the operator keeps trying to deliver the message until its expiry.
- To check this status, add a new branch and check if statusName begins with or is equal to NOT_AVAILABLE.
Set Up Contact Information for the Journey
After you finish setting up the journey, you need to select a Contact Entry to use. You map the default mobile number to the data type, Phone, in your data extension. This is available from the drop-down.
IMPORTANT
When setting up a Journey based on a copy of an already existing Journey, make sure that you've reconfigured the Infobip message activity, otherwise you receive an error message.
When activating Journeys based on automations, make sure that the data extension entry source is already defined and the automation already exists before running journeys.
Appendix
OMNI Reports
OMNI Delivery Reports
Attribute Name |
Attribute Type |
Is nullable |
Default value |
Length |
Description |
messageId |
Text |
50 |
The ID that uniquely identifies the message sent. |
||
messageCount |
Integer |
x |
1 |
Number of messages sent to end user. Count is always 1. |
|
to |
Text |
50 |
Message destination address. Addresses must be in international format |
||
pricePerMessage |
Decimal |
x |
The price per individual message. |
||
priceCurrency |
Text |
x |
5 |
The currency in which the price is displayed. |
|
statusGroupId |
Integer |
Status group ID. |
|||
statusGroupName |
Text |
50 |
Group name for the status. |
||
statusId |
Integer |
Status ID. |
|||
statusName |
Text |
50 |
Status name. |
||
statusDescription |
Text |
100 |
Human-readable description of the status. |
||
errorGroupId |
Integer |
x |
Yes |
Error group ID. |
|
errorGroupName |
Text |
x |
50 |
Error group name. |
|
errorId |
Integer |
x |
Error ID. |
||
errorName |
Text |
x |
50 |
Error name. |
|
errorDescription |
Text |
x |
1000 |
Human-readable description of the error. |
|
errorPermanent |
Boolean |
x |
Indicates whether the error is permanent. |
||
callbackData |
Text |
x |
4000 |
The callback data sent through the callbackData field in your fully featured message. |
|
sentAt |
Text |
50 |
Date and time the message was sent. |
||
doneAt |
Text |
50 |
Date and time the message was finished processing by Infobip. |
||
seenAt |
Text |
x |
50 |
Tells when the message was seen. |
|
from |
Text |
x |
50 |
||
channel |
Text |
x |
50 |
Channel which was used for sending messages |
Viber URL Tracking
Attribute Name |
Attribute Type |
Is nullable |
Default value |
Length |
Description |
notificationType |
Text |
x |
50 |
CLICKED |
|
messageId |
Text |
x |
50 |
The ID that uniquely identifies the message sent. |
|
recipient |
Text |
x |
50 |
Contact who clicked on the URL |
|
url |
Text |
x |
1000 |
URL that was clicked in message |
|
sendDateTime |
Text |
x |
50 |
Date and time contact clicked on the URL in UNIX format. |
|
deviceType |
Text |
x |
50 |
Phone or desktop |
|
os |
Text |
x |
50 |
OS running on the device |
|
deviceName |
Text |
x |
50 |
Device manufacturer (Samsung, PC, Apple) |
|
callbackData |
Text |
x |
4000 |
The callback data sent through the callbackData field in your fully featured message. |
SMS Reports
SMS Delivery Reports
Attribute Name |
Attribute Type |
Is nullable |
Default value |
Length |
Description |
messageId |
Text |
50 |
The ID that uniquely identifies the message sent. |
||
messageCount |
Integer |
x |
1 |
Long SMS messages have a character limit on how much can be sent over one message. |
|
to |
Text |
50 |
Message destination address. Addresses must be in international format |
||
pricePerMessage |
Decimal |
x |
The price per individual message. |
||
priceCurrency |
Text |
x |
5 |
The currency in which the price is displayed. |
|
statusGroupId |
Integer |
Status group ID. |
|||
statusGroupName |
Text |
50 |
Group name for the status. |
||
statusId |
Integer |
Status ID. |
|||
statusName |
Text |
50 |
Status name. |
||
statusDescription |
Text |
100 |
Human-readable description of the status. |
||
errorGroupId |
Integer |
x |
Yes |
Error group ID. |
|
errorGroupName |
Text |
x |
50 |
Error group name. |
|
errorId |
Integer |
x |
Error ID. |
||
errorName |
Text |
x |
50 |
Error name. |
|
errorDescription |
Text |
x |
1000 |
Human-readable description of the error. |
|
errorPermanent |
Boolean |
x |
Indicates whether the error is permanent. |
||
callbackData |
Text |
x |
4000 |
The callback data sent through the callbackData field in your fully featured message. |
|
sentAt |
Text |
50 |
Date and time the message was sent. |
||
doneAt |
Text |
50 |
Date and time the message was finished processing by Infobip. |
||
originalMCC |
Text |
x |
50 |
Mobile country code of the recipients number |
|
originalMNC |
Text |
x |
50 |
Mobile network code of the recipients number |
|
channel |
Text |
x |
50 |
Channel which was used for sending messages |
SMS URL Tracking
Attribute Name |
Attribute Type |
Is nullable |
Default value |
Length |
Description |
notificationType |
Text |
x |
50 |
CLICKED |
|
messageId |
Text |
x |
50 |
The ID that uniquely identifies the message sent. |
|
recipient |
Text |
x |
50 |
Contact who clicked on the URL |
|
url |
Text |
x |
1000 |
URL that was clicked in message |
|
sendDateTime |
Text |
x |
50 |
Date and time contact clicked on the URL in UNIX format. |
|
deviceType |
Text |
x |
50 |
Phone or desktop |
|
os |
Text |
x |
50 |
OS running on the device |
|
deviceName |
Text |
x |
50 |
Device manufacturer (Samsung, PC, Apple) |
|
callbackData |
Text |
x |
4000 |
The callback data sent through the callbackData field in your fully featured message. |