Google Analytics 4 destination
Beta
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.
Google Analytics 4, 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.
- Category: Analytics
- Release status: Beta
- Authentication: API secret
- Regional availability: US1
Get early access to native destinations for data warehouses, observability tools, and event pipelines.
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, message queued, message sent, message delivered, message failed, message undelivered, message read
All other event types aren't currently eligible for this destination. See event types for the full list of available event types.
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.
Info
See Set up a destination for the full UI and Destinations API setup flow common to every destination type.
To create a Google Analytics 4 destination in the Twilio Console:
- From your Google Analytics account, gather the settings listed in Destination settings.
- In the Twilio Console, go to Data > Data Destinations > Destinations > Add destination subscription.
- Complete the Add destination subscription wizard.
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.
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<string> | 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.
1{2"destinationType": "google-analytics-4",3"name": "My Google Analytics 4 destination",4"config": {5"credentials": {6"credentialType": "CUSTOM",7"apiSecret": "API_SECRET"8},9"hashSigningKey": "HASH_SIGNING_KEY",10"measurementId": "MEASUREMENT_ID"11}12}
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.
| 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.
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.
| 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 | 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 (available in US1 region only). If Twilio continues to encounter delivery errors, Twilio notifies you every 20 minutes after the initial error.