Emarsys (beta)

Emarsys is a comprehensive marketing automation platform that enables personalized customer engagement through email, SMS, and other channels.

The Emarsys integration is still in beta

Connect your Emarsys account to Chatlayer to manage contact data, trigger automated campaigns, and synchronize customer information across your marketing channels.

Setting Up API Credential in Emarsys

You need the Account Owner role inside of emarsys to be able to provision one. You can find it under Management -> Security Settings -> Api Credentials, create one of type WSSE.

Api permissions

Before connecting Emarsys to Chatlayer, you need to ensure your API credentials has the appropriate permissions in Emarsys.

Configure API user permissions in Emarsys (part 1)

Configure API user permissions in Emarsys (part 2)

Make sure your API user has permissions to access contacts, external events, and field information. Refer to the Emarsys API documentation for detailed information on creating API users.

Connecting Emarsys to Chatlayer

Once you have your API credentials (Username(ID) and Secret(Client Secret)) from your Emarsys account, you can connect to Chatlayer.

In an Action block, the Emarsys app will be available from the App options menu.

An App integration section will appear. You'll see any accounts already connected to Chatlayer and a button to connect a new account. If the account you need is already connected, you can select it from the list and skip the connection steps.

Click "Connect new account" and enter your Emarsys API credentials (Username and Secret from the API user you created).

Enter Emarsys Username and Secret

After successful authentication, your Emarsys account will appear in the connected accounts list.

Available Actions

The Emarsys integration provides several actions for managing contacts and triggering events:

Most actions use field IDs. See this reference for built-in fields. You can also use the "List Available Fields" action to view all available fields.

Get Contact Data with Enumeration Values

Retrieves field values for a specified contact and returns human-readable values for choice fields instead of numeric codes.

Get Contact Data with Enumeration Values action

Required fields:

• Key ID: The field ID to use as the contact identifier (e.g., "3" for email)

• Contact ID: The value of the identifier (e.g., the email address)

• Fields: Comma-separated list of field IDs to retrieve (e.g., "1,2,3")

Update Contact Data

Updates data for an existing contact or creates a new contact if they don't exist.

Update Contact Data action

Required fields:

• Key ID: The field ID to use as the contact identifier

• Contact ID: The value of the identifier

• Contact Data Fields: Key-value pairs of field IDs and their new values

Example use case: Update a contact's preferences or subscription status based on bot interactions.

List Available Fields

Retrieves all available contact fields in your Emarsys account. Useful for discovering field IDs when configuring other actions.

List Available Fields action

List Available Choices (Multi)

Returns the available options for multi-choice fields, helping you understand valid values for updates.

List Available Choices for multi-choice fields

List Available Choices (Single)

Returns the available options for single-choice fields.

List Available Choices for single-choice fields

Get Contact Data

Retrieves field values for a specified contact. Use this to pull customer information into your bot flow.

Get Contact Data action

Required fields:

• Key ID: The field ID to use as the contact identifier (e.g., "3" for email)

• Contact ID: The value of the identifier (e.g., the email address)

• Fields: Comma-separated list of field IDs to retrieve (e.g., "1,2,3")

Trigger External Event

Triggers an external event in Emarsys for a specific contact, which can initiate automated campaigns.

Required fields:

• Contact ID: The unique identifier of the contact

• Event ID: The ID of the external event to trigger

Example use case: Trigger a welcome email campaign when a user completes onboarding in your bot.

Developer Notes

Authentication

The Emarsys integration uses WSSE authentication (Web Services Security), which generates a secure token for each API request based on:

• Username and Secret from your API credentials

• A unique nonce (random value)

• Current timestamp

• SHA1 hash for security

This ensures secure communication without exposing your credentials in plain text.

Field IDs

Emarsys uses numeric field IDs rather than field names. Common system fields include:

• 1: First Name

• 2: Last Name

• 3: Email

• 31: Phone

Use the "List Available Fields" action to discover field IDs specific to your account, including custom fields.

Error Handling

API responses include status codes and error messages. Common issues:

• 400: Invalid request format or missing required fields

• 401: Authentication failed - verify your credentials

• 404: Contact or resource not found

• 429: Rate limit exceeded - reduce request frequency