Configuring the integration
Here we’ll show you how to get started using the charles x Emarsys integration.
Pre-requisites
Requirement | Description |
Emarsys Account | An Emarsys Administrator account is needed. |
Emarsys API User | An Emarsys API user 🔗 is required by charles to interact with your Emarsys account. As Emarsys Account Owner, you can get it from Security Settings > API Users. The following permissions need to be granted: contact.getdata contact.singleUpdate contact.update export.contact.changed export.contactlist export.download export.segment export.status field.get field.list field.multichoice.get field.singlechoice.list field.singlechoice.lang.list field.singlechoice.trans.list segment.get segment.list segment.contact.list combinedsegment.list |
Emarsys Integration was enabled | During the beta stage, the Emarsys integration needs to be enabled on a per-customer basis. Please reach out to your CSM for enabling the marketplace. |
In charles
Go to Settings > Integrations > Marketplace
Find Emarsys and select Connect. A pop-up will appear
Configure the connection using Pre-requisites
Once it’s successful, you should find Emarsys in the Connected apps section.
Configuring the features
Import Emarsys contacts into charles
Field Mapping
By default, we import the following fields from Emarsys into charles
Source (Field on Emarsys) | Destination (Field on charles) |
First Name | Last Name |
Last Name | Last Name |
Phone | Phone Number |
Email Addresses |
If you want to import additional custom fields from Emarsys into charles, you can add additional field mappings, via the configuration page.
Limitations: - 20 custom fields is the maximum you can import - 500k contacts is the maximum size a segment should have for the import into charles
Import from Emarsys
You can configure the segments that should be imported from Emarsys in the settings of the integration.
After configuring the integration, the configured segments will be imported once.
Afterwards, they will be imported incrementally every 12h.
During the import, we will stitch/merge the new contacts to existing contacts based on the phone number and email address.
After the contact is stitched, the latest opt-in status will be synced with Emarsys.
Incremental import from Emarsys
Every 12 hours we import the latest changes in contacts. Only fields that are selected in the field mapping are taken into account to determine whether the contact is updated.
Opt-in Export from charles to Emarsys
Everytime an end-user grants or withdraws an opt-in on charles, then we will send this information to Emarsys.
Configuration:
Create a custom property in Emarsys.
name: no hard requirement, for example “WhatsApp opt-in”
field type:
text
Select the field on page 3.
Set up an Emarsys automation program that triggers a charles flow using a CUSTOM Event
The Emarsys webhook node comes with some limitations, please check the Emarsys documentation for details.
This use case involves two components that need to be configured: The automation program that sends events to charles on Emarsys and the charles flows.
Component 1 - Set up the Emarsys automation
1a - Create the Webhook preset
Create the webhook present in Emarsys. Docs
Configure the Connection values as follows:
ield | Value |
API endpoint URL | https://<REPLACE WITH INSTANCE NAME>.hello-charles.com/api/v0/webhooks/incoming/emarsys/custom_external_event |
Authentication Method | Select “JWT authentication” |
JWT Secret | Copy it from the integration configuration of your charles instance (see screenshot on the right). You can find the page on Settings > Integrations > Marketplace . Navigate to Step 5 to copy the webhook secret |
Please configure the Data values as follows:
Event data: If you enable this, charles will receive the data of the event that triggered the webhook. This data can be used for personalizing WhatsApp messages.
Contact data:
external_reference_id
email
phone
For the phone, select the property that you use for storing the mobile phone number on Emarsys. Please note that phone numbers must be in format +{Country Code}… or {Country Code}…, for a German number this would be +4915… or 4911111
ID, Email and Phone are used by charles to identify the end-user who for whom the charles flow needs to be triggered.
Given a webhook is sent for a contact that does not exist yet, then charles will create a new contact based on the phone and/or the email from the webhook and attach the event to it.
Additional Data:
The event name is used for identifying the charles flow to trigger.
The event_name should not contain whitespaces. For example, "abandoned_cart" instead of "abandoned cart"
All other settings are optional.
1b - Add a the charles webhook node to your automation program
Open the program where you would like to use the Webhook node and insert it.
Double-click the Webhook node and select the required charles configuration preset from the dropdown.
If the automation is triggered by an event and the automation program is configured to “Data of the triggering event is being sent”, then the event data will be available in charles flows.
1c - Test the automation program
Change the Status to “in testing”, chose to only send to test contacts, manually
2. Click on “Send test contacts” on the button right and select a test contact with a valid phone number:
After clicking on “Send Test Contact” the spefified flow should be triggered for the ID number of the test contact
Component 2 - Setting up the charles flow
Create a new flow
Select Emarsys trigger
Payload configuration: Based on the properties in the event, create a payload.
Example
{
"birthdate": "",
"discount_code": ""
}
Set up an Emarsys automation program that triggers a charles flow using an ORDER Event
This feature is currently only available for selected customers. Please reach out to your CSM if you want to enable these use cases.
Use cases
Leverage the charles revenue attribution model to get insights about the effectiveness of your campaigns and flows
Segment your contacts within charles based on order data
Send order confirmation messages
Display orders in the conversation view to get context about your contacts
Setup
Set up an Emarsys automation that gets triggered based on Order/Purchase event
In the automation, add a webhook preset node.
Configure the webhook preset node so that
It sends the event data to the charles order webhook