Toll-Free Verification Compliance Embeddable Onboarding Guide
Info
The Compliance Embeddable is a white-label embed offering designed to seamlessly integrate into an Independent Software Vendor's (ISV) existing portal or web application. The user interface is tailored specifically for the ISV tenant use case with a form containing all the necessary questions required by a verification or registration, allowing ISVs' end customers to submit their compliance information via self-service. Twilio manages the questions that are asked in the UI, but there is no Twilio branding on the Compliance Embeddable. The UI can be customized by the Twilio team to align with your design standards, including color palette and typeface.
After reading this document, you will be able to integrate the Compliance Embeddable into your web application to allow self-service Toll-Free Verification for your end customers.
The Compliance Embeddable requires two integrations:
- Server-side integration to invoke the Twilio Initialize ComplianceInquiry APIs to initialize the ComplianceInquiry and get back a session token and inquiry ID.
- Client-side integration to embed the ComplianceInquiry UI in your existing web application using an iframe, utilizing the returned session token and inquiry ID.
This onboarding guide provides a step-by-step walkthrough on how to integrate the Compliance Embeddable into an ISV's web application, allowing self-service Toll-Free Verification for your end customers.
If you have questions about this product, check out the Compliance Embeddable FAQ or contact us at via the Twilio Help Center.
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.
To initialize a ComplianceInquiry for a Toll-Free Verification, make an HTTPS request to the following API:
POST https://trusthub.twilio.com/v1/ComplianceInquiries/Tollfree/Initialize
This call must be authenticated using Twilio's REST API credentials where the account SID is either your primary Twilio Account SID or a subaccount SID. All of the parameters except for TollfreePhoneNumber and NotificationEmail are optional. If this data is provided, it will automatically appear pre-filled in the subsequent forms in the user's UI.
Info
The Account SID given in the credentials is the Account that the Toll-Free Verification will be associated with after completion of the ComplianceInquiry.
The body of the request will require the following x-www-form-urlencoded parameters:
| Parameter | Field Type | Description |
|---|---|---|
| TollfreePhoneNumber [required] | String | The Toll-Free number, in E.164 format, for which the verification request needs to be submitted. |
| NotificationEmail [required] | String | The email ID to which all notifications for the status of Toll-Free Verification will be sent. |
| ThemeSetId [optional] | String | Theme ID for the UI. Relevant for customers who've requested customized font/color. To request a customized Theme, please follow the instructions in our FAQ. |
| BusinessName [optional] | String | The name of the business or organization using the Toll-Free phone number. |
| BusinessStreetAddress [optional] | String | The address of the business or organization using the Toll-Free phone number. |
| BusinessStreetAddress2 [optional] | String | The second row of the street address of the business or organization using the Toll-Free phone number. |
| BusinessCity [optional] | String | The city of the business or organization using the Toll-Free phone number. |
| BusinessStateProvinceRegion [optional] | String | The state/province or region of the business or organization using the Toll-Free phone number. |
| BusinessPostalCode [optional] | String | The postal code of the business or organization using the Toll-Free phone number. |
| BusinessCountry [optional] | String | The ISO country code of the business or organization using the Toll-Free phone number. |
| BusinessWebsite [optional] | String | The website of the business or organization using the Toll-Free phone number. |
| BusinessContactFirstName [optional] | String | The first name of the contact for the business or organization using the Toll-Free phone number. |
| BusinessContactLastName [optional] | String | The last name of the contact for the business or organization using the Toll-Free phone number. |
| BusinessContactEmail [optional] | String | The email address of the contact for the business or organization using the Toll-Free phone number. |
| BusinessContactPhone [optional] | String | The phone number of the contact for the business or organization using the Toll-Free phone number. |
| UseCaseCategories [optional] | Array (String) | Choose the use case that you believe best fits your customer's traffic pattern. This should be the use case that best fits the types of messages being sent by this Toll-Free phone number. |
| UseCaseSummary [optional] | String | The explanation on how messaging is used by the business or organization. |
| ProductionMessageSample [optional] | String | An example of the message content, e.g., "This is Chris, I'm here with your order. Reply STOP to opt out." |
| OptInImageUrls [optional] | Array (String) | Link to an image or document that shows the opt-in workflow where your users sign up for your SMS campaign. Multiple URLs are allowed. Any URL submitted must be reachable, resolvable, and accessible to the public. |
| OptInType [optional] | String | Describes how a user opts in to text messages. |
| MessageVolume [optional] | String | The monthly volume estimation of messages from the Toll-Free number. |
| AdditionalInformation [optional] | String | Additional info to help with the verification. |
| SkipMessagingUseCase [optional] | Boolean | Please send this as true if you wish to skip the messaging use case screen in the UI, which asks the user to provide "UseCaseCategories", "UseCaseSummary", "ProductionMessageSample", "OptInImageUrls", "OptInType", "MessageVolume". Please note, requests to hide will only be honored if "UseCaseCategories", "UseCaseSummary", "ProductionMessageSample", "OptInImageUrls", "OptInType", and "MessageVolume" are pre-populated. |
Note: Data validations will be performed on these fields. Please refer to our Toll-Free Verification Guide for detailed validation rules. Additionally, you may sign up for status change notifications for Toll-Free Verification via Twilio Event Streams.
1// Download the helper library from https://www.twilio.com/docs/node/install2const twilio = require("twilio"); // Or, for ESM: import twilio from "twilio";34// Find your Account SID and Auth Token at twilio.com/console5// and set the environment variables. See http://twil.io/secure6const accountSid = process.env.TWILIO_ACCOUNT_SID;7const authToken = process.env.TWILIO_AUTH_TOKEN;8const client = twilio(accountSid, authToken);910async function createComplianceTollfreeInquiry() {11const complianceTollfreeInquiry =12await client.trusthub.v1.complianceTollfreeInquiries.create({13notificationEmail: "dean@twilio.com",14tollfreePhoneNumber: "+800445566",15});1617console.log(complianceTollfreeInquiry.inquiryId);18}1920createComplianceTollfreeInquiry();
Output
1{2"inquiry_id": "inq_aaaaaaaaaaaaaaaaaaaaaaaa",3"inquiry_session_token": "new.session.token",4"registration_id": "tri1.us1.trusthub.ACaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa.tollfree.PNaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",5"url": "https://trusthub.twilio.com/v1/ComplianceInquiries/Tollfree/Initialize"6}
A successful request will return a JSON response body with the following attributes:
| Name | Description |
|---|---|
| registration_id | A reference for your Toll-free verification resource in Twilio. |
| inquiry_id | A reference for your Toll-free verification Inquiry in Twilio. This value will be used to initialize the client component. |
| inquiry_session_token | An ephemeral session token for your Compliance Inquiry in Twilio. This value will be used to initialize the client component. Expires in 1440 minutes from creation. |
API Error Responses and their meaning
| Error | Error Code | Error Message |
|---|---|---|
| PN not provided | 400 | Phone number is required. |
| Notification email not provided | 400 | Notification email is required. |
| PN entered doesn't belong to the ISV account | 400 | Phone number doesn't belong to this ISV account. |
| PN entered is not a Toll-free number | 400 | Phone number is not a Toll-free number. |
| Verification is not eligible for re-submission i.e. is already in progress or rejected with a non-resubmittable error. | 400 | Verification for Number is not eligible for re-submission. |
| Account is a trial account | 400 | Trial account: AccountSid cannot be used for this operation |
| PN status is not "in-use" | 400 | Phone number is not valid. |
| This is a generic error. A common reason for this error is when you've reached the session limit. Please note that for a single inquiry_id, there's a limit that you can generate max 50 inquiry_session_tokens. | 500 | Internal Server Error |
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 into your site with the following code snippet:
1import * as React from "react";2import { TwilioComplianceEmbed } from "@twilio/twilio-compliance-embed";34const ComplianceInquiry = () => {5return (6<TwilioComplianceEmbed7inquiryId='<your inquiry id from calling the Initialize ComplianceInquiry API>'8inquirySessionToken='<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.
| Name | Type | Description |
|---|---|---|
| inquiryId | (Required) String | A valid inquiryId returned by calling the Initialize ComplianceInquiry API |
| inquirySessionToken | (Required) String | A valid inquirySessionToken returned by calling the Initialize ComplianceInquiry API |
| onInquirySubmitted | () => void | An event handler that fires when the user has completed the ComplianceInquiry process. This event is fired when the user lands on the last screen |
| onComplete | () => void | An event handler that fires when the user has completed the ComplianceInquiry process. This event is fired when the user clicks the **Done** or **Exit** button on the last page. Please note that this event is not guaranteed to be fired as the user could choose not to click the button on the last page. If you wish to track when a user has finished the flow and submitted the bundle, please use onInquirySubmitted instead. |
| onCancel | () => void | An event handler that fires when the user has canceled the ComplianceInquiry process |
| onError | () => void | An event handler that fires when an unexpected error occurs during the ComplianceInquiry process |
| onReady | () => void | An event handler that fires when the ComplianceInquiry UI has finished loading |
| widgetPadding | { top?: number; bottom?: number; left?: number; right?: number; } | Allows customizing the internal padding inside the iframe. If this is not passed it will use the default values {top: 74, left: 24, right: 24, bottom: 24} Value should be an object with shape {top?: number; bottom?: number; left?: number; right?: number;} |
1import * as React from "react";2import { Spinner } from "@twilio-paste/core/spinner";3import { TwilioComplianceEmbed } from "@twilio/twilio-compliance-embed";45function MyComplianceInquiry() {6const [data, setData] = React.useState(null);7const [isLoading, setLoading] = React.useState(true);89React.useEffect(() => {10fetch("https://trusthub.twilio.com/v1/ComplianceInquiries/Tollfree/Initialize", {11method: "POST",12})13.then((res) => res.json())14.then((data) => {15setData(data);16setLoading(false);17});18}, []);1920return !isLoading ? (21<TwilioComplianceEmbed22inquiryId={data.inquiry_id}23sessionToken={data.inquiry_session_token}24onReady={() => {25console.log("Ready!");26}}27onInquirySubmitted={() => {28console.log("Registration complete");29}}30widgetPadding={{top: 0, left: 100, right: 100, bottom: 0}}31/>32) : (33<Spinner decorative={false} title="Loading" />34);35}3637export default MyComplianceInquiry;
We currently do not provide native support for integrations with frontend frameworks other than React. However, we are releasing a hosted version of this product soon, so customers using non-React frameworks or older versions of React can also use the Compliance Embeddable. Please check back on this page for more details in the coming months.