Telephony inline hook reference

This page provides reference documentation for telephony inline hooks, one type of inline hook supported by Okta. It provides sample JSON objects that are contained in the outbound request from Okta to your external service, and sample JSON objects that you can include in your response.

About

The Okta telephony inline hook allows you to integrate your own custom code into several of Okta's flows that send SMS or Voice (CALL) messages. You can integrate this hook with enrollment, authentication, and recovery flows that involve the Phone authenticator. While the One-Time Passcode (OTP) is sent to the requester, Okta calls your external service to deliver the OTP, and your service can respond with commands that indicate success or failure in delivering the OTP.

You can have only one active telephony inline hook per org.

When you create a telephony inline hook, you must include the authScheme parameter. See Create inline hook and the authScheme object.

Objects in the request from Okta

For the telephony inline hook, the outbound call from Okta to your external service includes the following objects in its JSON payload:

requestType

OTP request or event for which this transaction is being requested: authentication, enrollment, recovery

Acceptable values for requestType

Enum Value	Associated Okta Event
`com.okta.user.telephony.pre-enrollment`	Enrollment
`com.okta.user.telephony.mfa-verification`	Authentication
`com.okta.user.telephony.account-unlock`	Account Unlock
`com.okta.user.telephony.password-reset`	Password Reset

data.userProfile

Provides information on the OTP requester

Property	Description	Data Type
firstName	First name of the OTP requester	String
lastName	Last name of the OTP requester	String
login	Okta sign in of the OTP requester	String
userId	Okta user ID of the OTP requester	String

data.messageProfile

Provides information on the properties of the message being sent to the OTP requester.

Property	Description	Data Type
msgTemplate	SMS message template. Not applicable for CALL.	String
phoneNumber	Phone number enrolled for the Phone authenticator by the OTP requester	String
otpExpires	Time when the OTP expires	String
deliveryChannel	OTP delivery method: SMS or CALL	String
otpCode	OTP code	String
locale	Location of the OTP requester	String

Objects in the response that you send

For the telephony inline hook, the commands and error objects that you can return in the JSON payload of your response are defined in the following sections.

Note: The size of your response payload must be less than 256 KB.

commands

The commands object is where you can provide commands to Okta. It is where you can tell Okta whether your attempt to send the OTP using your own telephony provider was successful.

The commands object is an array, allowing you to send multiple commands. In each array element, there needs to be a type property and value property. The value property is where you specify the status of your telephony transaction and other relevant transaction metadata.

The value property is itself a nested object in which you specify a status, provider, transaction ID, and transaction metadata.

Property	Description	Data Type
type	One of the supported commands	String
value	Result of the send OTP operation. It specifies whether the OTP was sent successfully by the external web service/provider.	value

Supported commands

The following commands are supported for a telephony inline hook:

Command	Description
com.okta.telephony.action	Telephony operation action result

value

The value object is where you specify the result of the send OTP operation.

Property	Description	Data Type
status	Whether the OTP was sent successfully using the customer's web service	status
provider	Provider that was used for sending the OTP using the customer's web service	String
transactionId	Transaction ID that uniquely identifies an attempt to deliver the OTP to the requester	String
transactionMetadata	Any relevant transaction metadata, such as duration	String

status

Status	Description
SUCCESSFUL	External web service was able to deliver the OTP to the requester.
PENDING	External web service wasn't able to confirm delivery of the OTP to the requester.
FAILED	External web service was unable to deliver the OTP to the requester.

error

When you return an error object, it should have the following structure:

Property	Description	Data Type
errorSummary	Human-readable summary of the error	String

Returning an error object causes Okta to retry sending the OTP to the requester using Okta's telephony provider(s).

Note: If the error object doesn't include a defined errorSummary property, the following default message is returned to the end user: The callback service returned an error.

Sample JSON payload of a request

{
  "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": "test.user@okta.com",
      "userId": "00uyxxSknGtK8022w0g3"
    },
    "messageProfile": {
      "msgTemplate": "(HOOK)Your code is 11111",
      "phoneNumber": "9876543210",
      "otpExpires": "2022-01-28T21:48:34.321Z",
      "deliveryChannel": "SMS",
      "otpCode": "11111",
      "locale": "EN-US"
    }
  }
}

Sample JSON payloads of responses

This section provides example JSON payloads for the supported operations.

Sample response for successful OTP delivery

{
  "commands":[
    {
      "type":"com.okta.telephony.action",
      "value":[
        {
          "status":"SUCCESSFUL",
          "provider":"VONAGE",
          "transactionId":"SM49a8ece2822d44e4adaccd7ed268f954",
          "transactionMetadata":"Duration=300ms"
        }
      ]
    }
  ]
}

Sample response for failed OTP delivery

{
  "error":{
    "errorSummary":"Failed to deliver SMS OTP to test.user@okta.com",
    "errorCauses":[
      {
        "errorSummary":"Provider could not deliver OTP",
        "reason":"The content of the message is not supported",
        "location":"South Africa"
      }
    ]
  }
}

Timeout behavior

After receiving the Okta request, if there is a response timeout, the Okta process flow proceeds with trying to send the OTP using Okta's telephony provider(s). See Troubleshooting.

Troubleshooting

This section covers what happens when a telephony inline hook flow fails either due to the external inline hook service returning an error object or not returning a successful response.

Note: Administrators can use the Okta System Log to view errors. See the Troubleshooting section in the inline hooks concept piece for more information on the events related to inline hooks that the Okta System Log captures.

When there is a communication failure with the external service, a timeout for example, the inline hook operation is skipped, and the OTP is delivered to the requester using Okta's telephony provider(s).

Who can see this error? Administrators
When the external service returns a response with any other HTTP status code besides 200, the inline hook operation is skipped, and the OTP is delivered to the requester using Okta's telephony provider(s).

Who can see this error? Administrators
When the external service returns an error object in the response, the telephony inline hook flow fails with no OTP delivered using the hook.

Who can see this error? Administrators, developers, and end users
When a hook response is malformed or couldn't be mapped to the expected API response, the inline hook operation is skipped.

Who can see this error? Administrators

The following actions result in an error:
- Using an invalid status in the response
- Attempting to add an active telephony inline hook when one already exists
- Not including the authScheme in the request header

Edit This Page On GitHub

On this page