Configure Okta Workflows for an external telephony provider

This task explains how to create a flow in Okta Workflows to send the one-time pass code (OTP) to your end users through the telephony provider of your choice. The flow looks like this upon creation:

Before you begin

• Review the Telephony documentation to understand regulatory requirements, toll fraud, and technical considerations.

• Set up Okta Workflows.
  • Set up a connection from the Okta org. See Authorize the Okta connector.
  • Set up a connection for the API Connector. See Authenticate with API Connector cards.
• Set up a telephony provider of your choice. Take note of this information:
  • Account SID
  • Auth token
  • Phone number
  • SMS message URL to send POST requests. For example, the Twilio URL is https://api.twilio.com/2010-04-01/Accounts/{yourtwilioaccountid}/Messages.json, where {yourtwilioaccountid} is your Twilio account ID.

Create a flow

1. In the Admin Console, go to WorkflowWorkflows console.
2. In the Workflows Console, click FlowsNew Flow.

You can now add cards to your new flow.

Create the API Endpoint event card

1. Click Add Event. Search for and select the Okta app for API Endpoint.
2. In the API Endpoint settings window, set the Security level to Secure with client token.
3. Leave the Client token field blank and click Close.
4. In the Body section, create the following fields. Click the dropdown menu for the field to change its type.

Field	Type
data	Object
> userProfile	Object
> > userId	Text
> messageProfile	Object
> > messageTemplate	Text
> > phoneNumber	Text
> > otp	Text
requestType	Text

Create a Compose function card

1. Click Add function. Search for and select the Compose function card.
2. In the card, enter the following text: To=phoneNumber&From={yourphonenumber}&Body=messageTemplate
3. To map the phoneNumber and messageTemplate fields, drag and drop these fields from the API Endpoint event card.
4. Replace {yourphonenumber} with your phone number, including the country code. This is the number that your telephony provider assigned to you.

Create a Construct function card

1. Click Add function. Search for and add the Object Construct function card.
2. In the card, add these input text fields: Accept and Content-Type.
3. Enter values in the fields:
   • Accept: application/json
   • Content-Type: application/x-www-form-urlencoded

Create an If Error function card

1. Click Add function. Search for and select the If Error function card.
2. Ensure that the If Error function card is in the Try mode.

Inside this card, create the following cards.

Create an API Connector card

1. Inside the + menu, click the cloud icon. Search for and select the API Connector card.
2. Select the Post type.
3. In the Post card, enter the SMS message URL for your telephony provider.
4. Drag and drop the Output field from the Construct function card to the Request Headers field.
5. Drag and drop the Output field from the Compose function card to the Request Body field.
6. In the Request Body, create the sid text field.

Create a Compose function card for success

1. Next to the Post card, inside the + menu, click the calculator icon. Search for and select the Compose function card.

2. In the card, enter the following code:

   Copy

   {
    "commands":[
      {
        "type":"com.okta.telephony.action",
        "value":[
          {
            "status":"SUCCESSFUL",
            "provider":"<YOURPROVIDER>",
            "transactionId":"sid"
          }
        ]
      }
    ]
   }

3. Replace <YOURPROVIDER> with the name of your telephony provider, for example Twilio.
4. Drag and drop the sid field from the Post card.
5. Click the dropdown menu for the Output field to rename it Success.
6. Click View outputs for the If Error card.
7. Create an output object field called Response.
8. Under this Response field, drag and drop the Success field from the Compose card.

Add error fields

1. In the If Error card, switch the Try mode to If Error mode.
2. In the Error output, create the following fields. Click the dropdown menu for the field to change its type.

Field	Type
body	Object
> code	Text
> status	Text
> message	Text

Create a Compose function card for error

1. Next to the Error output fields, inside the + menu, click the calculator icon. Search for and select the Compose function card.

2. In the card, enter the following code:

   Copy

   {
     "error":{
       "errorSummary":"Failed to deliver SMS to phoneNumber",
       "errorCauses":[
         {
           "errorSummary":"Couldn't deliver OTP",
           "reason":"message"
         }
       ]
     }
   }

3. Drag and drop the phoneNumber field from the API Endpoint event card.
4. Drag and drop the message field from the Error output.
5. Click the dropdown menu for the Output field to rename it Error.
6. Drag and drop the Error field under the Response section of the If Error card.

The card in the If Error mode looks like this:

The If Error function card is now complete.

Create a Return Raw card

1. In the flow, click Add function. Search for and select the Return Raw function card.

2. Drag and drop the Output field from the Construct card to the Headers field.

3. Drag and drop the Response field of the If Error card to the Body field.

4. Save the flow and turn it on.

Copy information for telephony inline hook

1. Go to the API Endpoint event card, and then click the </> icon to open the API Endpoint settings.
2. From the settings dialog, copy the following information: Invoke URL, Alias, and Client Token.

You need this information in the next step when creating a telephony inline hook.

Next step

Connect to an external telephony service provider