Using Studio API Flows to Forward Calls to External Numbers

A Studio flow can be triggered from an external system via an API request.

Through this API request, an automatic outbound call can be initiated when a pre-specified condition is met. This way, you can easily dial clients to notify them of a specific event and forward those calls to an external phone.

Follow the steps below to create a Studio API-triggered flow that enables you to forward calls to external numbers.

Configuring an API Flow

1. Click Create flow on the Flow Manager page and on the new window that is displayed.
2. Select Empty flow [1], followed by Next [2].

3. Choose API request [3] and then Next [4].
4. On the next screen, enter a name and, if necessary, a description of the flow.

The flow editor page will be displayed, and you will see the API request component as the flow initiator. Within it, you will need to configure the input arguments, i.e., the data to be sent in the body of the POST API request that will trigger the Studio flow. Each argument can be mapped to a variable that can then be used in the flow.

In our example, a customer reports a problem with a home service installation through the provider’s website by clicking on a button. This action will trigger an automated outbound call from the provider to the customer, thus enabling the customer to speak with an agent through its external phone.

We have configured the arguments and variables in the following manner:

5. Fill in the first text box with the "Argument name" - “contact_1” that represents the customer’s number [5].
6. Create the corresponding variable that will map the customer phone number information - “contact_1” [6].
7. Repeat the process and click Add new argument [7] to fill in the remaining arguments and variables with the information that represents the second contact, which in our example, would be the agent’s phone number.
8. If necessary, create a variable (Preferences tab) to populate the interaction_id field, under the “Variables” section.
9. Go to the Exits tab and add the "Make outbound call" component. This is the component that enables the outbound call to be executed and the customer to be dialed.

📘

Note

There is a set usage limit of one “Make outbound call” component per call path.

10. In “Outbound call number”, select a source phone number from the list, from which the trigger will be executed [8]. The available phone numbers correspond to those previously added to your Talkdesk account under Admin > Numbers.
11. Select the destination number variable [9], which, in our example, corresponds to the variable we have configured in the API Request component - “contact_1”. This variable will retrieve the phone number information within the body of the API request.
12. Define the maximum time that the call will ring on your contact person’s phone, from 10 (minimum) to 35 seconds (maximum) [10], with 15 seconds being the default time range.

13. On the Exits tab, define the following mandatory exits [11]:

• “Answered”: The component will use this exit if the customer answers the call. This voice notification is played to the customer at this point, so we recommend using a voice component for this exit. In our example, the call will be directed to a “Play Audio” component, which we’ve named “Announce agent joining call”.

• “Invalid number”: Select a component that will be executed in case the destination number is invalid. In our example, we’ve decided to use the “End flow” component, which will terminate the call if the call made through our API request cannot reach the destination phone number.

• “Busy”: This exit will be used by the system if the customer’s phone line is busy or if the customer rejects the call. In our example, the call will be directed to the “End flow” component and will be hung up, but you can decide to use a different configuration.

• “No Answer”: This exit will be used to direct the call to a component of your choice in case the number was dialed, but the contact person did not pick up. We’ve decided to add the “End flow” component if, after the maximum ringing time defined before, in step 11, the call was not picked up.

14. Select the “Play Audio” component and then choose the method by which the audio message will be played to the customer when the call is answered [12]. Configure the remaining options accordingly. We have selected the Text-to-speech source and configured the following message, as an example:
    Thank you for reaching out to us. Your call will be redirected to the agent responsible for your installation.

15. On the Exits tab, select the Forward to External Number component. We’ve named ours “Call agent via external number”. Through this step, the call will be forwarded to an agent, in case, for instance, the customer needs to speak to an agent to schedule a new intervention for repair or a new installation.

16. On the Forward to External Number component, select “Contact number” if you wish the number to be displayed during the outbound call as the phone number of the person who made the call, or “Touchpoint” if you wish to have the company’s phone number showing up.

17. Define whether you wish to manually configure the external number or if you wish to use a variable that has been previously added to the flow. In our example, we’ve selected the latter, “contact_2”, i.e., the agent’s phone number.

18. Go to the Exits tab and define where to route the call in case of “No answer”, and “Invalid Number”. In our example, we’ve decided to end the flow.

19. Save and publish your flow.

Configuring the API request

1. When you have finished configuring your flow, return to the Flow Manager page and click on the Request details [1] button of the flow you’ve just created.

2. A side panel containing relevant information for you to build the API request on your API development tool will be displayed.

3. In addition, check the instructions provided on this page in order to obtain all the necessary details about how to build the API request.

📘

Notes

• Through Talkdesk Builder™ it is possible to create an OAuth Client to get access to the Flows API. The scope for the Flow API, which starts an interaction that executes the published version of a given Studio flow, is flows-interactions:start. For more information about scopes, please refer to this article.
• String input arguments are the sole data types that are currently supported. On your specific API request, the values will need to be replaced by the actual values to be sent in the request body.

Components Supported in API Flows

📘

Note

Each of the Voice components can only be placed on a point of the flow where a call exists, due to the fact that there must be a transition between a “Make outbound call” component’s “Answered” exit and one of those voice components.

Additional Specifications

• Flows API limit: There is a limit of two API requests per second (rps), per account.

• “Make outbound call” component reporting and automations: Apart from the “Studio Flow Execution Report”, there will be no reporting and no automations on automatic agentless outbound calls regarding these flows.