> ## Documentation Index
> Fetch the complete documentation index at: https://auth0.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Configure a Custom Phone Provider

> Implement a custom-phone-provider Action to send Auth0 SMS and voice messages through any gateway instead of the default phone provider.

You can configure a custom phone provider for SMS messages using a [phone number as a user identifier](/docs/authenticate/database-connections/activate-and-configure-attributes-for-flexible-identifiers). A custom phone provider uses [Actions](/docs/customize/actions/actions-overview) 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 <Tooltip tip="Auth0 Dashboard: Auth0's main product to configure your services." cta="View Glossary" href="/docs/glossary?term=Auth0+Dashboard">Auth0 Dashboard</Tooltip> or <Tooltip tip="Auth0 Dashboard: Auth0's main product to configure your services." cta="View Glossary" href="/docs/glossary?term=Management+API">Management API</Tooltip>.

## 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](#example-custom-phone-provider-action).

<Tabs>
  <Tab title="Auth0 Dashboard">
    #### 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](https://manage.auth0.com/dashboard/#/phone/templates/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**.

    <Callout icon="file-lines" color="#0EA5E9" iconType="regular">
      You cannot click **Send Test Message** to test your custom phone provider until after you save your custom phone provider configuration.
    </Callout>

    #### 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](https://manage.auth0.com/dashboard/#/phone/templates/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**.
  </Tab>

  <Tab title="Management API">
    #### Add a custom phone provider with the Management API

    You can also configure a custom phone provider using the Management API. This is a multi-step process:

    1. Create an [Action](https://auth0.com/docs/api/management/v2/actions/post-action) and set the `supported_triggers.id` to `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.
    2. [Deploy](https://auth0.com/docs/api/management/v2/actions/post-deploy-action) the action.
    3. Set the [phone provider](https://auth0.com/docs/api/management/v2/branding/create-phone-provider) to `custom`.

    <Callout icon="file-lines" color="#0EA5E9" iconType="regular">
      The Action you create with the `custom-phone-provider` trigger will not appear in the Actions library.
    </Callout>

    <Callout icon="file-lines" color="#0EA5E9" iconType="regular">
      If no Action is deployed and you try to configure a `custom` provider, Auth0 will return an error with `"errorCode":"custom_email_provider_deployed_action_not_found"`.
    </Callout>

    #### Edit a custom phone provider with the Management API

    You can also edit a custom phone provider using the Management API.

    1. (Optional) If you don’t know the specific Action ID, you can [get the list of actions](https://auth0.com/docs/api/management/v2/actions/get-actions) via the Management API. The response will include an Actions object. The Action used for the custom phone provider can be identified by the `supported_triggers.id`, which should be set to `custom-phone-provider`.
    2. [Update the Action](https://auth0.com/docs/api/management/v2/actions/patch-action) as needed.
    3. [Deploy](https://auth0.com/docs/api/management/v2/actions/post-deploy-action) the Action.
  </Tab>
</Tabs>

An example of a custom phone provider you can configure is [Twilio Verify](https://www.twilio.com/docs/verify). To learn more, read [Configure custom phone provider with Twilio Verify](/docs/customize/phone-messages/configure-phone-messaging-providers/configure-a-custom-phone-provider/configure-a-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:

* [Action Triggers: custom-phone-provider API Object](/docs/customize/phone-messages/configure-phone-messaging-providers/configure-a-custom-phone-provider/action-triggers-custom-phone-provider-api-object)
* [Action Triggers: custom-phone-provider Event Object](/docs/customize/phone-messages/configure-phone-messaging-providers/configure-a-custom-phone-provider/actions-triggers-custom-phone-provider-event-object)

The following code sample is a `custom-phone-provider` Action that has the functionality of a `send-phone-message` Action:

```javascript lines expandable theme={null}
/**
* 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.secret.SERVICE_URL, {
      method: 'POST',
      headers: {
        authorization: `Bearer ${event.secrets.TOKEN}`,
      },
      body: JSON.stringify(body),
    });

    console.log(response);
  }

  return;
};
```