--- title: Configuring a custom notification provider for PingOne description: Use the information in this section to configure PingOne to use a custom notification provider. component: pingone page_id: pingone:settings:p1_sender_configure_custom_provider canonical_url: https://docs.pingidentity.com/pingone/settings/p1_sender_configure_custom_provider.html revdate: May 10, 2024 section_ids: steps: Steps --- # Configuring a custom notification provider for PingOne Use the information in this section to configure PingOne to use a custom notification provider. | | | | - | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | | * You can define up to 10 SMS and Voice custom notification providers. * When defining more than one custom provider, the first provider on the **SMS/Voice** tab is the one that's used to send notifications unless you specify one of the other providers in the notification policy you're using. | ## Steps 1. Go to **Settings > Senders**. 2. Click **+**, enter the following options, and then click **Next**: 1. In the **Sender Type** list, select **SMS/Voice**. 2. In the **Provider Type** list, select **Custom Provider**. 3. In the **Provider Configuration** window, enter the following information: * **Provider Name**: Enter a meaningful name for your provider. * **Authorization**: * To use basic authentication, select **Basic** and enter the username and password. | | | | - | ------------------------------------------------------------------------------------------------------------------------- | | | When editing an existing configuration, click **Change Account** to enter a new password for the custom provider account. | * To use bearer token authorization, select **Bearer** and enter the token to use. * To use OAuth2 authorization, select **OAuth2 - Client Credentials** and enter the URL of the authorization server that provides the access token, the client's public identifier, and the client's secret. * To use custom header authorization, select **Custom Header** and enter the header name and the value to use for the header. * **Scope**: Click **[icon: plus, set=fa]Add Scope** to configure an OAuth 2.0 scope. * **Origination**: Click **[icon: plus, set=fa]Add Sender Phone Number** to configure a sender phone number, and for each number entered, select the following: 1. **Type**: Select the type of phone number * **Standard**: The sender **Number** must conform to the valid format of a full international phone number. * **Toll-free**: The sender **Number** should be a valid toll-free phone number (United States only). It's the customer's responsibility to confirm that the number is toll-free. * **Short code**: The sender **Number** must conform to the valid format of a short code phone number (United States only). It's the customer's responsibility to confirm that the number is a short code. 2. **Countries**: For **Toll-free** and **Short code** numbers, to configure supported **Countries** for notification recipients do the following: * Click in the **Countries** field. The **Configure countries** modal opens. * Click in the **Select countries** field to display the list of countries. Select a country from the list. | | | | - | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | | * **Toll-free**: Add multiple countries in the **Select countries** list. If you don't specify a country, the specified toll-free number is only used to dispatch notifications to recipient numbers in the United States. * **Short code**: Select only one country in the **Select countries** list. If you don't specify a country, the specified short code is only used to dispatch notifications to recipient numbers in the United States. | 3. **Voice**: Mark the checkbox to configure the number to dispatch voice notifications. 4. **SMS**: Mark the checkbox to configure the number to dispatch SMS notifications. Repeat this step to configure additional sender phone numbers. 4. To specify the information required by the API of your provider for SMS messages, select the **SMS** checkbox and then configure the following fields: | | | | - | -------------------------------------------------------------------------- | | | You must select and configure at least one type of message (SMS or Voice). | 1. **Type**: Choose the type of operation to issue SMS notification requests to the associated vendor **URL** endpoint. * **POST** (default) * **GET** 2. **URL**: The vendor endpoint that receives SMS notification requests using the corresponding operation and request body. 3. **Body** (optional): * **None**: The vendor endpoint receives SMS notification requests without a request body. * **Form**: The notification request body is in the form of key and value pairs. Click **[icon: plus, set=fa]Add Key, Value** for each new key and value pair that you want to enter. * **Raw**: Enter the notification request as free-form JSON text. | | | | - | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | | Changing the request body format style from **Form** deletes the request body's key and value pairs, and changing the format style from **Raw** deletes the request body's free-form JSON text. | * Include the following variables in the customized body: * `${from}` - Depending on vendor requirements, the `${from}` variable might be optional. * `${to}` - If there is a requirement to send the country code and national (significant) number separately, instead of `${to}`, the body should include: * `${to.country-code}` * `${to.national-number}` * `${message}` * You can use the following optional variables: * `${locale}` - locale * `${otp}` - OTP * The Body section supports dynamic variables. Learn more in [Dynamic variables](https://developer.pingidentity.com/pingone-api/platform/notifications/notifications-templates.html#notifications-templates-dynamic-variables) in the PingOne Platform API Reference. To prevent problems related to special character encoding when passing PingOne variables to the provider, it's recommended that you specify the type of input your provider expects when you include a PingOne variable. Use the syntax `${variable_name|format_used}`, for example, `${message|json}`. The formats you can specify are: * json * html * url * base64 4. **Headers**: Enter any required headers for the SMS notification request. Click **[icon: plus, set=fa]Add Header** for each new header you want to add. * For JSON body format, set the header to `content-type=application/json`. * For x-www-form-urlencoded body format, set the header to `content-type=application/x-www-form-urlencoded`. 5. **Plus sign**: * **Enabled** (default): Permit the standard number format for the sender and recipient numbers, including a leading plus sign. * **Disabled**: For configurations where the provider requires the sender and recipient numbers without a leading plus sign. 6. Click **Send Test SMS** to verify your configuration. The **Send Test SMS** modal opens. Enter a destination phone number to test receiving an SMS notification from your configured custom provider. 1. In the **Send To** field, select the phone number's country, and enter the destination phone number. 2. Click **Send**. The **Send Test SMS** modal closes. 3. Verify that you've received a test notification on the destination phone. 5. To specify the information required by the API of your provider for voice messages, select the **Voice** checkbox and then configure the following fields: | | | | - | -------------------------------------------------------------------------- | | | You must select and configure at least one type of message (SMS or Voice). | 1. **Type**: Choose the type of operation to issue voice notification requests to the associated **URL** endpoint. * **POST** * **GET** 2. **URL**: The vendor endpoint that will receive voice notification requests using the corresponding operation and request body. 3. **Body**: * **None**: The vendor endpoint receives voice notification requests without a request body. * **Form**: The notification request body is in the form of key and value pairs. Click **[icon: plus, set=fa]Add Key, Value** for each new key and value pair that you want to enter. * **Raw**: Enter the notification request as free-form JSON text. | | | | - | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | | Changing the request body format style from **Form** deletes the request body's key and value pairs, and changing the format style from **Raw** deletes the request body's free-form JSON text. | * Include the following variables in the customized body: * `${from}` - Depending on vendor requirements, the `${from}` variable might be optional. * `${to}` - If there is a requirement to send the country code and national (significant) number separately, instead of `${to}`, the body should include: * `${to.country-code}` * `${to.national-number}` * `${message}` * You can use the following optional variables: * `${voice}` - the type of voice configured for notifications * `${locale}` - locale * `${otp}` - OTP * `${user.username}` - user's username * `${user.name.given}` - user's given name * `${user.name.family}` - user's family name * The Body section supports dynamic variables. Learn more in [Dynamic variables](https://developer.pingidentity.com/pingone-api/platform/notifications/notifications-templates.html#notifications-templates-dynamic-variables) in the PingOne Platform API Reference. To prevent problems related to special character encoding when passing PingOne variables to the provider, it's recommended that you specify the type of input your provider expects when you include a PingOne variable. Use the syntax `${variable_name|format_used}`, for example, `${message|json}`. The formats you can specify are: * json * html * url * base64 | | | | - | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | | The `` and `` tags aren't supported for custom provider voice one-time passcode (OTP) *(tooltip: \
\

A passcode valid for only one sign-on or transaction on a computer system or other digital device. Also known as a one-time password, one-time PIN, or dynamic password.\

\
)* messages. To add a pause in a custom provider voice message, use the **Preceding padding** (`"beforeTag"`) and **Succeeding padding** (`"afterTag"`) parameters, for example: | 4. **Preceding padding**: Set a custom pause or padding before an OTP character, to leverage vendor capabilities when sending voice notifications. For example: ``` "beforeTag":"", ``` 5. **Succeeding padding**: Set a custom pause or padding after an OTP character to leverage vendor capabilities when sending voice notifications. For example: ``` "afterTag":" " ``` 6. **Headers**: Enter any required headers for the voice notification request. Click **[icon: plus, set=fa]Add Header** for each new header you want to add. * For JSON body format, set the header to `content-type=application/json`. * For x-www-form-urlencoded body format, set the header to `content-type=application/x-www-form-urlencoded`. 7. **Plus sign**: * **Enabled** (default): Permit the standard number format for the sender and recipient numbers, including a leading plus sign. * **Disabled**: For configurations where the provider requires the sender and recipient numbers without a leading plus sign. 8. Click **Send Test Voice** to verify your configuration. The **Send Test Voice** modal opens. Enter a destination phone number to test receiving a voice notification from your configured custom provider. 1. In the **Send To** field, select the phone number's country, and enter the destination phone number. 2. Click **Send**. The **Send Test SMS** modal closes. 3. Verify that you've received a test notification on the destination phone. 6. Click **Save**. | | | | - | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | | When using a custom provider, if there are repeated errors within a short period or long delays before responses from the provider, PingOne assumes there's some underlying issue and activates a circuit breaker, suspending notification attempts using that provider temporarily. |