Event Streams Setup and Notifications for A2P Brands and Campaigns

Customers who are registering Brands and Campaigns for A2P Messaging can now set up subscriptions to events which will notify them when a Brand or Campaign’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. 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, 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.

Set up Event Streams via the Event Streams API

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.

1 Create a new sink resource

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:

"sink_configuration": { 

    "destination": "http://example.org/webhook",

    "method": "<POST|GET>",

    "batch_events": <true|false>

}

Note finally that the sid return parameter from this call will become the sink_sid parameter used in Step 1.3 below.

2 Event types and type IDs

You can fetch a list of all subscribable event types from the event_type endpoint of the Events API. The following is a list of all six event types associated with A2P Brand and Campaign registration, and the corresponding Event Type ID string. You must pass all of these inside the types parameter object when you create your subscription in the next step.

3 Create a subscription to specific events, for a specific sink

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:

types=[
{'type': 'com.twilio.messaging.message.delivered'}, 
{'type': 'com.twilio.messaging.message.sent', 'schema_version': 2}
],

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

Set up Webhooks and subscribe to A2P Registration Events via the Event Streams Console

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

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:

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

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:

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:

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”:

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 see will see an A2P collection of 6 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:

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 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 and Campaign 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]

Read the Payloads for each event message

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

1 Brand Registered Unverified

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

[
  {
    "data": {
      "accountsid": "ACXXXXXXXXX",
      "brandsid": "BNXXXXXXXXX",
      "brandstatus": "registered",
      "createddate": 1686837061258,
      "externalbrandid": "XXXXXXX",
      "identitystatus": "unverified",
      "updateddate": 1686837061258
    },
    "datacontenttype": "application/ison",
    "dataschema": "https://events-schemas.dev.twilio.com/A2P.BrandRegisteredUnver\nfied/1",
    "id": "CE000000000000000000000000000000",
    "source": "CA000000000000000000000000000000",
    "specversion": "1.0",
    "time": "2023-06-15713:51:04.528Z",
    "type": "com. twilio.messaging compliance.brand-registration.brand-unverified"
  }
]

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.

2 Brand Registered

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.

[
  {
    "data": {
      "accountsid": "ACXXXXXXXXX",
      "brandsid": "BNXXXXXXXXX",
      "brandstatus": "registered",
      "createddate": 1686837061258,
      "externalbrandid": "XXXXXXX",
      "identitystatus": "verified",
      "updateddate": 1686837061258,
    },
    "datacontenttype": "application/ison",
    "dataschema": "https://events-schemas.dev.twilio.com/A2P.BrandRegisteredUnver\nfied/1",
    "id": "CE000000000000000000000000000000",
    "source": "CA000000000000000000000000000000",
    "specversion": "1.0",
    "time": "2023-06-15713:51:04.528Z",
    "type": "com. twilio.messaging compliance.brand-registration.brand-registered"
  }
]

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

3 Brand Registration Failure

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.

[
 {
        "data": {
            "accountsid": "ACXXXXXXXXX",
            "brandsid": "BNXXXXXXXXX",
            "brandstatus": "registration_failed",
            "createddate": 1687789009019,
            "updateddate": 1687789009019
        },
        "datacontenttype": "application/json",
        "dataschema": "https://events-schemas.stage.twilio.com/A2P.BrandRegistrationFailure/1",
        "id": "CE000000000000000000000000000000",
        "source": "CA000000000000000000000000000000",
        "specversion": "1.0",
        "time": "2023-06-26T14:16:50.481Z",
        "type": "com.twilio.messaging.compliance.brand-registration.brand-failure"
    }

]

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 making a fetch call to the brand_registrations endpoint of the Messaging API, as detailed in Section 3.0.1 of this document. The brand_registration_sid used in that call will be the brandsid returned in the payload above. Details on understanding the failure_reason (or reasons) returned in that call can be found in the document referenced.

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

4 Campaign Registration Submitted

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.

[
     {
        "data": {
            "a2pusecase": "MIXED",
            "accountsid": "ACXXXXXXXXX",
            "brandsid": "BNXXXXXXXXX",
            "campaignregistrationstatus": "pending",
            "campaignsid": "CMXXXXXXXXX",
            "createddate": 1687892791272,
            "messagingservicesid": "MGXXXXXXXXX",
            "timestamp": 1687892792294,
            "updateddate": 1687892791272
        },
        "datacontenttype": "application/json",
        "dataschema": "https://events-schemas.stage.twilio.com/A2P.CampaignRegistrationSubmitted/1",
        "id": "CE000000000000000000000000000000",
        "source": "CA000000000000000000000000000000",
        "specversion": "1.0",
        "time": "2023-06-27T19:06:32.294Z",
        "type": "com.twilio.messaging.compliance.campaign-registration.campaign-submitted"
    }
]

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

5 Campaign Registration Approved

After the Campaign has been approved by TCR, 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, this event will be issued, indicating that the new Campaign is ready for operation.

[
     {
        "data": {
            "a2pusecase": "MIXED",
            "accountsid": "ACXXXXXXXXX",
            "brandsid": "BNXXXXXXXXX",
            "campaignregistrationstatus": "success",
            "campaignsid": "CMXXXXXXXXX",
            "createddate": 1687892791272,
            "externalcampaignid": "XXXXXXX",
            "messagingservicesid": "MGXXXXXXXXX",
            "timestamp": 1687892792294,
            "updateddate": 1687892791272,

        },
        "datacontenttype": "application/json",
        "dataschema": "https://events-schemas.stage.twilio.com/A2P.CampaignRegistrationApproved/1",
        "id": "CE000000000000000000000000000000",
        "source": "CA000000000000000000000000000000",
        "specversion": "1.0",
        "time": "2023-06-27T19:06:32.294Z",
        "type": "com.twilio.messaging.compliance.campaign-registration.campaign-approved"
    }
]

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

6 Campaign Registration Failure

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.

[
     {
        "data": {
            "a2pusecase": "MIXED",
            "accountsid": "ACXXXXXXXXX",
            "brandsid": "BNXXXXXXXXX",
             "campaignregistrationstatus": "failure",
            "campaignsid": "CMXXXXXXXXX",
            "createddate": 1687892791272,
            "messagingservicesid": "MGXXXXXXXXX",
            "timestamp": 1687892792294,
            "updateddate": 1687892791272
        },
        "datacontenttype": "application/json",
        "dataschema": "https://events-schemas.stage.twilio.com/A2P.CampaignRegistrationFailure/1",
        "id": "CE000000000000000000000000000000",
        "source": "CA000000000000000000000000000000",
        "specversion": "1.0",
        "time": "2023-06-27T19:06:32.294Z",
        "type": "com.twilio.messaging.compliance.campaign-registration.campaign-failure"
    }
]

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.