Ping Telephony – Create custom OTP and ARN messages

📘

NOTE:

To add this product to your account, contact a Telesign expert. This product is available for full-service accounts only.

Telesign's API for SMS allows customers who are using Telesign as their telephony provider with PingOne to create customized one-time passcode (OTP) and ARN (alert, reminder, and notification) messages. Once Telesign is configured as a provider for use with PingOne, the message field will use a Ping notification template that you set up to customize the contents of the OTP or ARN message that you want to send to your end users.

Common use cases

Here are examples of common use cases for customized OTP and ARN messages that can be sent.

  • Send a personalized OTP or SMS alert to an end user's phone number.
  • Send a timely reminder to an end user's phone number such as password reset notification/confirmation.
  • Send a personalized notification to an end user's phone number.

Examples of these use cases include:

  • OTP messages that are customized with the end user's name.
  • OTP messages that include a company name or security reminder.
  • Account status change notifications such as password changes.
  • Password Recovery notifications for end users who have forgotten their password and have started the Forgot password process.
  • Strong Authentication notifications for end users setting up strong authentication.
  • Transaction notifications for end users when strong authentication is required for transaction approval. For example, elevated security for a high value or high risk resource or service.
  • Verification code notifications advising end users when verification codes are sent to the email address in the end user profile to verify an end user account.

📘

NOTE:

Only OTP and ARN (alert, reminder, and notification) messages sent via SMS may be customized. For simple templated SMS and voice OTP messages, please refer to Ping Telephony – Send OTP-only SMS and voice messages.

Basic Usage

At a high-level, the following workflow occurs when using the Telesign SMS API with PingOne when you bring Telesign as your PingOne provider.


A diagram of the high-level workflow that occurs when using the Telesign SMS API with PingOne.

Step 1 - Configure your Telesign account

This step is completed by Telesign Customer Support who will assist you in onboarding for the correct Telesign product(s) that you need to integrate Telesign as your telephony provider. When you contact us, advise our Customer Support team that you want to send custom OTP or ARN messages with PingOne.

Ask Customer Support for assistance with the following tasks:

  • Enable SMS (Telesign's API for SMS)

PLUS:

  • Enable a Sender ID purchased from Telesign.

📘

NOTE:

You will not be able to use your legacy shared Sender ID from Ping Identity. You will need to purchase a dedicated phone number from Telesign to use as a Sender ID for SMS messages. This article has details on how to get a dedicated phone number. Contact a Telesign expert for assistance.

Step 2 - Locate your Telesign Authentication credentials

You will need to enter in your Telesign Authentication credentials before you configure Telesign as a provider in Ping's portal. These are your Customer ID and your API Key.

  1. Locate your Customer ID and API Key using the instructions on How do I find my Customer ID and API Key.
  2. In the Authorization section, enter your Customer ID as the User Name and enter your API Key as the Password.

Step 3 - Select a PingOne notification template

Follow the instructions in the PingOne Notification Templates section to select a PingOne notification template (Select User ExperienceNotification Templates inside the PingOne portal). To send custom OTP and ARN messages using the SMS API API endpoint, you will need to select a PingOne template marked as being available for SMS. See Configuring a custom notification provider for PingOne for general configuration information. We recommend that you configure your notification template before you test your template but you may make adjustments to the notification template at any time during the setup process.

Step 4 - Configure and test the Telesign SMS endpoint

These instructions will help you navigate the PingOne platform as you set up Telesign as your telephony provider in the PingOne platform. The table below provides a list of the recommended values for each field when using Telesign's SMS endpoint with the PingOne platform. You can add additional fields by selecting + Add Key, Value for each additional field you need. You can also use the console to test the selected endpoint, which we recommend doing before using the endpoint.

URL: Use the POST https://rest-ww.telesign.com/v1/messaging endpoint (the Telesign SMS API).

Field
(Value)
Field
(Value)
Notes
Body
Select Form from the menu.
Add the key and value pairs listed below after selecting Form.Select + Add Key, Value for each additional entry
Type
POST
URL
https://rest-ww.telesign.com/v1/messaging
Use this endpoint.
Key
phone_number
Value
${to}
Contains the end user's phone number with country code included. Avoid use of special characters and spaces.
Key
message
Value
${message}
Contains the text of the message sent to the end user. You are limited to 160 characters. If you send a very long message, Telesign splits your message into separate parts.
Key
message_type
Value
ARN OR OTP
We recommend using ARN as the message_type
Headers
content-type
Value
application/x-www-form-urlencoded

After you set up these fields, select Send Test SMS and enter the country and test phone number along with your password. Select Send and then review the status or error messages in the lower right corner. Adjust or send again if adjustments are needed. Make sure to save your changes and fully test your setup before using using in your final integration.

Step 5 - Modify the PingOne notification templates

Use the instructions on PingOne - Notification templates to modify the notification templates. Once configured, the value for message will use the contents of the template to customize the message sent to the end user. For example, you can set up a template to insert an end user's name as well the OTP code in a message. Be sure to test your template and telephony provider configuration before using. The PingOne platform includes a testing button.

Step 6 - Next steps


🚧

CAUTION:

You are subject to all compliance rules as appropriate for your transaction. Note that each country has its own rules and regulations so please follow them carefully.