A2P 10DLC - Event Streams Setup

Setting up webhook sinks and event subscriptions via the Event Streams API entails the following steps:

1. Creating a sink resource
2. Note the possible event types you're interested in
3. 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:

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.

The following is a list of all six event types associated with A2P Number Registration, and the corresponding Event Type ID string.

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:

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).

1. From your Twilio Console home, search for Event Streams > Manage in the search bar:

Expand image

2. Clicking on the Manage link will bring up the Manage sinks and subscriptions page. Unless you already have sinks and subscriptions, here you will be invited to create your first sink:

Expand image

3. The blue Create new sink button will take you to the Create new sink page:

Expand image

4. Again, a sink is a destination type for the event messages you'll be subscribing to. In this case you want to configure a Webhook as your sink. Enter a sink description , such as "A2P Registration Event Sink", then select Webhook and press Next step :

Expand image

5. For Destination you will need to indicate the url endpoint that this webhook will call to deliver its event message payload, in this case as a POST . This endpoint will need to be a dedicated page on your own public site, which you have coded to parse and respond to that json payload (example payloads for each event message will be indicated in Part 3 below).
6. Click Finish when you're done. You'll now get a success dialog that invites you to either test this new sink immediately (which will send a generic message payload to your specified endpoint), or move on creating a subscription to listen for specific events:

Expand image

7. Let's click Create subscription , which will bring up the Create a new subscription page. On this page, you will first be asked to select the Sink where these events will be delivered. From the dropdown you will select the sink you just created (in our case "A2P Registration Event Sink." You'll then be asked to name your new subscription; here you'll probably want to stick to a similar naming convention, e.g. "A2P Registration Event Subscription":

Expand image

8. Next you will choose the particular events you'd like to subscribe to. There are a vast number of different events generated by various Twilio products; in this case, under Product groups you will select Messaging , and the first set of Messaging events you will see is an A2P collection of 12 events. The way you indicate that you're selecting a particular event group is to choose a schema for it. In the case of A2P events, for the time being there will only be a single schema, 1, for you to choose in the dropdown; this being the case you will want to select 1 under Apply schema version to all for this event collection:

Expand image

9. Finally, click the blue Create subscription button in the lower right. You're now finished with the Event Streams setup.

Again, IF you are an ISV with secondary customer Brands and Campaigns created or phone number registered immediately within your own top-level account, you would only need to perform this Event Streams setup once; your sink will capture Brand and Campaign registration events subscription for any and all of your clients (you will be able to identify which client a given event message pertains to by way of the Brand or Campaign/Messaging SID indicated in the message payload). If instead you are an ISV whose architecture features a separate subaccount for Brand, Campaign and Number registration for each of your secondary clients, then you will need to do both Event Sink and Subscription setup in each subaccount. Prior to the first step under Part 2 above you would need to switch from your main account to the relevant subaccount, then perform all of the steps indicated in the workflow]

As indicated in Section One above, there are total of 12 events to which you'll be subscribing for A2P Brand, Campaign and Number registration. Below is the JSON payload for each of the 12 events, with explanations of key return parameters where necessary.

This event message indicates that a Brand has been successfully submitted for registration, but it has not yet been verified (for example in the case of a Sole Proprietor Brand, the designated contact has not yet completed the OTP request).

Here accountsid will be either the account or subaccount in which this Brand was registered, and brandsid will be the SID returned when the Brand was created. Type is the full event type ID, in this case com.twilio.messaging compliance.brand-registration.brand-unverified.

Once the customer has responded to the OTP request, the Brand will be fully approved and its status will be changed to Registered, which will issue the next event message.

This event message indicates that the Brand has been successfully registered (and any OTP or other necessary customer action has been completed). Upon receipt of this event message, you should now focus on the status of the associated Campaign.

Again, accountsid will be either the account or subaccount in which this Brand was registered, and brandsid will be the sid returned when the Brand was created. Type is the full event type ID, in this case com.twilio.messaging compliance.brand-registration.brand-registered

This event can be raised either if the initial Brand submission fails (i.e. it fails the Twilio API data check) or if that submission is successful and the Brand undergoes TCR review, but the outcome of that review is a rejection of the Brand.

The type of this event is com.twilio.messaging.compliance.brand-registration.brand-failure

A further parameter brandfailurereason will be added to this payload in a subsequent release, which will give details on the reason for the Brand's failure. In the meantime, upon receipt of this event, you can learn details about the failure reason for this Brand by fetching the BrandRegistration resource.

The type of this event is com.twilio.messaging.compliance.brand-registration.brand-failure

This event message indicates that the Campaign has been successfully submitted, and is currently awaiting approval by TCR. No further action is required of the customer at this time.

Here brandsid and/or campaignsid can be used to identify which customer's campaign this event pertains to. The type of this event is com.twilio.messaging.compliance.campaign-registration.campaign-submitted

This event will be issued after the Campaign has received all required approvals. After this event we will register any and all numbers in the number pool of the Messaging service associated with that Campaign. Once this phone number registration is complete the new Campaign is ready for operation.

Again brandsid and/or campaignsid can be used to identify which customer's campaign this event pertains to. The type of this event is com.twilio.messaging.compliance.campaign-registration.campaign-approved

For the time being, this event message is being raised BOTH in the case where a Campaign has not been successfully submitted (i.e there was some issue on the initial create call to the Twilio API), AND in the case where the Campaign was successfully submitted to TCR, but the vetting process has resulted in the Campaign being rejected.

As before, brandsid and/or campaignsid can be used to identify which customer's campaign this event pertains to.

As with the failed Brand event message, in a future release the payload for this failed Campaign event message will include a campaignfailurereason parameter with details on the reason(s) for the Campaign's failed registration.

In the meantime, the best way to obtain detailed Campaign failure reason information is, again, through an API call, as detailed in Section 3.2 of the Brand and Campaign Troubleshooting document. As that document indicates, this is a fetch call to the us_app_to_person endpoint of the Messaging API, where you will specify the hardcoded compliance type of QE2c6890da8086d771620e9b13fadeba0b and the messaging_service_sid associated with that Campaign. This latter SID will be the messagingservicesid parameter included in the message payload above.

This event message indicates that number deregistration has failed. Below is an example of what the event payload might look like.

• accountsid is the account or subaccount in which this phone number was registered
• campaignsid is the SID from which the number was attempting to be removed
• externalstatus field points to the current registration status for the phone number which in this case is a failure
• failurereason provides the customer more information about this failure. At this point your phone number has failed to be deregistered and cannot be used to send messages, nor can it be used in another messaging service.
• type is the full event type ID, in this case com.twilio.messaging.compliance.number-deregistration.failed .

This event message indicates that the number deregistration process is pending. Below is an example of what the event payload might look like.

• accountsid is the account or subaccount in which this phone number was registered
• campaignsid is the SID from which the number was attempting to be removed
• externalstatus field points to the current registration status for the phone number which in this case is pending. At this point this phone number is in the process of removal from a campaign and cannot be used to send messages, nor can it be used in another messaging service.
• type is the full event type ID, in this case com.twilio.messaging.compliance.number-deregistration.pending .

This event message indicates that the number deregistration process is successful. Below is an example of what the event payload might look like.

• accountsid is the account or subaccount in which this phone number was registered
• note that there is no campaignsid as the number doesn’t currently belong to any campaign
• externalstatus field points to the current registration status for the phone number which in this case is unregistered. At this point your phone number has completed the deregistration process and can no longer be used to send messages. You can now use this number in another messaging service/campaign or re-add it to the same messaging service/campaign.
• type is the full event type ID, in this case com.twilio.messaging.compliance.number-deregistration.successful .

This event message indicates that Number Registration has failed. Below is an example of what the event payload might look like.

• accountsid is the account or subaccount in which this phone number was registered
• campaignsid is the SID to which the number was attempting to be added
• externalstatus field points to the current registration status for the phone number which in this case is a failure
• failurereason provides the customer more information about this failure. At this point your phone number has failed to be registered and cannot be used to send messages.
• type is the full event type ID, in this case com.twilio.messaging.compliance.number-registration.failed .

This event message indicates that the Number Registration process is pending. Below is an example of what the event payload might look like.

• accountsid is the account/subaccount in which this phone number was registered,
• campaignsid is the SID of the Usa2p Resource with which the phone number is associated.
• externalstatus field is the current registration status for the phone number.
• type is the full event type ID, in this case com.twilio.messaging.compliance.number-registration.pending .

In the example below, the externalstatus is pending, which means that the phone number is not fully registered and cannot yet be used to send messages.

This event message indicates that the Number Registration process is successful. Below is an example of what the event payload might look like.

• accountsid is the account or subaccount in which this phone number was registered
• campaignsid is the SID to which the number was added
• Externalstatus field points to the current registration status for the phone number which in this case is registered. At this point your phone number is fully registered and can be used to send messages to your customer.
• type is the full event type ID, in this case com.twilio.messaging.compliance.number-registration.successful .