# Engage Cloud Mode Integration

RudderStack lets you send your event data to Engage via [cloud mode]({{< ref "destinations/rudderstack-connection-modes.md#cloud-mode" >}}).

Find the open source transformer code for this destination in the [GitHub repository](https://github.com/rudderlabs/rudder-transformer/tree/main/src/v0/destinations/).

## Identify

You can use the [`identify`]({{< ref "event-spec/standard-events/identify.md" >}}) call to create or update a user in Engage. To update a user's email, you need to provide the [Engage Private Key]({{< ref "destinations/streaming-destinations/engage/setting-up-engage.md#connection-settings" >}}) in the dashboard settings.

RudderStack uses the [Create or update a User](https://docs.engage.so/en-us/a/62bbdd015bfea4dca4834042-users) API to add a new user to your Engage account.

The following table lists the RudderStack attributes and their mappings with the Engage properties:

| RudderStack property   | Engage property  | Data type |
| :-------------| :-----------------| :------|
|  `externalId.engageId`, `userId`, `traits.userid`, `traits.id`, `context.traits.userId`, `context.traits.id` <br /> <span style="color: #4D4DFF;font-size:12px;">Required</span> | `uid`     |     Alphanumeric |
| `traits.firstName`, `traits.firstname`, `traits.first_name`, `context.traits.firstName`, `context.traits.firstname`, `context.traits.first_name`  | `first_name`     |     String |
| `traits.lastName`, `traits.lastname`, `traits.last_name`, `context.traits.lastName`, `context.traits.lastname`, `context.traits.last_name`  | `last_name`     |     String |
| `traits.email`, `context.traits.email`, `properties.email`  | `email`     |     String |
| `traits.phone`, `context.traits.phone`, `properties.phone` | `number`     |     Number *(In `^[0-9]{7,15}$` format)* |
| Other user traits  | `meta` | String/Integer/Boolean |
| `timestamp`, `originalTimestamp`  | `createdAt` | Timestamp *(ISO 8601 format)* |
| `externalId.engageListId`, `config.listIds`  | `lists` | Array of List ID |

{{< info >}}
RudderStack uses `externalId.engageListId` or `config.listIds` as a fallback value in case `userId`, `externalId.engageId`, `traits.userId`, `traits.id`, or `context.traits.id` is absent in the event.
{{< /info >}}

### Deleting a user

You can delete a user in Engage using the [Suppression with Delete regulation]({{< ref "api/user-suppression-api/_index.md#adding-a-suppression-with-delete-regulation" >}}) of the RudderStack [User Suppression API]({{< ref "api/user-suppression-api/_index.md" >}}).

{{< info >}}
To delete a user in Engage, you need to specify the [Engage Private Key]({{< ref "destinations/streaming-destinations/engage/setting-up-engage.md#connection-settings" >}}) in the dashboard settings.
{{< /info >}}

A sample regulation request body for deleting a user in Engage is shown below:

```json
{
  "regulationType": "suppress_with_delete",
  "destinationIds": [
    "2FIKkByqn37FhzczP23eZmURciA"
  ],
  "users": [{
    "userId": "1hKOmRA4GRlm",
    "phone": "+1-202-555-0146",
    "email": "alex@example.com"
  }]
}
```

RudderStack deletes the user account in Engage using the [Delete User API](https://docs.engage.so/en-us/a/62bbdd015bfea4dca4834042-users#delete-customer-or-account).

## Track

The [`track`]({{< ref "event-spec/standard-events/track.md" >}}) call lets you capture user events along with the associated properties and send them to Engage.

RudderStack uses the [Add User events API](https://docs.engage.so/en-us/a/62bbdd015bfea4dca4834042-users#track-user-event) to send the user events to Engage.

A sample `track` call is shown below:

```javascript
rudderanalytics.track(
  "Order Completed", {
    revenue: 30,
    currency: "USD",
    userId: "1hKOmRA4el9Z" 
  })
```

The following table lists the RudderStack attributes and their mappings with the Engage properties:

| RudderStack property   | Engage property  | Data type |
| :-------------| :-----------------| :------|
| `externalId.engageId`, `userId`, `traits.userid`, `traits.id`, `context.traits.userId`, `context.traits.id` <br /> <span style="color: #4D4DFF;font-size:12px;">Required</span> | `uid`     |     Alphanumeric |
| `event` <br /> <span style="color: #4D4DFF;font-size:12px;">Required</span> | `event` | String |
| `originalTimestamp`  | `timestamp` | Timestamp *(ISO 8601 format)* |
| `properties`  | `properties` | Object |

{{< warning >}}
The event name must be less than 32 characters. Otherwise, Engage will reject the event.
{{< /warning >}}

## Page

The [`page`]({{< ref "event-spec/standard-events/page.md" >}}) call lets you record your website's page views with any additional relevant information about the viewed page.

RudderStack sends the page-related information to Engage using their [Add User events API](https://docs.engage.so/en-us/a/62bbdd015bfea4dca4834042-users#track-user-event).

The following table lists the RudderStack event properties and their mappings with the Engage properties:

| RudderStack property   | Engage property  | Data type |
| :-------------| :-----------------| :------|
| `externalId.engageId`, `userId`, `traits.userid`, `traits.id`, `context.traits.userId`, `context.traits.id` <br /> <span style="color: #4D4DFF;font-size:12px;">Required</span> | `uid`     |     Alphanumeric |
| `Visited {Category} {Name} Page` <br /> <span style="color: #4D4DFF;font-size:12px;">Required</span> | `event` | String | 
| `originalTimestamp`  | `timestamp` | Timestamp *(ISO 8601 format)* |
| `properties` | `properties` | Object |

{{< warning >}}
The event name must be less than 32 characters. Otherwise, Engage will reject the event.
{{< /warning >}}

## Group

You can use the [`group`]({{< ref "event-spec/standard-events/group.md" >}}) call to link an identified user to a specific Engage list.

RudderStack subscribes the user to the Engage list using their [Subscribe to a List API](https://docs.engage.so/en-us/a/62bbdd2e5bfea4dca4834045-lists#subscribe-user-to-a-list).

A sample `group` call is shown below:

```javascript
rudderanalytics.group("group01", {
"userId": "1",
"name": "Capsule Corp.",
"subscriber_status": "false",
"operation": "add"
});
```

You can pass the following parameters in the `group` event along with the `userId` (if known):

| RudderStack property   | Engage property  | Data type |
| :-------------| :-----------------| :------|
| `groupId` <br /> <span style="color: #4D4DFF;font-size:12px;">Required</span> | `id` | String |
| `externalId.engageId`, `userId`  | `uid`     |     Alphanumeric |
| `subscriber_status`  <br /> *(Default: `true`)* | `subscribed` | Boolean |
| `traits.operation` <br /> *(Acceptable values: `add`/`remove`)* | - | String | 

The following table lists the additional property mappings with the Engage properties:

| RudderStack property   | Engage property  | Data type |
| :-------------| :-----------------| :------|
| `traits.email`, `context.traits.email`, `properties.email`, `context.externalId.0.id` <br /> <span style="color: #4D4DFF;font-size:12px;">Required, if `phone` is not present</span>  | `email`     |     String |
| `traits.phone`, `context.traits.phone`, `properties.phone` <br /> <span style="color: #4D4DFF;font-size:12px;">Required, if `email` is not present</span> | `number`     |     Number *(In `^[0-9]{7,15}$` format)* |
| `traits.firstName`, `traits.firstname`, `traits.first_name`, `context.traits.firstName`, `context.traits.firstname`, `context.traits.first_name`  | `first_name`     |     String |
| `traits.lastName`, `traits.lastname`, `traits.last_name`, `context.traits.lastName`, `context.traits.lastname`, `context.traits.last_name`  | `last_name`     |     String |
| Other user traits   | `meta` | String / Integer / Boolean |
| `timestamp`, `originalTimestamp` | `createdAt` | Timestamp *(ISO 8601 format)* |

When sending `group` events to Engage, it is important to note the following:

- To remove a user from a group (`"operation": "remove"`), you need to provide the `userId` or  `externalId` in the event. 
- If the user's ID is not known, then either `email` or `phone` is required for looking up the user in Engage.
- If a user is found with an associated `email` or `phone` (in that priority), then Engage links the user to the provided Engage List ID. Otherwise, it creates a new user with the provided details and then links them to the List ID.