You can configure a custom phone provider for SMS messages using a phone number as a user identifier. A custom phone provider uses Actions to route the SMS messages to a phone provider of your choice when verifying phone numbers and resetting passwords. You may want to configure a custom phone provider for the following use cases:
  • Use different phone providers based on application context, which may include different geographic regions where phone provider message prices can vary significantly.
  • Use different phone providers based on organization context, where some B2B customers may require specific providers.
You can configure a custom phone provider with the or .

​
Configure a custom phone provider with the Auth0 Dashboard or Management API

To configure a custom phone provider, you must use the custom-phone-provider Action trigger that is not available in the Auth0 Actions editor. To learn more, read Example custom-phone-provider Action.

​
Add a custom phone provider with the Auth0 Dashboard

To configure a new custom phone provider in the Auth0 Dashboard:
  1. Navigate to Branding > Phone Provider. This takes you to the Phone Message Provider page. By default, the Twilio phone provider is selected.
  2. Select the Custom phone provider option in the Phone Provider section.
  3. Select the Delivery Method:
    1. Text: The verification code will be delivered to your users via SMS.
    2. Voice: The verification code will be delivered to your users via Voice Message.
  4. Under Provider Configuration, write your actions code to configure a custom phone provider:
    1. Consult with your provider’s documentation to understand how to deliver messages to their API.
    2. Add any required secrets to authenticate with the API.
    3. (Optional) You can edit the Action using the full Actions editor interface by clicking the Edit in Expanded Editor button. After editing your action in the Actions editor, Save and Deploy the Action from that interface. Click the Back to Phone Provider link at the top of the Actions editor page to return to the Phone Message Provider page. You will need to select the Custom phone provider option again in the Phone Provider section.
  5. Click the Save button at the bottom of the page.
When you click Save, the Action automatically saves and deploys. To test the custom phone provider configuration before using it in a production environment, click Send Test Message.
You cannot click Send Test Message to test your custom phone provider until after you save your custom phone provider configuration.

​
Edit a custom phone provider with the Auth0 Dashboard

To edit an existing custom phone provider in the Auth0 Dashboard:
  1. Navigate to Branding > Phone Provider. This takes you to the Phone Message Provider page.
  2. Modify the Action code on the Phone Message Provider page as needed.
    1. (Optional) You can edit the Action using the full Actions editor interface by clicking the Edit in Expanded Editor button. After editing your Action in the Actions editor, Save and Deploy the Action from that interface. Then click the Back to Phone Provider link at the top of the Actions editor page.
  3. Click the Save button at the bottom of the page.
When you click Save, the Action automatically saves and deploys. To test the custom phone provider configuration before using it in a production environment, click Send Test Message.
An example of a custom phone provider you can configure is Twilio Verify. To learn more, read Configure custom phone provider with Twilio Verify.

​
Example custom-phone-provider Action

The custom-phone-provider trigger is different from the send-phone-message trigger, which should not be used for configuring a custom phone provider. To learn more, read the following: The following code sample is a custom-phone-provider Action that has the functionality of a send-phone-message Action: 
const { fetch } = require('undici');
/**
* Handler to be executed while sending a phone notification
* @param {Event} event - Details about the user and the context in which they are logging in.
* @param {CustomPhoneProviderAPI} api - Methods and utilities to help change the behavior of sending a phone notification.
*/
exports.onExecuteCustomPhoneProvider = async (event, api) => {

  if (event.notification.message_type.startsWith('otp')) {
    const body = {
      from: event.notification.from,
      action: event.notification.message_type === 'otp_verify' ? 'second-factor-authenticator' : 'enrollment',
      language: event.notification.locale,
      recipient: event.notification.recipient,
      message_type: event.notification.delivery_method,
      text: event.notification.as_text,
      code: event.notification.code,
    };

    const response = await fetch(event.secrets['MY_ENDPOINT'], {
      method: 'POST',
      headers: {
        authorization: `Bearer ${event.secrets['MY_SECRET']}`,
      },
      body: JSON.stringify(body),
    });

    console.log(response.status); // 200
    console.log(await response.text()); // request's response body!
  }

  return;
};