---
"@context": https://schema.org
"@type": TechArticle
"@id": https://www.twilio.com/docs/data-destinations/destination/google-analytics-4#article
headline: Google Analytics 4 destination
description: Learn how to send event data to Google Analytics 4 through the Measurement Protocol.
url: https://www.twilio.com/docs/data-destinations/destination/google-analytics-4
inLanguage: en
dateModified: 2026-11-04T17:24:28.000Z
author:
"@type": Organization
name: Twilio Developer Education Team
publisher:
"@type": Organization
name: Twilio
---
# Google Analytics 4 destination
> \[!IMPORTANT]
>
> Data Destinations is currently available as a Private Beta product and the information contained in this document is subject to change. Data Destinations is not a HIPAA Eligible Service or PCI compliant and should not be enabled in workflows that are subject to HIPAA or PCI. To learn more, see [Private beta legal information](/docs/data-destinations#private-beta-legal-information).
[Google Analytics 4](https://analytics.google.com/), the Google analytics platform, lets you send Twilio events to GA4 through the Measurement Protocol for server-side analytics, engagement tracking, and reporting alongside your other app and web data.
### Destination overview
* **Category**: Analytics
* **Release status**: Beta
* **Authentication**: API secret
* **Regional availability**: US1
## Join the Data Destinations private beta
[Sign up](https://airtable.com/appaJfyV6LiIFMxuP/pagIaOAtKsQVxTfdW/form)
Get early access to native destinations for data warehouses, observability tools, and event pipelines.
## Eligible events
**Identifier-restricted eligibility**: Twilio can only send events that contain an end-user identifier (such as a phone number) to GA4, because the GA4 analytics model requires every event to map to a Client ID.
Twilio can currently send the following event types to GA4:
* **Messaging**: [inbound message received](/docs/events/event-types/messaging/inbound-message#received), [message queued](/docs/events/event-types/messaging/outbound-message#queued), [message sent](/docs/events/event-types/messaging/outbound-message#sent), [message delivered](/docs/events/event-types/messaging/outbound-message#delivered), [message failed](/docs/events/event-types/messaging/outbound-message#failed), [message undelivered](/docs/events/event-types/messaging/outbound-message#undelivered), [message read](/docs/events/event-types/messaging/outbound-message#read)
All other event types aren't currently eligible for this destination. See [event types](/docs/events/event-types-overview) for the full list of available event types.
## Get started
### Prerequisites
Before you set up a Google Analytics 4 destination, make sure you have:
* A Google Analytics 4 property and data stream.
* Your GA4 **Measurement ID** (format `G-XXXXXXXXXX`), found in GA4 under **Admin** > **Data Streams** > your stream.
* Your GA4 **API Secret**, found in GA4 under **Admin** > **Data Streams** > your stream > **Measurement Protocol API secrets**.
* A **Hashing Key**: a secret you choose, used to hash identifiers before Twilio sends them to GA4. Twilio recommends using your [Twilio Auth Token](/docs/iam/api/authtoken).
## Create the destination
> \[!NOTE]
>
> See [Set up a destination](/docs/data-destinations/destination-setup) for the full UI and Destinations API setup flow common to every destination type.
### Twilio Console
To create a Google Analytics 4 destination in the Twilio Console:
1. From your Google Analytics account, gather the settings listed in [Destination settings](#destination-settings).
2. In the Twilio Console, go to **Data** > **Data Destinations** > **Destinations** > **Add destination subscription**.
3. Complete the **Add destination subscription** wizard.
### Destinations API
To create a Google Analytics 4 destination through the Destinations API, send a `POST` request to the Destinations endpoint and set `destinationType` to `google-analytics-4`. For authentication and the other request body fields, see [Create a destination](/docs/data-destinations/api-quickstart#create-a-destination).
```text title="Create a destination"
POST "https://destinations.twilio.com/v1/ControlPlane/Destinations"
```
Set the `config` object in the request body as follows:
| Name | Type | Description |
| ------------------------------------------------- | -------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `credentials.credentialType`
(**Required**) | string | Set to `CUSTOM`. |
| `credentials.apiSecret`
(**Required**) | string | Your Measurement Protocol API secret. Find it in Google Analytics under **Admin** > **Data Streams** > **Measurement Protocol API secrets**. |
| `hashSigningKey`
(**Required**) | string | The key Twilio uses to hash personally identifiable information, such as phone numbers, before sending it to Google Analytics 4. Enter your primary Twilio account auth token. |
| `measurementId`
(**Required**) | string | The measurement ID of your data stream, in the format `G-XXXXXXXXXX`. |
| `region` | enum`` | The Google Analytics 4 API region. The default is `GLOBAL`. Valid values: `GLOBAL`, `EU`. |
The following example shows a request body. Replace the uppercase placeholder values with your own.
```json title="Example request body"
{
"destinationType": "google-analytics-4",
"name": "My Google Analytics 4 destination",
"config": {
"credentials": {
"credentialType": "CUSTOM",
"apiSecret": "API_SECRET"
},
"hashSigningKey": "HASH_SIGNING_KEY",
"measurementId": "MEASUREMENT_ID"
}
}
```
## Destination settings
Use `google-analytics-4` as the `destinationType`.
| Field | Description | Required | Default or choices |
| -------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------- | ------------------------ |
| API Secret | Measurement Protocol API secret, found in GA4 under Admin > Data Streams > Measurement Protocol API secrets. Sensitive: entered once and stored encrypted. | Yes | None |
| Measurement ID | Data Stream Measurement ID (format `G-XXXXXXXXXX`), found in GA4 under Admin > Data Streams. | Yes | None |
| Hashing Key | Secret key used to hash identifiers (such as phone numbers) before they're sent to GA4. Twilio recommends using your Twilio Auth Token. Sensitive: stored encrypted. | Yes | None |
| Region | API region for data collection. Use `EU` if your GA4 property requires GDPR data residency. | No | `GLOBAL` (default), `EU` |
Twilio authenticates to Google Analytics 4 by using your **API Secret** and **Measurement ID**, which Twilio sends as query parameters on every event delivered to GA4. Google recommends rotating your API Secret periodically because it has no expiration.
Before sending an identifier to GA4, Twilio hashes it by using your **Hashing Key** as the signing secret. If you leave the Hashing Key unset, event delivery fails because Twilio won't send an identifier to GA4 unhashed.
## Default mappings
| Field | GA4 field |
| ----------------------------------------------- | ------------------ |
| Event type | Event name |
| Event time | Timestamp |
| End-user identifier (for example, phone number) | Client ID (hashed) |
| A curated set of event-specific fields | Event parameters |
Twilio hashes the end-user identifier with your **Hashing Key** before sending it to GA4 as the Client ID, so GA4 never receives the identifier in plaintext.
Event parameters aren't a dump of the full event payload. Each eligible event type maps to its own hand-picked set of fields (for example, `messageSid`, `errorCode`, and `body` for a message-status event). Twilio chooses these fields to fit GA4 parameter limits and leaves out fields it doesn't map.
GA4 caps event names and parameter keys at 40 characters. Twilio
truncates a longer event type or key to fit. GA4 caps parameter string
values separately, at 100 characters. Twilio truncates values over that
limit rather than dropping them.
## Verification and troubleshooting
When you save a Google Analytics 4 destination, Twilio sends a test event to the real GA4 Measurement Protocol endpoint to confirm it's reachable. GA4 always returns a success response for a reachable endpoint, even if your API Secret is invalid. A successful save confirms that Twilio can reach GA4, but not that your credentials are correct. After setup, check the GA4 Realtime report to confirm events arrive.
Twilio doesn't currently offer a way to manually trigger a test event for this destination, from either the Console or the CLI. To confirm delivery works, wait for a real event of a subscribed type to occur.
### Common errors
| Cause | What you'll see | Fix |
| --------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------ |
| Unreachable endpoint or network timeout | Validation fails to reach Google Analytics 4 | Retry, and check that your network or firewall allows outbound HTTPS to `google-analytics.com` |
| Invalid or incorrect Measurement ID | No events appear in GA4 despite a successful save | Re-check the Measurement ID in GA4 under **Admin** > **Data Streams** and update the destination |
| Invalid or revoked API Secret | No events appear in GA4 despite a successful save (GA4 does not report auth failures) | Re-create the API Secret in GA4 and update the destination |
| Wrong Region selected | Events don't appear if your property requires EU data residency | Confirm your property's region requirement in GA4 and update `region` |
| Hashing Key is empty | Destination saves successfully, but every delivery fails (Twilio won't hash identifiers with no key); errors reported in the [Debugger](/docs/usage/troubleshooting/debugging-your-application) | Set a Hashing Key on the destination (Twilio recommends your Twilio Auth Token) |
If Twilio can't deliver events to your destination, Twilio sends an error notification to the [Debugger](/docs/usage/troubleshooting/debugging-your-application) (available in US1 region only). If Twilio continues to encounter delivery errors, Twilio notifies you every 20 minutes after the initial error.
## Additional resources
* [Destinations overview](/docs/data-destinations/destinations-overview)
* [Set up a destination](/docs/data-destinations/destination-setup)
* [Event types reference](/docs/events/event-types-overview)