This article provides a comprehensive guide to customizing routing workflows by using the Webex Contact Center HTTP Connector to call Webex Contact Center APIs. It covers a variety of essential topics, including the steps to create a native HTTP connector, configure HTTP request activities, execute GraphQL queries, and best practices for optimal use. By providing practical use cases and detailed instructions, this guide aims to empower flow developers to leverage the powerful capabilities of the Webex Contact Center Flow Designer for seamless API integration and custom logic orchestration.

anchorWhat is the Webex Contact Center HTTP Connector?

Previously, developers were required to maintain their own access tokens and refresh logic for invoking Webex CC APIs from the flow designer, now the native HTTP connector will manage the tokens behind the scenes. Flow developers can simply browse through the APIs on the developer portal and invoke them from the HTTP activity on the flow designer.

Connectors in Contact Center are an entity on Control Hub that enables an organization to make API calls from the flow designer. To make an API call, the following elements are required:

• Resource Domain (internally managed)
• Credentials (internally managed)
• API path
• Request Headers
• Request Body

The following diagram describes the HTTP connector flow:

Use Cases

The Webex Contact Center HTTP Connector can enhance your contact center workflows in several real-world scenarios. It allows for real-time customer data retrieval and support dynamic routing based on internal data. For example:

• Admin Workflows: Specific workflows can be established to allow administrators to make configuration changes, such as updating a menu or modifying business hours.
• Preferred Agent Routing/Last Agent Routing: Callers can specify their preferred agent, and the APIs can route the call to that particular agent.
• Journey Data-Based Call Routing: Caller information is stored as part of Journey Data Services. The JDS APIs can be used to store caller information or perform data lookups.
• CSAT/Rating-Based Routing: Routing logic can be customized based on the CSAT information of agents in a specific queue for premium customers.
• Least Handle Time Agent-Based Routing: Routing logic can be configured to direct calls to the agent with the least handle time for quick inquiries or premium customers.
• Least Wait Time Queue-Based Routing: Call flows can be directed to the queues with the shortest wait times.
• Least Handle Time Queue-Based Routing: Routing logic can be set up to direct calls to the queues with the least handle time.
• Externalizing Post-Call Data: Call-related information or metadata can be sent to an external system using the HTTP Activity in the event flow.

anchorPrerequisites

Before continuing, make sure you meet the following prerequisites:

• A Webex Contact Center organization on FLEX3 licenses.

In addition, the user setting up the connector should have one of these three roles:

• Full Administrator
• External Full Administrator
• Contact Center Service Administrator

anchorCreate a Native HTTP Connector

To create a Webex Contact Center HTTP connector:

1. Login to Webex Control Hub with your administrator account.
2. Navigate to Contact Center in the left hand nav and select Integrations, find the card labeled Webex Contact Center and select Set Up:
3. You’ll need to decide the access rights you want for the connector depending on your use case. Here are details on the form fields:
   • Name of the connector: Used as an identifier in the Flow Designer. Can be any alphanumeric string.
   • Access: Define the type of access to grant the tokens for this connector:
     • Read Only: Grants the ability to make GET API calls with the scopes: cjp_config``, and ``cjp_config_read.
     • Read-Write: Grants the ability to make GET, POST, PUT, UPDATE and DELETE API calls with the scopes: cjp_config``, ``cjp_config_read``, ``cjp_config_write``, and ``cjp_user.
   • Authorization: An admin must authorize this connector and grant permissions for the connector to read, write and modify data in the contact center solution. Select I authorize to authorize the connector. Select Add Connector when you’ve filled out the form:
4. You’ll receive a success message once the connector is created:

anchorCreate a HTTP Connect Flow

With the connector created, you’ll create a new flow using the Contact Center Flow Designer.

To create a new flow:

1. If you’re not already in Contact Center in Webex Control Hub, navigate to Contact Center and then select Flows in the left-hand nav. Choose Manage Flows and select Create Flows from the drop-down menu:
2. Enter a unique alphanumeric flow name and select Start Building Flow:
3. Once the flow canvas loads, find the HTTP Request activity in the left-hand palette, and drag and drop it onto the canvas:
4. Next, select the connection node on the right-hand side of the Start Flow activity and drag it to the left-hand connection node on the left side of your new HTTP Request activity to create a flow connection:
5. Select the HTTP Request activity and fill in the required information in the right-hand panel as described in the next section.

anchorConfigure the HTTP Request Activity

When the HTTP Request activity is placed on the right-hand panel, you’ll need to add the necessary values to make an outbound API call.

To determine the required values:

1. Navigate to the Webex Contact Center Developer Portal documentation site and login using your org administrator credentials.

2. From the API REFERENCE section in the left hand nav, choose the API you want to use for your HTTP request.

3. Gather the following information from the REST endpoint you’d like to use. In this example, we’re using the List Global Variables endpoint from the Global Variables API:

   1. The verb for the REST endpoint. In this case it’s GET.
   2. The request path for the endpoint. In this case it’s /organization/{orgid}/v2/cad-variable
   3. The orgid for your organization. Select Try Out and copy this from the orgid field in the Parameters section. You’ll add this in place of the {orgid} placeholder in the request path: /organization/3fa96685-e81e-468a-b70b-84111ec0b127/v2/cad-variable which is the value you’ll use in the HTTP Request activity.
   4. Any query parameters you’d like to use in the request. In this case, for example, page, pageSize, filter, etc.

4. Navigate back to Flow Designer and select the HTTP Request activity:

5. Fill in the HTTP Request activity’s form using the information you’ve gathered above: Use Authenticated Endpoint: Make sure to toggle this checkbox on for all CC API access.

   1. Connector: Select the connector you created above from the drop-down list.
   2. Request Path: Use the request path from the REST endpoint you selected above.
   3. Method: Choose the REST verb for the REST endpoint you selected above.
   4. Query Parameters: Add any query parameters you’d like to use from the REST endpoint you selected above.
   5. Content Type: Select Application/JSON from the drop-down list.
   6. Parse Settings: Get your HTTP response and save it to a variable by creating a flow variable (click on the canvas to create one). Use a JSON Path expression to find specific fields as needed. You can use the PlayMessage flow activity to play them back.

   

6. Drag an End Flow activity from the activity library to the flow canvas and connect it to the right-hand node of the HTTP Request activity.

7. Set the Validation toggle at the bottom right to On and select Publish Flow.

8. Continue to Test Your HTTP Connect Flow below.

anchorExecute a GraphQL Query

In addition to accessing any of the Contact Center REST APIs, you can also execute GraphQL queries.

To configure the HTTP Request activity to execute GraphQL queries:

1. Navigate to the Search API page in the Contact Center Developer Portal and choose Try Out and then Maximize Screen in the right-hand panel:
2. In the left-hand edit box of the GraphQL section, you can create and debug your GraphQL query:
3. Once your query is working the way you expect, convert it to a JSON string using any handy web tool or AI chat bot. Some tools don’t remove the Graph QL comments (#). Make sure your JSON string doesn’t have those. Note: You can find a variety of GraphQL examples in our GitHub repo: https://github.com/WebexSamples/webex-contact-center-api-samples/tree/main/reporting-samples.
4. Referring to the previous section, update the HTTP Response activity in your flow with the following values:
   1. Request Path: Set to /search.
   2. Method: Set to POST.
   3. Query Parameters: Add a query parameter with the key orgid and set the value to your organization ID.
   4. Content Type: Select Application/JSON from the drop-down list.
   5. Request Body: Paste in your GraphQL query that you’ve converted to a JSON string. Here is an example showing task IDs: { "query": "{ taskDetails ( from: 1719845438000 to: 1727794389000 ) { tasks { id } }}"}
5. Store the GraphQL response in a variable by selecting the background canvas of your flow to access the Global Flow Properties, scroll down to Variable Definition, select the Configuration tab and choose Add Flow Variable:
6. Enter the following information for the variable and then select Save:
   • Name: Choose an alphanumeric name for the variable.
   • Description: Fill out or leave blank.
   • Variable Type: Choose JSON from the drop-down list.
   • Default Value: Enter {}
7. Select the HTTP Response activity, scroll down to Content Type and choose JSON from the drop-down list, select Output Variable and choose your newly created variable, and enter $ in the Path Expression edit box:
8. Set the Validation toggle at the bottom right to On and select Publish Flow:
9. Continue to Test Your HTTP Connect Flow below.

anchorTest Your HTTP Connector Flow

To test your new HTTP Connector flow you can either play the variables content via Text To Speech or use the Debug mode:

1. Make sure you’ve saved and published your flow.
2. Select the Debug tab in the Flow Designer.
3. Call in to the entry point number associated with the flow, and scroll down to the HTTP Request activity to see the response:

Note: The Debug tab marks the execution of the HTTP activity as successful but does not provide the actual HTTP response code. For example, if the response code is returned as 500, the activity execution will still be marked as “success”.

Note: This debugging method is to be applied ONLY why creating and debugging the HTTP activity. Do not log responses by assigning a response body to a flow variable in a production application!

anchorBest Practices for using the HTTP Connector

When working with the HTTP Connector, keep the following points in mind:

• Always ensure that no sensitive response is stored in the flow logs. The flow designer encrypts the request and response body to ensure that no sensitive information is stored in the logs.
• The HTTP Connector is rate limited. All API calls originating from flow designer are rate limited based on the anticipated load. While we hope to service all requests, you may encounter 429 Too many requests.
• Ensure that ALL error codes are handled using a Case Activity for the error codes listed in the API definition. You can find the output variable, HTTP_Request.httpStatusCode, in the variable dropdown list.
• Learn more about common API errors here: (/docs/common-api-errors).
• You can optimize your flows by creating subflows with the HTTP Activity and Case/Condition Activity to ensure that all error cases are handled.
• If the API takes more than one second to execute, you can play music on wait by navigating to global settings in the right-hand panel.