PingOne

Configuring a custom notification provider for PingOne

Use the information in this section to configure PingOne to use a custom notification provider.

Steps

  1. Go to Settings > Sender.

  2. Click the SMS/Voice tab.

    The default Ping Server is shown, until a Custom Server or Custom Provider is configured for the environment.

  3. Select Custom Provider to use your organization’s provider account instead of the Ping service.

    Selecting Ping Identity or Custom Server will result in deletion of the custom provider configuration, if one exists.

  4. Provider Name: Enter the name of your provider account.

  5. From Authorization:

    Choose from:

    • Basic

      1. User Name: Enter the username for your custom provider account.

      2. Password: Enter the password for your custom provider account.

        When editing an existing configuration, you can click Change Account to enter a new password for the custom provider account.

    • Bearer: In Token, enter the token for your custom provider account.

  6. Origination: Click 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 (US only). It is 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 (US only). It is the customer’s responsibility to confirm that the number is a short code.

    2. Countries:

      For Toll-free and Short code numbers, you can configure supported Countries for notification recipients:

      • Click in the Countries field. The Configure countries popup opens.

      • Click in the Select countries field to display the list of countries. Select a country from the list.

        • Toll-free: You can add multiple countries in the Select countries list. If no country is specified, the specified toll-free number can only be used to dispatch notifications to United States recipient numbers.

        • Short code: You can select only one country in the Select countries list. If no country is specified, the specified short code can only be used to dispatch notifications to United States recipient numbers.

    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.

  7. Fallback to Ping Twilio account: Configure the fallback setting, to handle notification dispatch if your custom provider service becomes unavailable for any reason. (optional): Enter the phone number that sends the notification. You can leverage shortcodes and toll-free numbers for increased throughput for US numbers.

    • By default, the fallback option is set to Disable. No notifications will be sent while your custom provider service is unavailable.

    • Select Enable to use Ping Identity’s sender account to fall back to as an alternative and handle notification dispatch, while your custom provider account is unavailable.

  8. SMS:

    To use a different custom provider to send SMS messages, configure this section.

    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 will receive SMS notification requests using the corresponding operation and request body.

    3. Body (optional): The request body format style for configuration maintenance.

      • 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 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.

        The customized body should include the variables:"${from}", "${to}", and "${message}". Depending on vendor requirements, the "${from}" variable might be optional.

        The body can include:

        • ${locale} - locale

        • ${otp} - OTP

          You can also use dynamic variables in the Body section. For more information, see Dynamic variables in the PingOne Platform API Reference.

    4. Headers: Enter headers for the SMS notification request. Click Add Header for each new header you want to add. The header style assumes the same format style (key and value pair, or free text) according to the format you selected for the request body.

      • 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 check your configuration.

      The Send Test SMS popup 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 popup closes.

      3. Verify that you’ve received a test notification on the destination phone.

  9. Voice:

    To use a different custom provider to send voice messages, configure this section.

    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: The request body format style for configuration maintenance.

      • 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 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.

        The customized body should include the variables:"${from}", "${to}", and "${message}". Depending on vendor requirements, the "${from}" variable might be optional.

        In addition, the body can include the following optional variables:

        • ${voice} - the type of voice configured for notifications

        • ${locale} - locale

        • ${otp} - OTP

        • ${user.user.name} - user’s username

        • ${user.name.given} - user’s given name

        • ${user.name.family} - user’s family name

        You can also use dynamic variables in the Body section. For more information, see Dynamic variables in the PingOne Platform API Reference.

      The < repeatMessage> and <pause1sec> tags are not supported for custom provider voice OTP 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":"<Say>",

    5. Succeeding padding: Set a custom pause or padding after an OTP character, to leverage vendor capabilities when sending voice notifications. For example:

      "afterTag":"</Say> <Pause length=\"1\"/>"

    6. Headers: Enter headers for the voice notification request. Click Add Header for each new header you want to add. The header style assumes the same format style (key and value pair, or free text) according to the format you selected for the request body.

      • 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 check your configuration.

      The Send Test Voice popup 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 popup closes.

      3. Verify that you’ve received a test notification on the destination phone.

  10. Click Save.