Twilio Connector
Using Descope's connectors allows you to use Twilio to send SMS and make voice calls with your own Twilio account and trigger these actions within the authentication flow. This article will guide you through setting up and using the Twilio connector.
Configure Twilio connector
Descope uses your Twilio Account SID, Authentication token, API key, secret and sender details for integration.
To configure a Twilio connector, go to the Connectors page within the Descope Console, search for Twilio, and select the connector tile.
Settings
Below is a list of applicable settings for the Twilio 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.
- 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: There are two ways to define the sender of the message:
- Phone Number: A Twilio number you own. Must start with a country code.
- Messaging Service SID: If a messaging service is configured, one of the numbers in that service pool will be used. And if you'd like, the optional field:
- From Phone number (for voice calls): A Twilio number you own. Defines the sender of the voice call. Must start with a + and country code.
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.
Add your Twilio connector to a flow
Configure Twilio as the Default OTP Connector
To configure Twilio as your default connector for the various OTP auth methods for SMS and Voice, navigate to OTP within Authentication Methods, and select the configured Twilio connector. You can further configure the default OTP template for your Twilio messages; for more details, see our guide for Using Email and SMS Templates.
Once you have configured Twilio as the default connector within the OTP Auth method, Descope flows and any OTP calls via the API/SDK will utilize Twilio for OTP verification.
Using Twilio Explicitly in Flows
To override the default OTP connector within your flow to utilize Twilio, navigate to
Flows and choose your flow. Once you are in the flow that you'd like to use Twilio, 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 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 connector. After selecting the Twilio connector, click done, and save your flow. You can also select a customized template; for more details, see our guide for Using Email and SMS Templates. This action within your flow will utilize the Twilio connector and override the configured default OTP connector.
Sending Custom Messages via Twilio in Flows
There may be a use case where you want to send a text message or voice message as part of your Descope flow that is not directly related to the OTP Auth flow; this section will describe how to use Twilio to send custom messages.
Navigate to: Flows, choose your flow. Then, tap the create button
(designated via the + icon), select Connector, and choose Twilio.
Click to set down the connector in your flow editor and double click the action to add required fields:
- To: Who the message or call should be sent to. Setting this dynamically based on previous attributes is recommended (eg.
{{user.phone}}). As you type in the input field, options appear. - Message/Call content: Enter the content of the SMS or call.
Now, link your connector at a logical point in your authentication flow, likely at the end of the flow after the phone number has been submitted by the user.
That's it! Whenever a user goes through your authentication flow, the Twilio connector will be automatically triggered.
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.
