Skip to Content

Introduction

Welcome to the blog post of the Expert Services Marketing Practice.

We are happy to share our experience with you around Marketing Integration, Analytics, and Business Technology.

You want to see more? Click here

Background

With Social media channels becoming more important for companies to interact with their customers, we have described a generic use case to explain how companies can send personalized messages with WhatsApp.
With this simplified scenario, we enable to send messages to active WhatsApp subscribers, delivering personalized content.

Rather on focusing on a functional use case this blog post describes an exemplary technical set up, how a scenario like this can be implemented. To push the messages to the mobile devices, we have used WhatsBroadcast as messaging service.

With this setup, we have used the trial account provided by WhatsBroadcast (https://www.whatsbroadcast.com/).

 

In this Blog Post,

We focus on sending out personalized messages to active individuals on WhatsApp.
We mainly focus on the capabilities of the integration technologies and 3rd party applications used for this scenario.

The general approach and setup is described.

  • SAP Hybris Marketing Cloud
  • SAP Cloud Platform Integration
  • SAP Cloud Platform API Management
  • WhatsBroadcast
  • WhatsApp

 

Technical Configuration Overview

The following illustration describes the general approach how to set up WhatsApp integration with SAP Hybris Marketing.

  1. Setup the communication configurations on Hybris Marketing and define an Open Channel.
    To set up outbound communication from Hybris Marketing, follow the instructions on the SAP Help Portal.
    https://help.sap.com/viewer/p/SAP_HYBRIS_MARKETING_CLOUD
  2. Because we are using Open Channel for sending data from Marketing Cloud, we can’t use message personalization with Hybris Marketing Design Studio.
    We have configured a Custom Business Object what stored the message templates for the personalized messages.
    Each message is assigned to an active campaign and is extracted from Cloud Platform Integration when the campaign is executed.
  3. The data send from Hybris Marketing in received and processed on the middleware.
    On Cloud Platform Integration, the message template stored in the custom business object is extracted and enriched with the consumer information delivered from the Open Channel message. The personalized message is then forwarded to WhatsBroadcast.
  4. WhatsBroadcast received the personalized messages and pushed the message to the user with the corresponding user id.
    Before forwarding the message to WhatsBroadcast, we make sure that the user is active and has subscribed to receive messages.
  5. WhatsBroadcast send the message to a specific user, registeed on WhatsBroadcast.
    WhatsBroadcast listens to the chat interactions and can trigger a message to an external system.
  6. A Webhook on WhatsBroadcast is configured to an external system, sending messages for chat interactions from the WhatsApp user.
  7. To restrict access to the endpoint, we have protected the Cloud Platform Integration endpoint using API Management.
    SAP Cloud Platform API Management  is configured to allow access without user credentials and forward the message to the middleware securely. Further, we have configured access restrictions and quotas to allow only defined Servers to send messages to the API as well as access limitations.
  8. Relevant interactions are forwarded to Cloud Platform Integration, processed and imported to Hybris Marketing.
    In this use case we have considered 3 different types of interactions.
    – New user subscribed to the WhatsApp Chat
    – Subcribe/unsubscribe by the WhatsApp user
    – General interactions
  9. The interactions are imported to Hybris Marketing cloud and assigned to a contact.

 

SAP Hybris Marketing Cloud – Release E-Mail addresses to be validated

Configure WhatsBroadcast

In this blog post, we have used a trial version, provided by WhatsBroadcast. For easier onboarding, the WhatsBroadcast team have already automated the WhatsApp broadcasting procedure. With this initial setup already done by the WhatsBroadcast team, users can subscribe to your trial channel.

  1. Create an account with WhatsBroadcast.
  2. Embed the registration widget on website or other point of access.
  3. Have some active users

The registration widget can easily places as a HTML snipped on you web site or share the direct link.

Configure WhatsApp

Download the app and register with WhatsApp. Next, simply follow the instructions to subscribe to a new WhatsApp chat.

Configure SAP Hybris Marketing Cloud

As with all new scenarios, start with setting up the communication between SAP Hybris Marketing Cloud and the connected system, in this case SAP Cloud Platform Integration.

Define Permission Marketing

First, go to the  SAP Help Portal and read through the Permission Marketing chapter for Hybris Marketing Cloud (link below)
Basically, what you need to do is to create a new communication media and assigned this to the Origin MOBIL. This is because the WhatsApp ID is tied to the mobile phone number you have registered with WhatsApp.

Permission Marketing
https://help.sap.com/viewer/b88f770e4b7c4ecead5477e7a6c7b8f7/1708%20500/en-US/79b996a75b024dc3a7c02fcf755c3e12.html

Hybris Marketing Outbound: Open Channel

Define a  Communication System, Arrangement, and User for the Open Channel.
Add a custom logic in the Custom Field and Logic app and add this in the Communication Arrangement as the Implementation ID. Next, create an export definition for Open Channel on all consumers. Once this is done you can create a target group a define a blank automated campaign. This is where all the configuration comes together.
In the campaign automation, select the target group you have created and add a new action. Select the Custom Logic you have defined and select the Export Definition containing all fields that needs to be exported.

I have described the Open Channel Configuration in more detail in another Blog Post (https://blogs.sap.com/2017/08/04/sap-hybris-marketing-cloud-verifying-e-mail-addresses-with-neverbounce-overview/).

Hybris Marketing Inbound: Custom Business Object

Create a new Custom Business Object to maintain the WhatsApp campaign data. You’ll need at least custom fields for to save the campaign ID, message template and image URL. Enable the checkboxes for generating an UI and Service.
Publish the Custom Business Object and create a new Custom Scenario to associate with an inbound communication arrangement, system and authentication settings.
You can find information on how to create and use CBOs on SAP Help.

Hybris Marketing Inbound: Master Data Import

For importing interaction we use the CUAN_IMPORT_SRV Odata Service available on Hybris Marketing.
Configure the standard scenario SAP_COM_0003.

SAP Help Portal – SAP Hybris Marketing Cloud
https://help.sap.com/viewer/p/SAP_HYBRIS_MARKETING_CLOUD

Note:
There is currently no dedicated facet for WhatsApp. By this no data for the WhatsApp ID and opt-in/opt-out is maintained in the system as standard.
With this demo scenario, we have derived the WhatsApp ID from the mobile phone number.

SAP Cloud Platform Integration

With this scenario, we are using to different Iflows, one for processing messages from Hybris Marketing to WhatsApp via WhatsBroadcast) and another for collecting chat interaction from WhatsApp (via WhatsBroadcast and AP Management)

WhatsApp to SAP Hybris Marketing

Before we send out any messages for Hybris Marketing, we need to make sure that the WhatsApp User has subscribed to out Newsletter/Chat and is active. To do so, we need to capture the moment when the WhatsApp User subscribes to out Newsletter/Chat. Luckily, WhatsApp capture these actions and provides this for you to import to Hybris Marketing.

Since the WhatsBroadcast Webhook is pushing messages without authentication, we want to protect out Cloud Platform Integration endpoint from un-allowed access. For this we use SAP Cloud Platform API Management. The API Management restricts access and only forwards relevant messages to Cloud Platform Integration. These interactions are then imported to Hybris Marketing.

This process is triggered when the WhatsApp user subscribes to our WhatsApp Channel. This is captured by the WhatsBroadcast Webhhook, and send to the API on SAP Cloud Platform.

SAP Cloud Platform Integration IFlow

The message from API Management is converted to XML file and properties extracted for the routing conditions.

With  the Router Integration Pattern, we define from the properties if this is a marketing permission interaction, new subscription, or general interaction.

1) We choose this branch, when the WhatsApp User subscribes to the WhatsApp Channel.

{
"messages": [{
"id": "31082960",
"messenger": "WA",
"usernumber": "15551112222",
"date": "1505399516",
"attachment": "",
"attachment_type": "",
"text": "Start",
"welcome": "1",
"channelnumber": "4911122222222",
"userstatus": "1"
}]
}

2) When the WhatsApp User unsubscribes from our WhatsApp channel, we define a interaction to restrict us from Hybris Marketing to contact this user via WhatsApp.

{
"messages": [{
"id": "31083118",
"messenger": "WA",
"usernumber": "15551112222",
"date": "1505399636",
"attachment": "",
"attachment_type": "",
"text": "Stop",
"welcome": "0",
"channelnumber": "4911122222222",
"userstatus": "0"
}]
}

3) If the User interacts with the chat, we define a general interaction. This can be used for example to execute trigger based campaigns or import interaction with the Chat Bot.

{
"messages": [{
"id": "31083054",
"messenger": "WA",
"usernumber": "15551112222",
"date": "1505399586",
"attachment": "",
"attachment_type": "",
"text": "Hi, what's up?",
"welcome": "0",
"channelnumber": "4911122222222",
"userstatus": "1"
}]
}

The Iflow logic for this one is pretty simple.
The inbound message on Cloud Platform Integration is converted to XML and exchange properties to be used in the Router defined. The Router direct the message to the correct Message Mapping where the inbound message is mapped to the correct target structure. After that, the message is send to SAP Hybris Marketing Cloud.

SAP Hybris Marketing to WhatsApp

This Iflow processes the message that is send from the Open Channel, creates a personalized message and forwards this to WhatsBroadcast.  WhatsBroadcast then pushed the message to WhatsApp.
Before we start creating an Iflow we need to understand what processing logic needs to be implemented to achieve our goal. We basically like to send a personalized message to our WhatsApp user. To do so, we need to make sure, that the message is received, enriched with personalized content and delivered to the WhatsApp User.

The personalized message is send to the active WhatsApp user through WhatsBroadcast.

Here we have a very simple message what is defined and maintained in the campaign execution in Hybris marketing (see illustration above).

SAP Cloud Platform Integration IFlow

The Iflow consist of one main and two local integration processes.

  • The main process (1) receives, maps, and sends the message to the receiver.

In the main process we call the local integration processes, split the message to process each target group member separately, and do the message mapping. For each target group member, the activity status of the user is verified before sending the message to WhatsApp via WhatsBroadcast.

  • The WhatsAppCampaign process (2) calls the configured CBO on Hybris Marketing to retrieve the WhatsApp campaign data.
  • The checkActiveUser process (3) confirms that the WhatsApp Users is active and subscribed to our WhatsApp Chat.

We have covered the basic steps how to transform and verify the message before sending this to the WhatsApp user.

SAP Cloud Platform API Management

The WhatsBroadcast Webhook sends a POST request to the configured URL.
To avoid access from unknown sources, we have configured a simple API with SAP Cloud Platform API Management.

The configured API does the following:

  • Set access control via IP range
    • Different options are available, for this demo scenario we just allow access from specific IP range.
  • Set a quota
  • Forward the message to SAP Cloud Platform Integration with Basic Authentication

First, you need a SAP Cloud Platform API Management account.
You can use the trial version for testing the capabilities and setting up your first scenarios.
How to get the trial version is described in this Blog Post: https://blogs.sap.com/2016/02/02/free-trial-of-sap-api-management-on-hana-cloud-platform-is-available-now/.

Once your account is set up follow the documentation on SAP Help to set up API Management and assign users.
SAP Help Cloud Platform API Management: https://help.sap.com/viewer/66d066d903c2473f81ec33acfe2ccdb4/Cloud/en-US/adcbc07b031b4ac285b22867a1216306.html
This Blog Post describes very well how to create API with API Managament and what roles are needed (https://blogs.sap.com/2016/02/24/building-consuming-apis-using-sap-api-management-part-1/).

Create an API to pass through the message to the endpoint you have configured on SAP Cloud Platform Integration.
An API Proxy URL is created for the sending system, in our cats WhatsBroadcast, to send messages to.

Add a new Resource with POST operation to allow the sender to send POST request to the API.

Next, create a new policy to ensure only messages from a defined IP range are allowed. Add a quota to limit the amount of messages accepted in a specific timeframe. Next define the Authorization header in the TargetEndpoint Flow.

With these couple steps we have successfully configured a API to pass-through message payloads from the WhatsBroadcast Webhook.

The Message is received on Cloud Integration, processed, and forwarded to SAP Cloud Platform Integration.

Refer to the WhatsBroadcast API for webhook details.
WhatsBroadcast API documentation: https://api.whatsbroadcast.com/

Summary

We have simplified the process to illustrate the basic procedure using only standard integration patterns. With this to be used as basis for further enhancements you can easily create your own WhatsApp Integration with SAP Hybris Marketing Cloud.

We have tested the scenario with dummy data only in the amount of couple hundreds. If you are planning to send higher amounts of messages, the Iflows described here must be re-designed to ensure that all messages are delivered and processed. To do so we provide multiple options to ensure the messages are processed and delivered.

With this approach, we have used a Custom Business Object to maintain campaign data. This is because at the time this blog post was created, Open Channel did not provide the option to include dynamic campaign data. This is subject to change.

We have mainly focused on how to leverage integration technologies to implement process logic when connecting SAP Hybris Marketing Cloud with 3rd party applications.

The WhatsBroadcast configuration is fairly easy and provides more functionalities that the ones described in this blog post.

All in all, this blog post will give you an idea on one approach, how to implement a personalized campaign from SAP Hybris Marketing Cloud.

Trial Accounts

 

You want to see more? Check out all of our blogs here.

Your SAP Hybris Expert Services – Marketing Practice team.

To report this post you need to login first.

7 Comments

You must be Logged on to comment or reply to a post.

  1. Tim Nusch

    Hi Johannes,

     

    thanks! Very well written!

    You mentioned that for higher amounts of messages the Iflows would need to be re-designed. Can you briefly describe which parts would change?

     

    Best regards,

    Tim

    (0) 
    1. Johannes Hirling Post author

      Hi Tim,

      We did not configure error handling with this IFlow. With this when the Iflow fails, the message is not guaranteed to be delivered to the receiver system.

      To ensure that all messages are delivered once, we need to enable Quality of Service Exacly-once.

      We cando this using a JMS Queue or build a exacly-once scenario manually.

      best,
      Johannes

       

      (0) 
    1. Anton Peters

      Hi Amornnart,

       

      I just checked the line API: https://developers.line.me/en/docs/messaging-api/reference/#text-message

      Looks feasible to me, but we would need to do a quick test to tell for sure. In case you try by yourself, please let us know the result.

      In addition I would pay close attention to the new releases – new outbound channels get added on a regular basis.

       

      Best regards, Anton

      (0) 
    2. Johannes Hirling Post author

      Hi,

      just went through the Line API documentation from the link Anton provided.

      This should work similar to WhatsApp via WhatsBroadcast (at least for the messaging part).

      br,

      Johannes

      (0) 

Leave a Reply