Using Data from External APIs Containing Arrays
Note
If you are in Talkdesk Workspace, you can access Studio and all features described below by navigating to the Studio app. For more information, please refer to this article.
This use case describes the process of setting up a Studio Flow using the "Execute action" component with an action containing arrays. Here, the external API will return an array containing the customerâs name and VIP status, and we will use that information to route the call.
Setting up the Custom Integration

-
Create a custom integration. In our example, we will be creating a custom integration with Zendesk.
-
Then, create an action. To do it, go to the âIntegrations Managerâ page, select the newly created custom integration, and proceed to add the action.

- Give it a name and a description, and fill out the âURL Settingsâ fields. In this example, we want to get information from the CRM system about our customers: their name and their VIP status, so we will fill in the URL settings as shown above. The path parameter will be the phone number, which will be used to retrieve information. We will then name it âPhone numberâ and select the âStringâ type from the drop-down list.

- Since we will be making a data dip onto the CRM system, we need to define the output schema. For our example, we will use the schema shown here.
{
"$schema": "http://json-schema.org/draft-07/schema",
"type": "object",
"title": "Array schema",
"properties": {
"results": {
"type": "array",
"title": "Array response",
"items": {
"$schema": "http://json-schema.org/draft-07/schema",
"type": "object",
"title": "results",
"properties": {
"is_vip": {
"type": "boolean",
"title": "VIP customer"
},
"name": {
"type": "string",
"title": "name"
}
}
}
}
}
}
Setting up the Studio Flow

- Once that our custom integration and action are created, we will create a Studio inbound flow. In the initial step, we will define the phone number as a variable to be used in the current Studio flow.

- Then, we can add the âExecute actionâ component, which will allow us to make a data dip using the custom integration and action that we previously created.

- Fill in the Preferences tab of the "Execute action" component as detailed below:
- Select a custom integration - in this case, we select the one we previously created - âZendesk Integrationâ.
- Select an action - in this case, we also select the action we previously created - âGet from numberâ.
- Define the inputs - in this case, we will use the callerâs phone number.

- Since the output returns an array, we must select the âRaw responseâ option for the outputs. This will convert the whole response into a string variable (including the array field), that can later be parsed using the âRun functionâ component*. For that, we selected the âRaw responseâ option and then created a variable named âraw_responseâ.
Setting up the Studio Function
Note
Please be aware that to set up the Studio Function, you will need to use the Run Function component. If you wish to start using it, please get in touch with your CSM (Customer Success Manager).*

- To be able to use the âRun functionâ component, we need to create a Function. For this, we need to go to Admin > Studio > Functions > Create Function.

- Add a name and a description to your Function and fill in the âFunction propertiesâ section:
- âInputsâ: this will be the field that will be populated with the output from the âExecute Actionâ component. In our example, we will name the input as âraw_responseâ and set it as âStringâ.
- âOutputsâ: we will set up the information that we want to parse. In our example, we will parse the name and the customer VIP status - we will set the first output as âis_vipâ and set the type as âBooleanâ and after pressing Add output to add the second output, it will be set as ânameâ and its type will be âStringâ.

- Then, we will need to define the âFunction codeâ by writing the desired lines of code after the line that says âWrite your code belowâ. For our example, this is the code we will be using:

function zendesk_information_parser(args) {
// Your function inputs will be listed here
const { raw_response } = args;
// âŹď¸ Write your code below âŹď¸
let parsedResponse = JSON.parse(raw_response);
//getting the first element of the array
let firstElement = parsedResponse.array[0];
return {
name: firstElement.name,
is_vip: firstElement.is_vip
}
}
-
You can then test the function, by clicking on âTest Functionâ. When you do so, a modal appears, allowing you to insert a custom value to test your function. You can see the Functionâs result on the result box to the right side of the modal. We advise you to test your function with a real result (by selecting âCustom Valueâ on the dropdown), as well as other different scenarios to make sure that the expected behavior is retrieved successfully. After testing, you can now save and publish your Studio Function, so that you can start using it in your Studio Flow.
-
Go back to the Studio flow and proceed as follows:

- For the âExecute actionâ componentâs exit, we defined the âRun functionâ (which will parse information retrieved from the execute action component) for the OK exit. In our example, if a connection error occurs, the flow ends.

-
Add the âRun functionâ component and on âPreferencesâ, select the function that you have recently created and published.
-
In the âInputsâ, we will use the context variable that we defined in the âExecute actionâ component (raw_response). We just need to select it from the dropdown.

- As we want to use the values retrieved from the array, on the rest of the flow we will be creating variables for the âits_vipâ and ânameâ outputs. Click on the dropdown and select Create variable for each of the outputs. Give names to those variables (we used âis_vipâ and âcustomer_nameâ, respectively) and click on Create variable.

- Now, we need to define the exit variables for the âRun Functionâ component. For the âOKâ exit, we will select âConditional statementâ, which will allow routing the call based on the customerâs VIP status. For the âExecution errorâ exit, we will end the flow.

- We want for a VIP customer to be assigned to an agent, and non-VIP customers to go through a âStandard IVRâ. Now, in the âConditional statementâ componentâs exit, we need to define those rules. If the variable âits_vipâ is equal to âtrueâ, then the flow should follow through a âPlay audioâ component (to greet the customer, and thank them for being a VIP member), and an âAssignment and dialâ component so that the caller can speak to an agent. If not, then it should follow through a âStandard IVRâ.

- In the âPlay audioâ component, we can define a message to greet our VIP customer before directing the call to go through the âAssignment and dialâ component. In this message, we will be using text-to-speech and include the name of the customer that has been previously retrieved, through the use of the previously defined variable.

- We can then configure the âAssignment and dialâ component. We define the assignment type (in this example we use ring groups), define the settings regarding Agents to ring, as well as the priority (in this example, we attributed 1), and set the maximum waiting time to 10 seconds. For the exits, we want the flow to finish after the call. If the agent does not answer, the maximum waiting time is exceeded or if there is no match, then we will allow for our VIP caller to leave a voicemail.

- Before reaching the voicemail, our VIP customers will hear a brief audio message soliciting them to leave a voicemail. We will also use our customerâs name in this message.

- Then, we just need to configure the Voicemail component in order to finish the setup for the VIP Customer branch.

- As for the âStandard IVRâ that our non-VIP customers will go through, we will define two options: 01 for Sales and 02 for Support. In that sense, we will only have to define the IVR message and configure the respective exits. For this example, we will define all exits pointing towards the âEnd Flowâ. For the âInvalidâ exit, we will go through a âPlay audioâ component requesting the customer to insert a valid option and go back to the IVR menu.

- When you finish configuring the flow, it will have the same appearance as the one shown above.
Updated about 23 hours ago