PingID Administration Guide

Configuring a Twilio account for PingID SDK

Configure PingID SDK for a Twilio account.

About this task

PingID SDK uses Twilio for voice and SMS. By enabling your own Twilio account, you are taking responsibility for despatching SMS and voice messages.

Ensure that you have available your Twilio account SID and auth token. You can copy them as required from the Twilio dashboard. You should also have set up one or more origination phone numbers. The following procedure will guide you in configuring PingID SDK to use your Twilio account.

To configure PingID SDK for a Twilio account:

Steps

  1. Sign on to the admin console.

  2. Go to Setup → PingID SDK.

  3. Under SMS/Voice Sender, choose Custom.

    The custom configuration settings appear.

    A screen capture of the SMS/Voice Sender section with Custom and Twilio selected.

  4. In the SMS/Voice Sender dropdown, select Twilio.

    A custom Twilio account applies across all PingID SDK applications of the organization.

  5. Copy/paste the Twilio account SID to the indicated field.

    If the SID is shorter than 34 characters, you will be shown this error message:

    A screen capture of the Account SID with the error message

  6. Copy/paste the Twilio auth token to the indicated field.

  7. Click the Verify Account button. That validates the account to PingID SDK and populates the Origination Numbers list from your Twilio account.

    • If the auth token is incorrect, you will be shown this error message:

    A screen capture of Account SID with the error message

    • If there are no originating phone numbers in the Twilio account, it will not be validated to PingID SDK.

    If the account was successfully verified, the display will change to show a list of originating numbers from Twilio:

    A screen capture of the SMS/Voice Sender section with a list of origination numbers showing.

  8. Select at least one originating telephone number to use.

    • Twilio allows you to define phone numbers for use with either voice or SMS or both. PingID SDK uses the same number for both voice and SMS and will so relate to the Twilio defined numbers. Twilio numbers (excluding short codes) that are defined as voice only or SMS only are filtered out from the numbers list to avoid operational errors.

    • Twilio allows the use of sender IDs (in place of telephone numbers) for commercial use or to comply with regulations requiring SMSs to be sent as transactional and not promotional.

    When using the Ping Identity account, all originating numbers are defined as transactional with a sender ID in Twilio. To achieve the same functionality in a custom Twilio account, you must configure it directly in Twilio. Sender IDs are displayed according to the sender IDs sent in the API requests. Short codes are supported only for the United States, and only for SMS messages. If only short codes are chosen, but the number is not a United States number:

    • If the admin configures FALLBACK SMS/VOICE SENDER as Ping Identity or Syniverse, the selected fallback account’s phone numbers are used.

    • If the admin Disables the FALLBACK SMS/VOICE SENDER option, the SMS will not be sent.

  9. Enable FALLBACK SMS/VOICE SENDER as Ping Identity or Syniverse to fall back to one of these alternatives if Twilio becomes unavailable for reasons explained in the following note.

    Under fallback:

    If PingID SDK receives an error during the message despatch process that the used number is invalid, it will retry using the fallback option.

    • If there was no way originating the SMS or voice event with tenant’s own account, and admin defined a fallback to Syniverse or Ping Identity’s account, the event will be originated from the fallback account.

    • The following errors will cause fallback:

      • All API errors (but not SMS delivery errors)

      • No origination number was found on the Twilio account

    • If a transaction was charged to a specific account (Ping or custom), it does not imply that subsequent transactions will be charged to the same account. The account charged for each transaction is determined on an individual basis. Preference is always given to the custom account.

    • If you configured FALLBACK SMS/VOICE SENDER as Ping Identity, you will be billed at Ping Identity’s rates and not at any preferential rates you have directly from Twilio. In addition, Ping Identity originating numbers and setup parameters will be in force.

    • Ping Identity:

      Use Ping Identity’s SMS/voice sender account in cases of fallback.

    • Syniverse:

      Enter the Syniverse Access Token and select at least one Origination Number:

      A screen capture of the Fallback SMS/Voice Sender section with Syniverse selected and an address entered in the Address field.

      1. Copy/paste your Syniverse Access Token to the indicated field.

        The system uses your access token to connect to your Syniverse account.

        Recommended: In your account in the Syniverse portal, define an application that is dedicated to PingID SDK traffic. Use this application for analyzing PingID SDK traffic throughput, and troubleshooting SMS or voice message despatch cases.

      2. Click the Verify Account button. That validates the account to PingID SDK and populates the Origination Numbers list from your Syniverse account.

        • If the Access Token is incorrect, you will be shown this error message:

        A screen capture of the Access Token with the error message

        • If your Syniverse account is not fully configured a yellow exclamation mark appears next to the Access Token field. If you click on it, this message appears:

        A screen capture of the Syniverse Not Configured warning message.

        • If there are no originating phone numbers in the Syniverse account, it will not be validated to PingID SDK.

        • To configure your Syniverse account to work with PingID SDK:

          1. Copy the URL from the Address field.

          2. In your Syniverse account:

            • In the Delivery Configuration, paste the URL that you copied from the PingID SDK Address field.

            • Create two subscriptions: SCG-Message and SCG-Voice-Calls.

        See How to setup a Webhook for Receiving Messages and Notifications in the Syniverse Developer Community for more information.

        These Syniverse configurations are required in order that Ping Identity’s dashboards and reports will reflect complete and accurate data. Ping Identity will not be able to troubleshoot SMS or voice events related to Syniverse if these configurations are incomplete.

    If the account was successfully verified, the display will change to show a list of originating numbers from Syniverse:

    + image::itu1597828167369.png[alt="A screen capture of the list of Organization Numbers.",role="border-no-padding"]

    1. Select at least one originating telephone number to use.

  10. To save your settings, click Save at the bottom of the Setup window.

  11. To complete the setup process, enter your legal consent:

    A screen capture of the Third-party Service Consent.

    You will only be asked for legal consent when entering a new SID.