Configure and use telephony

You can configure SMS messages or voice calls as part of authentication policies or account recovery. This topic describes how to enable SMS messages or voice calls, customize SMS messages, and monitor use using the System Log and reports.

If you're configuring telephony for the first time for your org, you must first set up an external telephony service provider. See Connect to an external telephony service provider.

Using phone OTP isn't a guaranteed way to verify a user's identity. See Potential risks of verifying identity through SMS and voice call.

Okta recommends that you require users to authenticate using a more robust authenticator. For example, an authenticator that not only verifies the user presence but is also device-bound, hardware-protected, or phishing-resistant. Such authenticators include authenticator apps, email magic links, or FIDO2 (WebAuthn). See Multifactor authentication.

Enable SMS messages or voice for account recovery

The default password policy enables Okta users to reset their account password or unlock their account using an email link. You can modify this policy to enable users to receive an SMS messages or a voice call to reset their password or unlock their account. Okta recommends adding another password policy to the same effect and place it at a higher priority.

For information about adding a password authenticator with a default policy rule, see Configure the password authenticator.

Configure SMS messages or voice for multifactor authentication

You can configure a phone as an authenticator to use a one-time passcode (OTP) for multifactor authentication, device enrollment, and account recovery. You can choose to enable OTP only through SMS messages or voice calls, or both.

You can't use toll-free, premium, and invalid phone numbers for multifactor authentication or device enrollment. If you attempt to use a toll-free, premium, or unrecognized phone number format, the phone number is rejected as an invalid phone number.

Costs and availability

When SMS messages or voice calls are used for account recovery, the costs can vary widely depending on the telecommunication services available in the countries where the calls are placed.

Service protection and reliability

If you enable SMS messages for multifactor authentication, users authenticate by entering a security token that is sent to their mobile device. The sender ID or phone number that appears on the devices can be a short code, a long code, or a toll free number. The sender ID can change without notice to ensure service protection and might change from one sign-in attempt to another. Changes to the sender ID allow Okta to maintain service reliability, adjust the routing of messages to telecommunication providers, and provide a more consistent delivery rate for different destinations.

Customize SMS messages templates

You can customize the SMS messages by modifying the default message template or by localizing the message. In addition, some countries require that the SMS messages include branding information or comply with specific regulatory requirements. See Customize an SMS message.

Before you customize the default SMS messages template, consider the following items:

The languages you need to support
The character set required for the languages that you support
The maximum number of characters allowed for a single SMS messages

Character set limitations

Most telecommunication providers encode SMS messages using the GSM-7 character set. The GSM-7 character set supports the most commonly used letters and symbols in many languages that use the Latin-based alphabet, such as English, Spanish, and French. Because the SMS messages is transmitted 140 8-bit octets at a time, messages that are encoded using the GSM-7 character set can contain a maximum of 160 characters. If a message can't be encoded using the GSM-7 character set, it's typically encoded using UCS-2. Examples include messages in a non-Latin-based alphabet language such as Arabic, Chinese, or Cyrillic. With UCS-2 encoding, the maximum message length is 70 characters.

Message segments and delivery

Okta supports sending SMS messages that use GSM and non-GSM characters. The character set determines the maximum number of characters per message. It also determines how messages are broken down into segments and delivered.

The character limit for a single SMS message segment is 160 characters for the standard GSM character set. Messages exceeding the limit are split into segments with a maximum of 153 characters each. The segments are sent individually and then assembled by the recipient endpoint. If your message consists of 161 characters, it's sent as two separate messages. The first message contains 153 characters and the second contains 8 characters. As a results, it's counted as two 160-character messages.

Similarly, messages with non-GSM characters are limited to 70 characters per segment. Only few mobile carriers support concatenation of non-GSM characters. Messages exceeding the limit are split into segments with a maximum of 67 characters each.

Validation for custom message templates

For a customized SMS message template, Okta checks the message to determine whether it contains GSM or non-GSM characters and enforces the corresponding character limit before saving it. This check ensures that your custom SMS messages follow the character limit for message segments.

The character set validation isn't performed for custom SMS message templates that you might have previously created. However, if you change existing custom templates, the new restrictions are enforced if your messages contain non-GSM characters.

If you have existing SMS message templates that you aren't planning to update, it can be difficult to determine whether they contain non-GSM characters. Try entering such texts in an online tool that can evaluate the characters used.

View or query SMS messages or voice call events

You can use the System Log to view or query for SMS messages or voice call events.

For example, you can use the System Log to view details about when an SMS message was sent to verify a phone as an authenticator or if verification was successful:

You can expand these events to view more details about the activity. For example, if an SMS message was successfully delivered to its destination, you can see details similar to the following:

You can also use the System Log to filter and query for a specific provider status. For example:

There are several scenarios that can cause SMS messages or voice calls to fail.

For example, authentication requests might fail for any of the following reasons:

A telephony provider can't be reached
The phone number used is incorrect or inactive
The service requested isn't available in the country where the request was made
A request for verification has timed out
A number is blocked because of suspicious activity

SMS event types

The System Log records the following events for SMS messages:

Event	Description
system.sms.receive_status	Recorded when a status update for an SMS message has been received from a service provider. You can use this event to identify users who aren't getting one-time passcodes delivered successfully. For any system.sms.send_* event, there should be exactly one corresponding system.sms.receive_status event.
system.sms.send_account_unlock_message	Recorded when a self-service account unlock SMS message has been sent.
system.sms.send_factor_verify_message	Recorded when a second factor authentication has been sent as an SMS message.
system.sms.send_okta_push_verify_message	Recorded when a request to activate Okta Verify Push for mobile SMS message has been sent.
system.sms.send_password_reset_message	Recorded when a self-service password reset SMS message has been sent.
system.sms.send_phone_verification_message	Recorded when a phone verification SMS message has been sent.

For additional information about the System Log API and SMS event types, see Event Types in the Okta developer documentation and type sms in the search field.

Voice event types

The System Log records the following events for voice messages:

Event	Description
system.voice.receive_status	Recorded when a status update for a voice message has been received from a service provider. You can use this event to identify users who aren't getting one-time passcodes delivered successfully. For any system.voice.send_* event, there should be exactly one corresponding system.voice.receive_status event.
system.voice.send_account_unlock_call	Recorded when a self-service account unlock voice call has been sent.
system.voice.send_call	Recorded when a voice call has been sent.
system.voice.send_mfa_challenge_call	Recorded when a second factor authentication has been sent as a voice call.
system.voice.send_password_reset_call	Recorded when a voice call for self-service password reset has been sent.
system.voice.send_phone_verification_call	Recorded when a voice call for phone verification has been sent.

For additional information about the System Log API and voice event types, see Event Types in the Okta developer documentation and type voice in the search field.

View the Telephony usage report

You can see details about the domestic and international SMS messages sent in a month for users in your organization. Use this report to identify patterns of user behavior and whether the SMS message is for enrollment, sign-in requests, password resets, or unlocking accounts.

Select a language for voice-based authentication

Individual users can select the language used for the voice message they receive to verify their identity. To select a language, users click Settings in the End-User Dashboard. After they click Edit Profile to validate their credentials, they can edit the Display Language setting to select the language used for voice-based authentication and recovery. If they authenticate using a phone call after changing the language setting, they hear the voice message in their selected language.

For more information about modifying user settings, see End-user settings or direct your user community to Select your display language.