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:
Setting up webhook sinks and event subscriptions via the Event Streams API entails the following steps:
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 sinks
endpoint 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).
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).
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).
_20[_20 {_20 "data": {_20 "accountsid": "ACXXXXXXXXX",_20 "brandsid": "BNXXXXXXXXX",_20 "brandstatus": "registered",_20 "createddate": 1686837061258,_20 "externalbrandid": "XXXXXXX",_20 "identitystatus": "unverified",_20 "updateddate": 1686837061258_20 },_20 "datacontenttype": "application/ison",_20 "dataschema": "https://events-schemas.dev.twilio.com/A2P.BrandRegisteredUnver\nfied/1",_20 "id": "CE000000000000000000000000000000",_20 "source": "CA000000000000000000000000000000",_20 "specversion": "1.0",_20 "time": "2023-06-15713:51:04.528Z",_20 "type": "com. twilio.messaging compliance.brand-registration.brand-unverified"_20 }_20]
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.
_20[_20 {_20 "data": {_20 "accountsid": "ACXXXXXXXXX",_20 "brandsid": "BNXXXXXXXXX",_20 "brandstatus": "registered",_20 "createddate": 1686837061258,_20 "externalbrandid": "XXXXXXX",_20 "identitystatus": "verified",_20 "updateddate": 1686837061258,_20 },_20 "datacontenttype": "application/ison",_20 "dataschema": "https://events-schemas.dev.twilio.com/A2P.BrandRegisteredUnver\nfied/1",_20 "id": "CE000000000000000000000000000000",_20 "source": "CA000000000000000000000000000000",_20 "specversion": "1.0",_20 "time": "2023-06-15713:51:04.528Z",_20 "type": "com. twilio.messaging compliance.brand-registration.brand-registered"_20 }_20]
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.
_19[_19 {_19 "data": {_19 "accountsid": "ACXXXXXXXXX",_19 "brandsid": "BNXXXXXXXXX",_19 "brandstatus": "registration_failed",_19 "createddate": 1687789009019,_19 "updateddate": 1687789009019_19 },_19 "datacontenttype": "application/json",_19 "dataschema": "https://events-schemas.stage.twilio.com/A2P.BrandRegistrationFailure/1",_19 "id": "CE000000000000000000000000000000",_19 "source": "CA000000000000000000000000000000",_19 "specversion": "1.0",_19 "time": "2023-06-26T14:16:50.481Z",_19 "type": "com.twilio.messaging.compliance.brand-registration.brand-failure"_19 }_19_19]
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.
_22[_22 {_22 "data": {_22 "a2pusecase": "MIXED",_22 "accountsid": "ACXXXXXXXXX",_22 "brandsid": "BNXXXXXXXXX",_22 "campaignregistrationstatus": "pending",_22 "campaignsid": "CMXXXXXXXXX",_22 "createddate": 1687892791272,_22 "messagingservicesid": "MGXXXXXXXXX",_22 "timestamp": 1687892792294,_22 "updateddate": 1687892791272_22 },_22 "datacontenttype": "application/json",_22 "dataschema": "https://events-schemas.stage.twilio.com/A2P.CampaignRegistrationSubmitted/1",_22 "id": "CE000000000000000000000000000000",_22 "source": "CA000000000000000000000000000000",_22 "specversion": "1.0",_22 "time": "2023-06-27T19:06:32.294Z",_22 "type": "com.twilio.messaging.compliance.campaign-registration.campaign-submitted"_22 }_22]
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.
_24[_24 {_24 "data": {_24 "a2pusecase": "MIXED",_24 "accountsid": "ACXXXXXXXXX",_24 "brandsid": "BNXXXXXXXXX",_24 "campaignregistrationstatus": "success",_24 "campaignsid": "CMXXXXXXXXX",_24 "createddate": 1687892791272,_24 "externalcampaignid": "XXXXXXX",_24 "messagingservicesid": "MGXXXXXXXXX",_24 "timestamp": 1687892792294,_24 "updateddate": 1687892791272,_24_24 },_24 "datacontenttype": "application/json",_24 "dataschema": "https://events-schemas.stage.twilio.com/A2P.CampaignRegistrationApproved/1",_24 "id": "CE000000000000000000000000000000",_24 "source": "CA000000000000000000000000000000",_24 "specversion": "1.0",_24 "time": "2023-06-27T19:06:32.294Z",_24 "type": "com.twilio.messaging.compliance.campaign-registration.campaign-approved"_24 }_24]
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.
_22[_22 {_22 "data": {_22 "a2pusecase": "MIXED",_22 "accountsid": "ACXXXXXXXXX",_22 "brandsid": "BNXXXXXXXXX",_22 "campaignregistrationstatus": "failure",_22 "campaignsid": "CMXXXXXXXXX",_22 "createddate": 1687892791272,_22 "messagingservicesid": "MGXXXXXXXXX",_22 "timestamp": 1687892792294,_22 "updateddate": 1687892791272_22 },_22 "datacontenttype": "application/json",_22 "dataschema": "https://events-schemas.stage.twilio.com/A2P.CampaignRegistrationFailure/1",_22 "id": "CE000000000000000000000000000000",_22 "source": "CA000000000000000000000000000000",_22 "specversion": "1.0",_22 "time": "2023-06-27T19:06:32.294Z",_22 "type": "com.twilio.messaging.compliance.campaign-registration.campaign-failure"_22 }_22]
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
.
_22[_22 {_22 "specversion": "1.0",_22 "type": "com.twilio.messaging.compliance.number-deregistration.failed",_22 "source": "CA000000000000000000000000000000",_22 "id": "CE000000000000000000000000000000",_22 "dataschema": "https://events-schemas.twilio.com/A2P.NumberDeregistrationFailed/1",_22 "datacontenttype": "application/json",_22 "time": "2024-03-13T15:51:10.552Z",_22 "data": {_22 "accountsid": "ACXXXXXXXXXXXXXXXXXXXXXXXX",_22 "timestamp": 1710345070552,_22 "id": "fd902aed-ca5a-8e26-85ee-35bdbf3503ea",_22 "campaignsid": "CMXXXXXXXXXXXXXXXX",_22 "externalstatus": "failure",_22 "failureReason": "https://www.twilio.com/docs/api/errors/30126",_22 "phonenumbersid": "PNXXXXXXXXXXXXXXXX",_22 "updateddate": 1710345070476,_22 "phonenumber": "1234567890"_22 }_22 }_22]
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
.
_22_22[_22 {_22 "specversion": "1.0",_22 "type": "com.twilio.messaging.compliance.number-deregistration.pending",_22 "source": "CA000000000000000000000000000000",_22 "id": "CE000000000000000000000000000000",_22 "dataschema": "https://events-schemas.twilio.com/A2P.NumberDeregistrationPending/1",_22 "datacontenttype": "application/json",_22 "time": "2024-03-13T15:51:10.552Z",_22 "data": {_22 "accountsid": "ACXXXXXXXXXXXXXXXXXXXXXXXX",_22 "timestamp": 1710345070552,_22 "id": "fd902aed-ca5a-8e26-85ee-35bdbf3503ea",_22 "campaignsid": "CMXXXXXXXXXXXXXXXX",_22 "externalstatus": "pending_deregistration",_22 "phonenumbersid": "PNXXXXXXXXXXXXXXXX",_22 "updateddate": 1710345070476,_22 "phonenumber": "1234567890"_22 }_22 }_22]
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
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
.
_21_21[_21 {_21 "specversion": "1.0",_21 "type": "com.twilio.messaging.compliance.number-deregistration.successful",_21 "source": "CA000000000000000000000000000000",_21 "id": "CE000000000000000000000000000000",_21 "dataschema": "https://events-schemas.twilio.com/A2P.NumberDeregistrationSuccessful/1",_21 "datacontenttype": "application/json",_21 "time": "2024-03-13T15:51:10.552Z",_21 "data": {_21 "accountsid": "ACXXXXXXXXXXXXXXXXXXXXXXXX",_21 "timestamp": 1710345070552,_21 "id": "fd902aed-ca5a-8e26-85ee-35bdbf3503ea",_21 "externalstatus": "unregistered",_21 "phonenumbersid": "PNXXXXXXXXXXXXXXXX",_21 "updateddate": 1710345070476,_21 "phonenumber": "1234567890"_21 }_21 }_21]
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
.
_22[_22 {_22 "specversion": "1.0",_22 "type": "com.twilio.messaging.compliance.number-registration.failed",_22 "source": "CA000000000000000000000000000000",_22 "id": "CE000000000000000000000000000000",_22 "dataschema": " "dataschema": "https://events-schemas.twilio.com/A2P.NumberRegistrationFailed/1",_22 "datacontenttype": "application/json",_22 "time": "2024-03-13T15:51:10.552Z",_22 "data": {_22 "accountsid": "ACXXXXXXXXXXXXXXXXXXXXXXXX",_22 "timestamp": 1710345070552,_22 "id": "fd902aed-ca5a-8e26-85ee-35bdbf3503ea",_22 "campaignsid": "CMXXXXXXXXXXXXXXXX",_22 "externalstatus": "failure",_22 "failureReason": "https://www.twilio.com/docs/api/errors/30126",_22 "phonenumbersid": "PNXXXXXXXXXXXXXXXX",_22 "updateddate": 1710345070476,_22 "phonenumber": "1234567890"_22 }_22 }_22]
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.
_21[_21 {_21 "specversion": "1.0",_21 "type": "com.twilio.messaging.compliance.number-registration.pending",_21 "source": "CA000000000000000000000000000000",_21 "id": "CE000000000000000000000000000000",_21 "dataschema": "https://events-schemas.twilio.com/A2P.NumberRegistrationPending/1",_21 "datacontenttype": "application/json",_21 "time": "2024-03-13T15:51:10.552Z",_21 "data": {_21 "accountsid": "ACXXXXXXXXXXXXXXXXXXXXXXXX",_21 "timestamp": 1710345070552,_21 "id": "fd902aed-ca5a-8e26-85ee-35bdbf3503ea",_21 "campaignsid": "CMXXXXXXXXXXXXXXXX",_21 "externalstatus": "pending_registration",_21 "phonenumbersid": "PNXXXXXXXXXXXXXXXX",_21 "updateddate": 1710345070476,_21 "phonenumber": "1234567890"_21 }_21 }_21]
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
.
_21[_21 {_21 "specversion": "1.0",_21 "type": "com.twilio.messaging.compliance.number-deregistration.successful",_21 "source": "CA000000000000000000000000000000",_21 "id": "CE000000000000000000000000000000",_21 "dataschema": "https://events-schemas.twilio.com/A2P.NumberDeregistrationSuccessful/1",_21 "datacontenttype": "application/json",_21 "time": "2024-03-13T15:51:10.552Z",_21 "data": {_21 "accountsid": "ACXXXXXXXXXXXXXXXXXXXXXXXX",_21 "timestamp": 1710345070552,_21 "id": "fd902aed-ca5a-8e26-85ee-35bdbf3503ea",_21 "campaignsid": "CMXXXXXXXXXXXXXXXX",_21 "externalstatus": "registered",_21 "phonenumbersid": "PNXXXXXXXXXXXXXXXX",_21 "updateddate": 1710345070476,_21 "phonenumber": "1234567890"_21 }_21 }_21]