Customize your telephony service provider

By default, Okta routes telephony work flows to a predetermined service provider. However, you can customize the telephony service provider for your organization by using a telephony inline hook.

If you configure a telephony inline hook, you can use a telephony service provider of your choice for all work flows that send SMS text messages or voice calls except Okta Verify enrollment. For example, you can create a telephony inline hook to connect to the telecommunication provider you want to use when end users or customers request a One-Time Passcode (OTP) to be sent as an SMS text message.

Connect to an external service

With a telephony inline hook, you can set up an external web service to connect to your telephony service provider for enrollment, authentication, and recovery work flows that involve the phone as an authenticator. For example, if a user requests a One-Time Passcode as part of multifactor authentication, Okta uses the external web service to connect to your service provider to make the request on the user’s behalf. The service provider delivers the OTP to the requester’s device and the external web service responds to Okta with messages that indicate whether the delivery of the OTP succeeded or failed.

Each organization can only have one active telephony inline hook at any given time. However, logic in the external web service can direct requests to different telephony providers based on conditions you specify. For example, you might send the request to different telephony providers based on the country where the request originates. Similarly, your custom code might include error handling to send requests to a secondary telephony provider if your primary telephony provider fails to deliver messages.

Before you add the inline hook, you must create the external web service that defines the JSON objects for the request and the response from the telephony provider of your choice. You can find the reference documentation for creating the request and response JSON objects web in Telephony Inline Hook Reference. After you prepare the external web service request and response JSON objects for the telephony provider you want to use, you can add and manage the Telephony Inline Hook through the Admin Console.

For a general introduction to Okta inline hooks, see Inline hooks. For information about the API for registering external service endpoints with Okta, see Inline Hooks Management API.

Add a Telephony Inline Hook

After you configure your external telephony service, connect it with Okta by adding a telephony inline hook:

In the Admin Console, go to Workflow > Inline Hooks.
Click Add Inline Hook, and then select Telephony.
Type a descriptive name for the telephony provider inline hook.
Add the external service URL, including the endpoint that sends the one-time passcode (OTP) to end-user devices.
Optional. Specify a value for the Authentication field header field.
Optional. Specify a value for the Authentication secret header field.

The external service should use the authentication secret to validate that the request is an Okta request for service.
Click Save to make the inline hook active.

Preview the request and response

After you configure the telephony hook for your service provider, you can test its operation using the Preview action.

To test your connection to the telephony service provider:

In the Admin Console, go to Workflow > Inline Hooks.
Identify the Active telephony inline hook.
Click Actions, and then select Preview.
Select a user profile for a user with a phone as a valid authenticator.
Select the event that results in an SMS text message or voice call you want to test.

For example, select one of the following event actions:
- MFA enrollment
- MFA verification
- Account unlock
- Password reset
Click Generate request to generate the HTTP request to send to your telephony provider.

Optionally, you can edit the generated request by clicking Edit. For example, you might want to edit the profile to send a text message to a phone number that you use for testing purposes.
Click View response to view the response from your service provider.

View metrics for your telephony provider

Okta provides basic metrics to help you monitor how well your telephone service provider is performing. The metrics track the total number of times a hook is executed for a 30-day period, and indicate the number of successful executions, the number of unsuccessful executions, and the average execution time for successful executions.

To view metrics for you telephony service provider:

In the Admin Console, go to Workflow > Inline Hooks.
Identify the telephony inline hook that is currently Active.
Click Actions, then select Metrics.

Deactivate a telephony provider

You can only have one active telephony service provider for an organization. However, you can configure multiple inline hooks for different telephony providers, then change between them by deactivating one and activating another. For example, if you have two providers available but the currently active provider is experiencing service delays, you might switch to your secondary provider.

To deactivate a telephony service provider: