Twilio Verify Connector

Descope's Twilio Verify connector allows you to utilize the Twilio Verify SDK and service to authenticate users via Voice, SMS, and email for OTP rather than utilizing Descope OOTB OTP verification functions. This article will guide you through setting up and using the Twilio Verify connector.

Note

You cannot customize the OTP template within Descope when utilizing the Twilio Verify connector. You must rely on the configured templates within your Twilio Verify account.

Configure Twilio Verify Connector

Descope uses your Twilio Verify Account SID, Service SID, and the API Key and Secret or the Auth token to authenticate the connector to the Twilio Verify API.

To configure the Twilio Verify connector, navigate to the Connectors page within the Descope console, search for Twilio Verify, and click the tile.

Settings

Below is the list of settings and configurations available that you can customize for your Twilio Verify Connector.

Connector name: Custom name for your connector. This will come in handy when creating multiple connectors from the same connector template.
Connector Description: Briefly describe the purpose of this connector.
Account SID: A unique key provisioned for Twilio customers that acts as a username.
Service SID: A unique key that identifies the Twilio Verify service.
Authentication: There are two ways of authenticating with Twilio service:
- Auth token: The authentication token associated with the Account SID.
- API key and secret: The preferred way to authenticate to Twilio's services; consist of a SID and a secret.
From Email address (only for email verification): A verified Twilio (Sendgrid) email address you own. Defines the email sender.

You can test if your connector's configuration is working properly simply by hitting the Test button and viewing the Test Results panel.

Save your configuration by hitting Create.

Using Twilio Verify in Auth Methods and Flows

Configure Twilio Verify as the Default OTP Connector

To configure Twilio Verify as your default connector for the various OTP auth methods for SMS, Voice, and Email, navigate to OTP within Authentication Methods, and select the configured Twilio Verify connector. Note that you will see the templates option disappear because you cannot customize the OTP template within Descope when utilizing the Twilio Verify connector. You must rely on the configured templates within your Twilio Verify account.

Once you have configured Twilio Verify as the default connector within the OTP Auth method, Descope flows and any OTP calls via the API/SDK will utilize Twilio Verify for OTP verification.

Using Twilio Verify Explicitly in Flows

To override the default OTP connector within your flow to utilize Twilio Verify, navigate to Flows and choose your flow. Once you are in the flow that you'd like to use Twilio Verify, select and edit the action that starts the OTP process, such as Sign In, Sign Up, or Sign Up or In with OTP via SMS, Email, or Voice. If you have not yet added the OTP action, you can do so by clicking the blue + icon at the top left, searching and selecting the OTP action, and then selecting and editing the initiating action.

In this example, we will update the Sign Up or In / OTP / SMS action to utilize the Twilio Verify connector and override the configured default for the OTP auth method.

Once in edit mode for the initiating OTP action, select the dropdown for the connector and choose your Twilio Verify connector. After selecting the Twilio Verify connector, click done, and save your flow. Note that you will see the templates option disappear because you cannot customize the OTP template within Descope when utilizing the Twilio Verify connector. You must rely on the configured templates within your Twilio Verify account.This action within your flow will utilize the Twilio Verify connector and override the configured default OTP connector.

Localized Twilio Verify Messages

Twilio Verify allows you to send messages in different languages based on the supplied locale. Descope integrates with this functionality by utilizing the browser's locale or the locale configured within the Descope front-end SDK component when sending the request to Twilio Verify. If you want the user's browser to be used when sending messages, no configuration is necessary; Descope will automatically capture the locale and send it to Twilio Verify to send the message in the correct language. If you want to override the language to send the message, you can set the locale within the Descope component, like the example below.

<Descope
  flowId= "twilio-verify"
  onSuccess={(e) => {
    navigate("/");
    console.log("Logged in!");
  }}
  onError={(e) => console.log("Error!")}
  locale="es-MX" // override the locale to be es-MX which will enforce sending the message in Spanish
/>

Handling Twilio Blocked Calls

Twilio may block voice calls to certain numbers; this results in Twilio error code 21216. Essentially, the number is blocked by Twilio due to:

The destination has a high-risk of fraud
Due to regulatory reasons, the destination cannot be reached
You are placing a call to a +1 destination and your account is missing a Primary Customer Profile

Descope allows you to capture this returned error from Twilio and handle it how you would like. See the example image below; however, for further details on handling errors within flows, see this guide.

Was this helpful?

On this page