Okta telephony - Send SMS and voice using Messaging

📘
NOTE:
To add this product to your account, contact us. This product is available for full-service accounts only.

This page walks you step-by-step through how to deliver SMS and voice messages using Telesign Messaging if you have written your own code for the Telesign Okta telephony inline hook solution. (This page is only for those who have elected to write their own code rather than use our no-code solution.)

📘
NOTE:
Telesign also offers a no-code solution, Okta Telephony - Telesign no-code inline hook, which provides a user-friendly integration. The no-code option simplifies integration without sacrificing functionality. It is ideal for most users and scenarios.

Before you begin

Make sure you have the following before you start:

Review Okta guide pages: Review these Okta pages:
- Bring Your Own Telephony Required for SMS and Voice - article by Okta so that you are familiar with Okta's telephony changes.
- Telephony inline hook reference - Objects in the request from Okta - familiarize yourself with the parameters in the Okta request.
Understand how to use Telesign Messaging: Review Messaging - Overview and Send a message with advanced features.
Configure your Telesign account: Have your Telesign account configured as described on this page so that the SMS and/or Voice products are enabled.
Configure optional account features: You may elect to have Callback Status and Get Status enabled when your Telesign account is configured. We recommend having Messing callback service enabled so Telesign can send you delivery status updates for your Messaging requests. Go to Messaging - Callback service for more details.
Dedicated phone number You will need to purchase a dedicated phone number from Telesign to use as your Sender ID or Voice caller ID.
Complete all of the steps for writing your own code: If you have elected to not use our no-code solution, you will need to write your own code. Go to our Write your own code for your Telesign inline hook example for more information on how to do this.
Configure your Okta inline hook: Configure the inline hook in the Okta console as described in this section of the Okta telephony - Write your own code for your Telesign inline hook page.
Customize your SMS message: You may customize the SMS message sent to the end user using this Okta procedure. Carefully note Okta's length, character type, and message length count limitations when customizing your SMS message. (Optional)

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

Steps

Send a POST /v1/omnichannel request. Go to Send a message with advanced features for more information.

Go to Request examples at the end of this page for examples of SMS and voice requests.

Include the following parameter values when sending an SMS message, depending on what is received in Okta’s request:

Parameter	Value	Description	Required?
`channels`	array of channel objects	Add channel objects to the array in the order you want the service to try the channels.	yes
`channels[0]`	`{"channel":"sms"}`	Only used if this is Okta request received: `data.messageProfile.deliveryChannel: "SMS"` Include `sms` as the only channel.	yes
`channels[0].fallback_time`	A time in seconds.	Specify the time to wait before cascading to the next channel.	no
`recipient.phone_number`	`data.messageProfile.phoneNumber` from Okta request.	The recipient's phone number as provided by Okta.	yes
`message.sms.template`	`text`	The name of the template to use for this message.	yes
`message.default.parameters.text`	`data.messageProfile.msgTemplate` from Okta request.	The main text of your message, which should be the same as in Okta request parameter `msgTemplate`.	yes
`message_type`	`OTP`	The purpose for which the message is being sent.	yes

Include the following param values when sending a Voice message, depending on what is received in Okta’s request:

Parameter	Value	Description	Required?
`channels`	array of channel objects	Add channel objects to the array in the order you want the service to try the channels.	yes
`channels[0]`	`{"channel":"voice"}`	Only used if this is Okta request received: `data.messageProfile.deliveryChannel: "voice call"` Include `voice` as the only channel.	yes
`channels[0].fallback_time`	A time in seconds.	Specify the time to wait before cascading to the next channel.	no
`recipient.phone_number`	`data.messageProfile.phoneNumber` from Okta request.	The recipient's phone number as provided by Okta.	yes
`message.voice.template`	`otp_voice`	The name of the template to use for this message.	yes
`message.voice.parameters.otp_code`	`data.messageProfile.otpCode` from Okta request.	The OTP code provided in the Okta request.	yes
`message.voice.parameters.language`	`data.messageProfile.locale` from Okta request.	The location of the OTP Requester (i.e. the Display language selected by the end user).	yes
`message_type`	`OTP`	The purpose for which the message is being sent.	yes

The 3001 status code ("Message in progress") is used by Telesign when a request is processed successfully.

Response provided by Messaging - success

{
  "status": {
    "code": 3001,
    "description": "Message in progress"
  },
  "reference_id": "0123456789ABCDEF0123456789ABCDEF",
  "external_id": null
}

Provide Okta with a successful response in the manner that Okta expects it using the commands object. Note that transactionId is your Telesign reference ID.

Response that you provide to Okta (This response is coded by you)

{
  "commands":[
    {
      "type":"com.okta.telephony.action",
      "value":[
        {
          "status":"SUCCESSFUL",
          "provider":"Telesign",
          "transactionId":"0123456789ABCDEF0123456789ABCDEF",
          "transactionMetadata":""
        }
      ]
    }
  ]
}

If the request is NOT processed successfully, a response other than 3001 is sent. Go to Okta telephony - errors and status codes for more information.

Response provided by Messaging - failure

{
    "status": {
        "code": 3300,
        "description": "Missing parameter channels"
    },
    "external_id": null
}

Provide Okta with an unsuccessful response in the manner that Okta expects it using the error object.

Response that you provide to Okta (This response is coded by you)

{
  "error":{
    "errorSummary":"3300",
    "errorCauses":[
      {
        "errorSummary":"3300",
        "reason":"Missing parameter channels",
        "location":"en"
      }
    ]
  }
}

(Optional) Receive asynchronously the final status of each transaction when the Messaging callback service is enabled. (Applies only to customers who write their own code). For statuses received on callback, no further actions are needed by you. Contact our Customer Support Team to enable the Get Status feature to receive transaction statuses on demand.

Callback delivery status

{
  "channel_status": [
    {
      "voice": {
        "code": 3110,
        "description": "Invalid request",
        "reference_id": "0123456789ABCDEF0123456789ABCDEF",
        "updated_on": "2024-08-05T09:54:46.083656Z"
      }
    }
  ],
  "mcc": "220",
  "mnc": "01",
  "reference_id": "0123456789ABCDEF0123456789ABCDEG",
  "status": {
    "channel": "voice",
    "code": 3003,
    "description": "Delivery error",
    "updated_on": "2024-08-05T09:54:46.083656Z"
  }
}

Get Status response

{
  "status": {
    "updated_on": "2024-08-05T09:51:07.000897Z",
    "code": 3000,
    "description": "Delivered",
    "last_channel": "sms"
  },
  "reference_id": "0123456789ABCDEF0123456789ABCDEF",
  "additional_info": {
    "mcc": "220",
    "mnc": "01"
  },
  "channel_status": [
    {
      "sms": {
        "code": 3000,
        "description": "Delivered",
        "reference_id": "0123456789ABCDEF0123456789ABCDEG",
        "updated_on": "2024-08-05T09:51:07.000897Z"
      }
    }
  ]
}

Request examples

SMS

Request received from Okta on your webhook

{
  "eventId": "uS5871kJThSsU8qlA1LTcg",
  "eventTime": "2022-01-28T21:43:40.000Z",
  "eventType": "com.okta.telephony.provider",
  "eventTypeVersion": "1.0",
  "contentType": "application/json",
  "cloudEventVersion": "0.1",
  "source": "https://${yourOktaDomain}/api/v1/inlineHooks/calz6lVQA77AwFeEe0g3",
  "requestType": "com.okta.user.telephony.pre-enrollment",
  "data": {
    "context": {
      "request": {
        "id": "reqRgSk8IBBRhuo0YdlEDTmUw",
        "method": "POST",
        "url": {
          "value": "/api/internal/v1/inlineHooks/com.okta.telephony.provider/generatePreview"
        },
        "ipAddress": "127.0.0.1"
      }
    },
    "userProfile": {
      "firstName": "test",
      "lastName": "user",
      "login": "[email protected]",
      "userId": "00uyxxSknGtK8022w0g3"
    },
    "messageProfile": {
      "msgTemplate": "Your code is 11111",
      "phoneNumber": "9876543210",
      "otpExpires": "2022-01-28T21:48:34.321Z",
      "deliveryChannel": "SMS",
      "otpCode": "11111",
      "locale": "en"
    }
  }
}

Request sent to Messaging based on Okta’s request

{
    "recipient": {
        "phone_number": "9876543210"
     },
    "channels": [
        {
            "channel": "sms"
        }
    ],
    "message": {
        "sms": {
            "template": "text",
            "parameters": {
                "text": "Your code is 11111"
            }
        }
    },
    "message_type": "OTP"
}

Voice

Request received from Okta on your webhook

{
  "eventId": "uS5871kJThSsU8qlA1LTcg",
  "eventTime": "2022-01-28T21:43:40.000Z",
  "eventType": "com.okta.telephony.provider",
  "eventTypeVersion": "1.0",
  "contentType": "application/json",
  "cloudEventVersion": "0.1",
  "source": "https://${yourOktaDomain}/api/v1/inlineHooks/calz6lVQA77AwFeEe0g3",
  "requestType": "com.okta.user.telephony.pre-enrollment",
  "data": {
    "context": {
      "request": {
        "id": "reqRgSk8IBBRhuo0YdlEDTmUw",
        "method": "POST",
        "url": {
          "value": "/api/internal/v1/inlineHooks/com.okta.telephony.provider/generatePreview"
        },
        "ipAddress": "127.0.0.1"
      }
    },
    "userProfile": {
      "firstName": "test",
      "lastName": "user",
      "login": "[email protected]",
      "userId": "00uyxxSknGtK8022w0g3"
    },
    "messageProfile": {
      "msgTemplate": "Your code is 11111",
      "phoneNumber": "9876543210",
      "otpExpires": "2022-01-28T21:48:34.321Z",
      "deliveryChannel": "voice call",
      "otpCode": "11111",
      "locale": "en"
    }
  }
}

Request sent to Messaging based on Okta’s request

{
    "recipient": {
        "phone_number": "9876543210"
     },
    "channels": [
        {
            "channel": "voice"
        }
    ],
    "message": {
        "voice": {
            "template": "otp_voice",
            "parameters": {
                "otp_code": "11111",
                "language": "en"
            }
        }
    },
    "message_type": "OTP"
}

Okta telephony - Send SMS and voice using Messaging

📘
NOTE:

📘
NOTE:

Before you begin

🚧
CAUTION:

Steps

Request examples

SMS

Voice

Telesign Okta inline hook documentation

📘NOTE:

📘NOTE:

Before you begin

🚧CAUTION:

Steps

Request examples

SMS

Voice

Telesign Okta inline hook documentation

📘
NOTE:

📘
NOTE:

🚧
CAUTION: