← Lab 10 | Index | Lab 12 →

Lab 11 - Let's go

Last modified: Mon, 19 Jun 2023

Table of Contents

Introduction

Important: Changes to the API Lab.

• The New Webex Contact Center APIs are now available on developer.webex-cx.com and use OAuth2 as opposed to One-time API Keys.
• The Legacy APIs (v1) are still available and are documented in the later section of this lab.
• The lab assumes that you will use the All New Webex Contact Center APIs which are documented below.
• For a quick start and overview, refer to the Overview / Quick start section.

All New Webex Contact Center APIs (New Version)

Introduction to the New Webex CC APIs

This is the introduction video. It explains what API we have, what application and authorization mechanisms exist and how to get started.

📺 Introduction Video

1. Walkthrough of Auth Flow

• To develop applications with the new APIs, you must build an integration with Webex.
• See Contact Center Dev Portal Docs for all the details.

Here is a summary:

API Access — create an Integration

• The New Webex Contact Center APIs are accessed by using Webex OAuth2
• Watch this video to create an integration and run APIs on Postman.
• Steps to create an integration and use on Postman
• OAuth2 by design, requires a client_id, client_secret, callback URL (Redirect URL)
• Use the Client ID, Client Secret, Redirect URI (callback URL) to obtain access_token for your Org. Use the Access token to hit the API inside of the Authorization header:

Authorization: Bearer yourAccessToken

• Use the refresh_token before it expires to renew your access_token — and get a new set of Access and Refresh Tokens.

By default, the access_token is valid for 12 hours and the refresh token is valid for 60 days. However, using another call for the refresh token will give you a new set of tokens. Maintaining this access is important for perpetual access. One can write a simple scheduler that performs this background refresh activity.

OAuth2 Mechanism — Implications

• With the OAuth2 support — will require a "One Time Onboarding" User interface to obtain access to an org
• "Login with Webex" > Button to access an org
• You will register an App with us and use it for N orgs
• Have each Org administrator login into your App at least once to obtain the tokens
• This is a "Required Onboarding" Process
• Once you obtain an Org's access_token and refresh_token, you can access their data

OAuth2 Access Token Flow

• Your App redirects to authorize with Webex (GET):

GET https://webexapis.com/v1/authorize?client_id=______&response_type=code&redirect_uri=https://your-app/auth&scope=cjp:config_read&state=set_state_here

• Admin user completes login. Redirect back to your App (GET):

GET https://your-app/auth?code=___unique_code_sent

• Your App uses this code — API Endpoint — and then sends a POST request back to Webex
• Request Access Token AND/OR Refresh Tokens (POST):

POST https://webexapis.com/v1/access_token
Content-Type: application/x-www-form-urlencoded

Example response:

{
  "access_token": "ZDI3MGEyYzQtNmFlNS00NDNhLWFlNzAtZGVjNjE0MGU1OGZmZWNmZDEwN2ItYTU3",
  "expires_in": 1209600,
  "refresh_token": "MDEyMzQ1Njc4OTAxMjM0NTY3ODkwMTIzNDU2Nzg5MDEyMzQ1Njc4OTEyMzQ1Njc4",
  "refresh_token_expires_in": 7776000
}

Expiry in seconds. Required x-www-form-urlencoded values include:

• grant_type = authorization_code OR refresh_token
• client_id
• client_secret
• code
• redirect_uri

2. Initial Setup of Sample App

• Login with the POD admin account to https://developer.webex-cx.com/
• Go to Documentation > API Reference
• Follow the instructions in the video to request access to your sample app.
• The sample app is available here: https://github.com/CiscoDevNet/webex-contact-center-api-samples/tree/main/app-auth-sample
• Follow the instructions in the video to clone the repository and run the app.

Reporting APIs

In this video we will go through the developer portal and execute your first API calls through Postman.

📺 Reporting APIs Video

• Login with the POD admin account to https://developer.webex-cx.com/
• Go to Documentation > API Reference

1. Executing "Get Tasks" API

• Go to the Tasks section
• Click on GET Tasks > Try Out
• Fetch all the tasks using the "From Date/time" in Epoch milliseconds.
• To get the Epoch time use epochconverter
• Enter the Org ID and channel type > Press Run

The same request can be drafted on Postman using your personal Bearer Token.

Example of a GET Task: https://api.wxcc-us1.cisco.com/v1/tasks

• Create a new collection in Postman
• Under that add a request
• Enter the request URL copied from the developer portal. Make changes to the from and to times and the org ID to reflect your tenant.
• Under Headers enter the Key: Authorization and Value: Bearer <Your Bearer token copied from the developer portal>
• Under Parameters enter the values you will be passing as shown in the video
• Click on Send

2. Executing "Get Queue Statistics" API

• Go to the Queues section
• Click on Get Queue Statistics > Try Out
• Enter the from date, to date and the interval
• Click on Run

To try this out in Postman follow the steps outlined in the previous example.

3. Executing "Get Agent Activities" API

• Go to the Agents section
• Click on Get Agent Activities > Try Out
• Enter the required parameters as explained in the video. Click on Run

To try this out in Postman follow the steps outlined in the previous example.

4. Executing "Get Agent Statistics" API

• Go to the Agents section
• Click on Get Agent Statistics > Try Out
• Enter the required parameters as explained in the video. Click on Run

To try this out in Postman follow the steps outlined in the previous example.

Call Recording APIs

In this video we will concentrate on "Captures" API. Captures are audio recordings that can be downloaded through API.

📺 Call Recording APIs Video

Working with "List Captures" API

• Run the Get Tasks API as explained in the video and get the required task IDs
• Go to Captures section
• Click on List Captures > Try Out
• Enter the parameters: orgid, taskids, urlexpiration
• Click on Run
• Use the Filepath in the response to download and listen to the recording
• Enter the required parameters as explained in the video. Click on Run

To try this out in Postman follow the steps outlined in the previous example.

Configuration APIs

This is the bonus section of New WxCC APIs where you will be able to create/change settings in the Webex Contact Center by using the Configuration APIs.

📺 Configuration APIs Video

1. Creating a Site with "Create Sites" API

• Go to Sites section
• Click on Create Sites > Try Out
• Enter the parameters: active, orgid, multimediaprofileid, name
• Click on Run

To try this out in Postman follow the steps outlined in the previous example.

2. Changing the Site name with "Update Site By ID" API

• Go to Sites section
• Click on Update Site by ID > Try Out
• Enter the parameters orgid and the id (the site ID that was created in the previous exercise)
• In the request body update the orgid, id, multimediaprofileid, name
• Click on Run

To try this out in Postman follow the steps outlined in the previous example.

3. Practicing with Bulk Upload

Follow the instructions in the video to use Postman and create multiple sites using a CSV file.

Search API

📺 Search API Video

1. Search endpoint in developer portal

• Go to Search endpoint on Developer Portal
• Click on Try out → Expand try out window by clicking box icon on right hand side top section.

2. Forming a GraphQL query

• In the interactive editor paste the query from GitHub sample link
• NOTE: To and From should be changed according to your needs, it has to be epoch time in milliseconds. Use this link to convert.

3. Running the query

• Click on run — notice that you will receive all the interaction IDs between that timeframe.
• Run the query https://github.com/CiscoDevNet/webex-contact-center-api-samples/blob/main/reporting-samples/graphql-sample/totalCallsByAni.graphql to aggregate calls from a specific phone number.
• NOTE: Change the line 11 to the ANI from your tenant.
• Refer to docs section as shown in video to find explanation for each field in the schema.
• You can also run all the GraphQL samples here

NOTE: Change filters and aggregation values according to your tenant.

Agent Desktop APIs

📺 Agent Desktop APIs Video

1. Useful links

• Web socket subscription API
• Login
• Logout
• Reload
• State change

2. Importing Postman collection and setting up OAuth2

• As shown in the video Import the desktop postman collection.
• Postman → Import → Raw Text → Continue
• Setup OAuth2 connection on postman collection as mentioned in section 1

3. Establish a WebSocket connection

• Establish a web socket connection from postman as shown in this video
• Collection → Agent → Register Web socket Subscription.
• Run the request. A WebSocket URL will be generated.
• Copy the web socket notification URL received in the above step.
• On Postman, click on New → WebSocket Request → Paste the URL → Click Connect.
• At this point a WebSocket will be established successfully.

4. Login an agent

• Collection → Agent → Station login.
• Change the request body as mentioned in this document
• Click on Send.
• Agent will be successfully logged in and will be in idle state.
• Click on web socket established in step 3 and notice that an event is received on web socket for successful login.

5. Change state of an agent

• Collection → Agent → Change state.
• Change the request body as mentioned in this (To available) document
• Click on Send.
• Agent state will be successfully changed to Available.
• Click on web socket established in step 3 and notice that an event is received on web socket for successful state change.

6. Reload an agent

• Collection → Agent → Reload Agent.
• Reload API documentation
• Click on Send.
• Agent state data will be successfully received on web socket. This will include the config details as well as task agent is handling.
• Click on web socket established in step 3 and notice that an event is received on web socket for successful agent reload.

7. Logout an agent

• Collection → tasks → Logout Task.
• Change the request body as in this document
• Click on Send.
• Agent will be successfully logged out.
• Click on web socket established in step 3 and notice that an event is received on web socket for successful agent reload.

Quick Reference: Key URLs

Congratulations, you have completed this lab! You can continue with the next one.

→ Lab 12 - Digital Channels