# Amplitude (Message Metrics)

## How it works[](#how-it-works)

This integration sends your audience engagement data—also available as [reporting webhooks](/integrations/api/webhooks/)—to Amplitude, where you can use it alongside your other user and analytics data to gain insight into your audience’s behaviors.

Because Amplitude generally expects a unique, immutable `user_id` in events, we *only* send events to Amplitude when they represent a person with an `id` or a the event contains a `device_id`. **We do not send events to Amplitude for people who do not have an `id` or aren’t represented by a `device_id`**.

The events we send are both based on things that happen in Customer.io and your customer activity. For example, an `email sent` event indicates that we’ve sent an email to a person, but an `email clicked` event lets you know that your audience clicked a link in your email.

## Enable the Amplitude integration[](#setup-amplitude)

As a part of this process, you’ll need your Amplitude API key.

1.  Go to **Integrations** and select the Amplitude integration card.
    
    [![find and enable the amplitude integration](https://docs.customer.io/images/amplitude-card.png)](#20285861c3e2bfee25681cdbbacd5e13-lightbox)
    
2.  Copy your Amplitude project’s API key into the *API Key* field. You’ll [find your key in Amplitude](https://www.docs.developers.amplitude.com/analytics/find-api-credentials/#) **Settings** > **Projects** > **General**.
    
3.  (Optional) If your account is in Amplitude’s EU data centre, enable the *Use EU Data Residency* setting.
    
4.  Select the events that you want to send to Amplitude. We describe each event on the page. Check out our [reporting documentation](/integrations/api/webhooks/) for more information about the data available to each event.
    
5.  (Optional) Enable *Body Content* to capture the first 1024 characters of messages in *Sent* events. This is an Amplitude limitation. You can still lookup deliveries in Customer.io to see the full contents of sent messages.
    
6.  Click **Save**.
    
    [![select your events and click save](https://docs.customer.io/images/amplitude-setup.png)](#3a39c015a80752edb975b75f9eeac1fd-lightbox)
    

 Amplitude User IDs

Amplitude does not allow a UserID of 0. If you have a profile with an ID of 0, we’ll use the email address instead for only that profile.

## Test your integration[](#test-your-integration)

When you add your API key and set up your integration, you can click **Test Connection** to make sure that your key is valid and connects to the correct project in Amplitude.

The test sends an `email sent` event to Amplitude to ensure that your API key is valid. You can check your Amplitude project for this `email sent` event to make sure that you set up your integration for the Amplitude project you want to send Customer.io data to.

## Payload reference[](#payload-reference)

In this integration, we map our [reporting webhook payloads](/integrations/api/webhooks/) to fit [Amplitude](https://www.docs.developers.amplitude.com/analytics/apis/batch-event-upload-api/#event-properties). Below is a list of fields from our reporting webhooks and how we map them to Amplitude. We’ve also provided examples of both kinds of events.

Amplitude Field

Customer.io Field

Description

`user_id`

`identifiers.id`

`device_id`

`recipients.device_id`

`platform`

`recipients.platform`

As of March 28, 2024, we capitalize/camel-case these items, like `Web`, `Android`, `iOS`.

`event_type`

`object_type` + `metric`

We capitalize/camel-case these items, like `Email Sent`

`insert_id`

`event_id`

Amplitude uses this ID to de-duplicate events

`time`

`timestamp`

The date-time when the event occurred

`groups`

`account_id` and `workspace_id`

While your account and workspace IDs aren’t in our standard reporting webhook payload, we send this to Amplitude to support their [Accounts add-on](https://help.amplitude.com/hc/en-us/articles/5332668738331) add on.

`event_properties`

This covers the remaining fields in the payload, including `identifiers.email`

 Amplitude payload

#### Amplitude payload[](#Amplitude payload)

```json
{
  "$insert_id": "01GJDDNVWD723D5GNSEAQJVSEB",
  "$insert_key": "018a4e4d19084729ad7c4a77667a832afd#905",
  "$row_source": "realtime",
  "$schema": 13,
  "_time": 1669045350000,
  "adid": null,
  "amplitude_attribution_ids": null,
  "amplitude_event_type": null,
  "amplitude_id": 507275024343,
  "app": 419422,
  "city": null,
  "client_event_time": "2022-11-21 15:42:30",
  "client_upload_time": "2022-11-21 15:42:29.394000",
  "country": null,
  "data": {
    "group_first_event": {},
    "group_ids": {
      "257325": [
        10753477083
      ],
      "257326": [
        10871859635
      ]
    }
  },
  "data_type": "event",
  "device_brand": null,
  "device_carrier": null,
  "device_family": null,
  "device_id": "d148bf61-a152-5e08-bcc1-e8be96a9fce4",
  "device_manufacturer": null,
  "device_model": null,
  "device_type": null,
  "display_name": "Sms Sent",
  "dma": null,
  "event_id": 148912891,
  "event_properties": {
    "action_id": 1001266,
    "campaign_id": 1000223,
    "content": "Hey jenny! I got your number!",
    "customer_id": "313803",
    "delivery_id": "dgSiuAMBAMeAFMWAFAGEmtrrwMzFAHs6nMGmSG4=",
    "journey_id": "01GJDDNSY0X731SPYZEBKRNZZ1",
    "recipient": "5558675309"
  },
  "event_time": "2022-11-21 15:42:30",
  "event_type": "Sms Sent",
  "global_user_properties": {},
  "group_properties": {
    "account_id": {
      "1": {}
    },
    "workspace": {
      "56354": {}
    }
  },
  "groups": {
    "account_id": [
      "1"
    ],
    "workspace": [
      "56354"
    ]
  },
  "idfa": null,
  "ip_address": null,
  "is_attribution_event": false,
  "language": null,
  "library": "batch/1.0",
  "location_lat": null,
  "location_lng": null,
  "os": "",
  "os_name": null,
  "os_version": null,
  "partner_id": null,
  "paying": null,
  "plan": {},
  "platform": null,
  "processed_time": "2022-11-21 15:42:42.526145",
  "region": null,
  "sample_rate": null,
  "server_received_time": "2022-11-21 15:42:29.394000",
  "server_upload_time": "2022-11-21 15:42:39.646000",
  "session_id": -1,
  "source_id": null,
  "start_version": null,
  "timeline_hidden": false,
  "user_creation_time": "2022-11-21 15:42:28",
  "user_id": "313803",
  "user_properties": {},
  "uuid": "22ed3a6e-69b3-11ed-898f-d5a02747ae5a",
  "version_name": null
}
```

 Customer.io payload

#### Customer.io payload[](#Customer.io payload)

```json
{
  "event_id": "01GJBCEYDJMH4VCDKXC98JNQ2D",
  "object_type": "sms",
  "timestamp": 166904535,
  "metric": "sent",
  "data": {
    "trigger_id": 1,
    "customer_id": "313803",
    "delivery_id": "dgSiuAMBAMeAFMWAFAGEmtrrwMzFAHs6nMGmSG4=",
    "action_id": 1001266,
    "campaign_id": 1000223,
    "journey_id": "01GJDDNSY0X731SPYZEBKRNZZ1",
    "identifiers": {
      "id": "313803",
      "email": "cool.person@example.com",
      "cio_id": "d9c106000001"
    },
    "content": "Hey jenny! I got your number!",
    "recipient": "+15558675309"
  }
}
```