How can we help?

Send data from Segment to Cordial (actions)

Overview

With our Segment integration, you can send contact data from your Segment account to Cordial, which is seamlessly integrated into the appropriate data collections. From there you can use Cordial's powerful data and messaging tools to build audiences, personalize message content, and trigger messages across multiple channels.

You can also send data from Cordial to Segment.

Certain features in your Cordial account must be preconfigured before the Segment integration can be enabled. Please contact your Client Success Manager for assistance before attempting to enable the integration.

Latest v. legacy version

The latest version of our integration with Segment uses the actions framework. Benefits of using the latest version include:

  • Transparent data mapping: The classic Cordial destination receives data from Segment as is. The Cordial backend then converts those Segment events to Cordial’s format and clients have limited control over this conversion. The Cordial (Actions) destination allows clients to fully define their own mappings of Segment events, making sure they receive data structured specifically for their needs.
  • Only sends data you need: With Cordial (actions) you can define only those destination actions and mappings that make sense for your use cases, while Cordial Classic always sends four predefined API calls: identify, track, group, and page.
  • Sends Engage components to Cordial: With Cordial (Actions) it’s possible to define action mappings that will send audiences and user computed traits defined in the Segment Engage platform to Cordial.

You can find documentation for the legacy (non-actions) version of our Segment integration here.

Enable latest integration version (actions framework)

Enable destination actions

1. Make sure you have your Cordial API Key. To create a new API key, navigate to Account Settings > API Keys.

2. From the Segment web app, click Connections > Catalog.

3. Search for the Cordial (Actions) destination item in the left navigation, and click it.

4. Click Configure Cordial.

5. Select the Source you want to connect to Cordial (Actions).

Destination settings

Setting Description
API key Required. Your Cordial API key.
Endpoint Required. Cordial API endpoint. Leave default, unless you’ve been provided with another one. See more details
User ID attribute key Required. Cordial string unique attribute key to store Segment User ID in (e.g. segment_id). Note: This attribute should be the secondary key. Contact your CSM for assistance.

Available actions

Combine supported Segment triggers with the following Cordial-supported actions:

Mapping limits per destination: individual destination instances support a maximum of 50 mappings.

  • Upsert order
  • Merge contacts
  • Add contact to list
  • Remove contact from list
  • Create contactactivity
  • Remove product from cart
  • Upsert contact
  • Add product to cart

Upsert order

Upserts order to Cordial. Default trigger: event = "Order Completed" or event = "Order Updated" or event = "Order Refunded" or event = "Order Cancelled"

Field Description
Segment User ID Type: HIDDEN

Segment User ID value

Segment Anonymous ID Type: HIDDEN

Segment Anonymous ID value

User Identities Type: OBJECT

An ordered list of contact identifiers in Cordial. Each item in the list represents an identifier. For example, channels.email.address -> userId and/or customerId -> traits.customerId. If a contact is found using the identifiers it is updated, otherwise a new contact is created.

Order ID* Type: STRING

Internal identifier of an order

Order purchase date* Type: DATETIME

Order purchase date

Order status* Type: STRING

Order status (e.g. completed/cancelled/returned)

Order total* Type: NUMBER

Order total amount

Order properties Type: OBJECT

Additional order properties (e.g. affiliation/tax/revenue)

Order items* Type: OBJECT

Order items

Merge contacts

Merge contacts in Cordial. Default trigger: type = "alias"

Field Description
New Segment User ID Type: STRING

New Segment User ID value

New Segment Anonymous ID Type: STRING

New Segment Anonymous ID value

Previous Segment ID* Type: STRING

Previous Segment User or Anonymous ID value

Add contact to list

Add contact to a list. If the list does not exist in Cordial it will be created. Default trigger: type = "group"

Field Description
Segment User ID Type: HIDDEN

Segment User ID value

Segment Anonymous ID Type: HIDDEN

Segment Anonymous ID value

User Identities Type: OBJECT

An ordered list of contact identifiers in Cordial. Each item in the list represents an identifier. For example, channels.email.address -> userId and/or customerId -> traits.customerId. If a contact is found using the identifiers it is updated, otherwise a new contact is created.

Group ID* Type: STRING

Segment group id. Required.

List name Type: STRING

Cordial list name. Optional. If list name is empty, the name of the list will be set to segment_[groupId].

Remove contact from list

Remove contact from Cordial list.

Field Description
Segment User ID Type: HIDDEN

Segment User ID value

Segment Anonymous ID Type: HIDDEN

Segment Anonymous ID value

User Identities Type: OBJECT

An ordered list of contact identifiers in Cordial. Each item in the list represents an identifier. For example, channels.email.address -> userId and/or customerId -> traits.customerId. If a contact is found using the identifiers it is updated, otherwise a new contact is created.

Group ID* Type: STRING

Segment group id. Required.

Create contactactivity

Create a new contact activity. Default trigger is: type = "track" or type = "page"

Field Description
Segment User ID Type: HIDDEN

Segment User ID value

Segment Anonymous ID Type: HIDDEN

Segment Anonymous ID value

User Identities Type: OBJECT

An ordered list of contact identifiers in Cordial. Each item in the list represents an identifier. For example, channels.email.address -> userId and/or customerId -> traits.customerId. If a contact is found using the identifiers it is updated, otherwise a new contact is created.

Event name* Type: STRING

Event name. Required.

Event timestamp Type: DATETIME

Event timestamp. Optional. Date format is ISO 8601 standard. If empty, the request upload time will be used.

Event properties Type: OBJECT

An object of additional event attributes. Optional.

Event context Type: OBJECT

Event context as it appears in Segment. Optional. We use context to capture event metadata like sender ip and device info.

Remove product from cart

Removes product from Cordial contact cart. Default trigger: type = "track" and event = "Product Removed"

Field Description
Segment User ID Type: HIDDEN

Segment User ID value

Segment Anonymous ID Type: HIDDEN

Segment Anonymous ID value

User Identities Type: OBJECT

An ordered list of contact identifiers in Cordial. Each item in the list represents an identifier. For example, channels.email.address -> userId and/or customerId -> traits.customerId. If a contact is found using the identifiers it is updated, otherwise a new contact is created.

Product ID* Type: STRING

Internal identifier of a product

Quantity* Type: INTEGER

Quantity of a product

Upsert contact

Create or update a contact in Cordial. Default trigger: type = "identify"

Field Description
Segment User ID Type: HIDDEN

Segment User ID value

Segment Anonymous ID Type: HIDDEN

Segment Anonymous ID value

User Identities Type: OBJECT

An ordered list of contact identifiers in Cordial. Each item in the list represents an identifier. For example, channels.email.address -> userId and/or customerId -> traits.customerId. If a contact is found using the identifiers it is updated, otherwise a new contact is created.

Contact Attributes Type: OBJECT

Contact attributes to update. Optional. Contact attributes must exist in Cordial prior to updating. Attributes that do not exist in Cordial will be ignored. Complex attribute types to be mapped via dot notation, for example, cordialPerson.first_name -> traits.segmentPerson.firstName, cordialPerson.last_name -> traits.segmentPerson.lastName. Segment trait address can be mapped directly to geo Cordial attribute: geo_cordial_attribute -> traits.address.

Add product to cart

Adds product to cart. Default trigger: type = "track" and event = "Product Added"

Field Description
Segment User ID Type: HIDDEN

Segment User ID value

Segment Anonymous ID Type: HIDDEN

Segment Anonymous ID value

User Identities Type: OBJECT

An ordered list of contact identifiers in Cordial. Each item in the list represents an identifier. For example, channels.email.address -> userId and/or customerId -> traits.customerId. If a contact is found using the identifiers it is updated, otherwise a new contact is created.

Product ID* Type: STRING

Internal identifier of a product

SKU* Type: STRING

SKU of a product

Quantity* Type: INTEGER

Quantity of a product

Category* Type: STRING

Category of a product

Name* Type: STRING

Name of a product

Description Type: STRING

Description of a product

Price Type: NUMBER

Price of a product

URL Type: STRING

URL of a product

Image URL Type: STRING

Image of a product

Properties Type: OBJECT

Properties of a product (e.g brand, color, size)

Migration from the legacy Cordial destination

User identities mappings

Every Cordial destination action needs to be invoked with data identifying a Cordial contact. To identify a contact every destination action has a User Identities field, which maps Segment event fields to Cordial contact identifiers. Each entry in the list represents a contact identifier and how it maps from a Segment event. For example, channels.email.address <- userId or customerId <- traits.customerId. At least one identifier should be valid, otherwise the contact won’t be identified and the request will be ignored.

Typically, the User Identities field maps the Segment events userId field to the Cordial secondary identifier field. For example, if Segment’s userId field is known to be an email, the mapping will be channels.email.address <- userId, meaning the value of userId will be sent as channels.email.address to Cordial.

Update contacts

If you plan to create and update contacts in Cordial, define the upsertContact destination action. In addition to the User Identities field, the action defines the Contact Attributes field. This field defines an exclusive set of attributes that will be updated in a contact. Typically, you map them from Segment traits. For example, customerId <- traits.customerId. For the Cordial Classic destination, these mappings are stored in Cordial’s database. In the Cordial (Actions) destination, they become explicit in the upsertContact destination action mappings.

Send events

To send events, define the createContactactivity destination action. In addition to the User Identities field, additional fields such as Event name, Event timestamp, and Event properties may be defined. Refer to documentation for each field when defining the destination action.

Add and remove users from lists

If you plan to segment users in Cordial, make sure you define the addContactToList and removeContactFromList destination actions. Both actions require the Segment group ID. addContactToList optionally accepts a list name.

Although optional, you should consider the list name as a required option, because it simplifies segmenting contacts in Cordial based on lists. Lists without a name are called following the segment_[groupId] pattern.

Comments

0 comments

Please sign in to leave a comment.