A2P 10DLC Compliance Embeddable Onboarding Guide

With global regulatory requirements frequently changing across jurisdictions, navigating compliance is an expensive, ongoing challenge. Complex requirements lead to customer confusion and registration drop-offs, while maintaining internal compliance tooling consumes significant engineering resources. The Compliance Embeddable helps address these challenges by this by shifting the development and regulatory management burden away from your team, allowing you to scale onboarding effortlessly.

The Compliance Embeddable is a white-label, self-service solution designed to integrate seamlessly into an Independent Software Vendor's (ISV) existing portal or web application. It empowers your end customers to independently manage their registrations and verifications requests while Twilio manages the underlying registration workflow infrastructure".

No Twilio Branding: Twilio manages the UI logic and regulatory question flows behind the scenes, but the entire experience can be fully customized to match your platform's exact design, typography, and color palette. Request Theme: https://forms.gle/tvSuXpvwJE9aPj9B9

Minimize Manual Data Entry: When initializing the Compliance Inquiry, Twillo allows ISV's to pre-fill their customer data for an expedited registration experieince.

The Compliance Embeddable requires two integrations:

1. Server-side integration: Call Twilio's API to initialize a Compliance Inquiry and retrieve a session token and inquiry ID.
2. Client-side integration: Embed the UI in an iframe, and include the session token and inquiry ID as URL parameters.

All calls must be authenticated using Twilio's REST API credentials with Basic Auth, where the account SID is either your primary Twilio Account SID or a subaccount SID. The Account SID given in the credentials is the account that the registration will be associated with after completion of the ComplianceInquiry.

Learn more about the Compliance Embeddable in the Compliance Embeddable FAQ

Before you begin, you must have a Trust Hub Primary Customer Profile for a business whose Business Identity is set to ISV or Reseller. See Create a Trust Hub Primary Customer Profile to learn more.

Only ISV accounts with approved Trust Hub profiles can access the Compliance Embeddable API. Trial accounts are not eligible to use this API.

A2P 10DLC registration is a two-step process that requires both Brand Registration and Campaign Registration. The Compliance Embeddable supports this flow through two separate form submissions:

1. Brand Registration: First, you initialize a brand inquiry to collect business information. This registers the brand with The Campaign Registry (TCR).
2. Campaign Registration: After the brand is approved, you initialize a campaign inquiry to register specific messaging campaigns under that brand.

The Compliance Embeddable supports both steps by separately calling the Initialize Inquiry API in your workflow twice:

• Once to initialize the brand registration inquiry
• A second time to initialize the campaign registration inquiry after the initial brand approval

The Compliance Embeddable's data collection process is secured via server-side authentication and is triggered by a server-side API call. This API call initializes a ComplianceInquiry and returns a token, which you can then pass to your web client to authenticate into a submission flow. The Compliance Embeddable supports both new submissions and resumption of existing inquiries. If a verification is already in progress, approved, or rejected with an error that cannot be resubmitted, the API returns an error response. See the Error responses table for details.

To initialize a ComplianceInquiry for A2P 10DLC Brand registration, make an HTTPS request to the following API:

POST https://trusthub.twilio.com/v1/A2PBrandRegistrations

If you provide data for optional fields, they're pre-filled in any of your users' subsequent forms. The body must use the application/json content type.

To resume a ComplianceInquiry for A2P 10DLC Brand registration, make an HTTPS request to the following API:

POST https://trusthub.twilio.com/v1/A2PBrandRegistrations/{id}/EmbeddedSessions

The value for id is tri1.us1.account.(AccountSID).registration.(BrandBundleSID)

To retrieve a list of all A2P 10DLC registrations, including their Bundle SIDs, make an HTTPS request to the following API:

GET https://messaging.twilio.com/v1/a2p/BrandRegistrations

To learn more about query parameters for filtering results, see the Brand Registration API docs.

To initialize a ComplianceInquiry for A2P 10DLC Campaign registration, make an HTTPS request to the following API:

POST https://trusthub.twilio.com/v1/A2PCampaignRegistrations

If you provide data for optional fields, they're pre-filled in any of your users' subsequent forms.

The body must use the application/json content type.

To resume a ComplianceInquiry for A2P 10DLC Campaign registration, make an HTTPS request to the following API:

POST https://trusthub.twilio.com/v1/A2PCampaignRegistrations/{id}/EmbeddedSessions

Once the campaign is created, its associated Bundle SID will be removed. Going forward, delivery status and errors by using the Messaging Service API.

By default, Twilio sets your Messaging Service to "Defer to sender's webhook," meaning inbound messages to any sender within the Messaging Service's sender pool hit the webhook configured on each sender. The delivery status of your message, including any delivery errors, is sent asynchronously to your status callback URL.

GET https://messaging.twilio.com/v1/Services/{MessagingServiceSid}/Compliance/Usa2p/QE2c6890da8086d771620e9b13fadeba0b

This endpoint returns the following details:

• sid
• campaign_status (for example, IN_PROGRESS, VERIFIED, or FAILED)
• failure_reason (if any)

Track your A2P registration status automatically with Twilio Event Streams. You can now get instant webhook notifications for any changes to your Brands, Campaigns, or 10DLC numbers without having to manually poll APIs or refresh the console. To learn more, see the Event Streams docs.

After initializing a ComplianceInquiry, you may embed the ComplianceInquiry UI in your website using the TwilioComplianceEmbed React client.

Install the package in your React project using your preferred package manager.

NPM:

npm install @twilio/twilio-compliance-embed

Yarn:

yarn add @twilio/twilio-compliance-embed

The ComplianceInquiry UI can be embedded in your site using following code snippet:

1
import * as React from "react";
2
import { TwilioComplianceEmbed } from "@twilio/twilio-compliance-embed";
3

4
const ComplianceInquiry = () => {
5
  return (
6
    <TwilioComplianceEmbed
7
      inquiryId='<your inquiry ID from calling the Initialize ComplianceInquiry API>'
8
      inquirySessionToken='<your inquiry session token from calling the Initialize ComplianceInquiry API>'
9
    />
10
  );
11
};

The ComplianceInquiry UI may take a few seconds to load and render.

We don't yet provide native integrations for frontend frameworks other than React. However, we are releasing a JS SDK soon, so customers using non-React frameworks or older versions of React can also use the Compliance Embeddable.