A2P 10DLC - Event Streams Setup
Customers who are registering Brands, Campaigns and 10DLC Phone Numbers for A2P Messaging can now set up subscriptions to events which will notify them when a Brand, Campaign or Phone Number's status has changed. This setup and subscription is handled through Twilio's Event Streams product, which allows users to define a sink (in this case a webhook) to which an event notification will be sent for any events to which the user has subscribed - in this case, when a Brand or Campaign has been either successfully submitted or not, and whether successfully-submitted Brands and Campaigns are ultimately approved or rejected, or what a phone number's status is in it's A2P registration or deregistration process. With these event notifications now 'pushed' to customers via the Event Streams framework, it will no longer be necessary to repeatedly query the Brand and Campaign creation APIs, be in limbo about the number's registration status, or continually visit the A2P Console pages, in order to be kept up to date on registration status.
This document will cover the following topics:
- How to set up event sinks and subscriptions via the Event Streams APIs, which will be the most likely path for Independent Software Vendors (SVs) managing the registration of large numbers of secondary brands, either Sole Proprietor or Standard/Low-Volume Standard.
- How to set up event sinks and subscriptions via the Event Streams Console, which will be the likely path for Direct customers who make use of the Event Streams service.
- How to read the json payloads sent in messages for various events, with example payloads for each event.
Setting up webhook sinks and event subscriptions via the Event Streams API entails the following steps:
- Creating a sink resource
- Note the possible event types you're interested in
- Creating a subscription to specific events, for a specified sink
NOTE: If you are an ISV using separate subaccounts for each of your secondary clients, the Event Stream setup (both Sink and Subscription) will need to be done for each subaccount.
A new sink is created via a POST/create call to the sinksendpoint of the Events API.
Sinks are the destinations to which events selected in a subscription will be delivered. Each sink has a sink_type property. At this time, the Sink resource supports three types: AWS Kinesis indicated by the value kinesis, Webhooks (which you will be using) indicated by the value webhook, and Segment indicated by the value segment . Each Sink has a sink_configuration property which expresses its set up. Finally, each sink resource has a friendly-name description parameter.
Again, if you are configuring a secondary customer whose Profile/Brand/Campaign resides in a subaccount, the account_sid and auth_token parameters used in this call (as well as the Subscription creation call in Step 1.3 below) must be those of the subaccount.
Sink_configuration is an object parameter whose elements are different for each sink_type. For the Webhook type, sink_configuration is formatted as follows:
_10"sink_configuration": {_10_10 "destination": "http://example.org/webhook",_10_10 "method": "<POST|GET>",_10_10 "batch_events": <true|false>_10_10}
| Parameter | Description |
|---|---|
destination | The customers' url endpoint i.e http://example.org/webhook |
method | The HTTP method for updating the data on the webhook. The currently available options are GET and POST. |
batch_events | false if you want to receive single events and true if you want events sent in batches. Batched events currently have a 64kB data limit. |
Note finally that the sid return parameter from this call will become the sink_sid parameter used in Step 1.3 below.
You can fetch a list of all subscribable event types from the event_type endpoint of the Events API. You must pass all of these inside the types parameter object when you create your subscription in the next step.
The following is a list of all six event types associated with A2P Brand and Campaign registration, and the corresponding Event Type ID string.
| Event Type | Event type ID |
|---|---|
| Brand Registration Failure | com.twilio.messaging.compliance.brand-registration.brand-failure |
| Brand Registered Unverified | com.twilio.messaging.compliance.brand-registration.brand-unverified |
| Brand Registered | com.twilio.messaging.compliance.brand-registration.brand-registered |
| Campaign Registration Submitted | com.twilio.messaging.compliance.campaign-registration.campaign-submitted |
| Campaign Registration Failed or Rejected | com.twilio.messaging.compliance.campaign-registration.campaign-failure |
| Campaign Registration Approved | com.twilio.messaging.compliance.campaign-registration.campaign-approved |
The following is a list of all six event types associated with A2P Number Registration, and the corresponding Event Type ID string.
| Event Type | Event type ID |
|---|---|
| Number Deregistration Failed | com.twilio.messaging.compliance.number-deregistration.failed |
| Number Deregistration Pending | com.twilio.messaging.compliance.number-deregistration.pending |
| Number Deregistration Successful | com.twilio.messaging.compliance.number-deregistration.successful |
| Number Registration Failed | com.twilio.messaging.compliance.number-registration.failed |
| Number Registration Pending | com.twilio.messaging.compliance.number-registration.pending |
| Number Registration Successful | com.twilio.messaging.compliance.number-registration.successful |
To create a new subscription, use a POST/create call to the subscriptions endpoint of the Events API. This call must associate a specific array of event types with a specific sink to which these event messages will be sent when they are raised.
The subscription create call has the following parameters:
description - a brief human-readable description of the subscription, which should be clearly associated with the sink you're specifying here
sink_sid - the SID of the new sink you created in Step 1.1 above
types - an object containing a delimited list of all the event type IDs for the events you wish to subscribe to, in this case all of the IDs enumerated in 1.2 above. The exact syntax of the types object will vary depending the library you are using; please refer to the code snippet below. In python, for example, the syntax would be:
_10types=[_10{'type': 'com.twilio.messaging.message.delivered'},_10{'type': 'com.twilio.messaging.message.sent', 'schema_version': 2}_10],
In the above example we are subscribing to only two events: messaging.message.delivered and messaging.message.sent, but in your create call you will include all 6 events enumerated in Step 1.2 above. Note that in this example, the second event also specifies a schema_version of 2; if this is not specified, the default schema used will be 1 (currently only schema 1 is available for A2P events, so schema_version need not be specified).
- From your Twilio Console home, search for Event Streams > Manage in the search bar: