We recommend reading through the Getting Started article before you plan your integration. After you have created an integration plan, read the steps below to get started with the Cyara 3.0 API.
The Cyara 3.0 API is built to allow integrations to the Cyara platform. Once you have generated your authentication key, you can test out API routes with the Swagger API platform. You can use the Swagger platform to make changes to your live Cyara Platform.
Swagger is the platform where we have documented each of the Cyara 3.0 API routes. Each route is grouped by which section of the Cyara platform it is related to and labelled with the type of route (GET, PUT, POST, DELETE). Swagger allows you to test pre-formatted API routes.
API calls will send data and receive results in JSON formatted content. Swagger will supply samples of the JSON content so that content parsing code is easier to construct.
Accessing Cyara REST API through Swagger UI
Swagger utilizes a prefix called “Base URL” as part of every API call issued. The base URL references the specific Cyara Portal against which the API calls are to be executed.
For example, use the base URL https://cyaraportal.us/cyarawebapi if you have an account on the Cyara US Portal.
If you are using one of the other Portals that Cyara provides, you must change the URL to reflect the Portal you are utilizing.
The API examples in this document references the Base URL by using the <baseURL> syntax.
Authorizing API Requests
The API credentials must be embedded within the site. You can do this through the Swagger home page.
To authorize an API route with swagger, do the following:
Before you begin
You must have the authorization key, which is a combination of the API key and your unique access key. For information about authentication, see Authentication.
Procedure
- Login to Swagger with the following URL (replace <YourCyaraPortalURL> your portal URL) : http://<YourCyaraPortalURL>/cyarawebapi
For example, use the base URL https://cyaraportal.us/cyarawebapi if you have an account on the Cyara US Portal. - Click Authorize in the top right corner.
- In the Available authorizations screen, specify the authorization key in the Value field and click Authorize.
The authorization credentials are stored on the Swagger site. - Click Close to return to the Swagger home page.
Now you can use the Swagger site to execute the APIs against the Cyara account where the user has access.
Testing an API Route with Swagger
To test an API route with swagger, do the following:
Procedure
- Login to Swagger using the base URL of your Cyara portal.
For example, the base URL of the Cyara US portal is: https://cyaraportal.us/cyarawebapi
- Click the Authorize button in the top right corner and paste the access token copied from the Cyara Portal.
For more information about access tokens, see Authentication.
- Click any functional area from the menu to list all the available endpoints for that functional area.
For example, click Accounts from the list of functions to open a list of all available API endpoints with Accounts.
- To execute a specific API endpoint, expand the API call in the list to view all the parameters that can be a part of the API call. Click Try It Out and specify the API parameters as required, then click Execute.
The Responses section is updated with the Curl request and the server response.
This allows developers to see the complete content of the API endpoint as well as the complete results from executing the endpoint.
Check out our Example Integrations page for some use-case examples on how to get the most out of the Cyara 3.0 API.
Constructing your API Request
The following examples show how to construct the URL for an endpoint.
Example: List all accessible accounts
Request URL: <baseURL>/v3.0/accounts
This call returns a list of all the accounts available for the authorization supplied. This is especially important when using an “entity” user’s credentials that are shared by many developers. Accidental re-generation of the entity’s token is not an uncommon event when new staff are joining the automation effort.
Example: Get voice settings for an account
Request URL: <baseURL>/v3.0/accounts/{accountId}/voice
This call retrieves the voice settings for a specific account. Effectively, it is a subset of the account settings reflecting just the voice settings. Maximum CAPS rate and the default settings for test case steps is important information to know when creating campaigns
Example: Get list of plans within an account
Request URL: <baseURL>/v3.0/accounts/{accountId}/plans
This call returns the list of plans that have been created for the account. Plans are how different media types and capacities are configured for an account. Creating campaigns using an API requires that you associate the campaign to a configured plan for the campaign to run.
The resulting list can be filtered by including the following sort command at the end of the API call: ?channel={field name}
The valid channel field names include: None, Voice, Web, AgentVoice, AgentChat, AgentDesktop, Email & sms.
The resulting list can also be filtered by plan type by including the following filter command at the end of the API call: ?plan={field name}
The valid plan field names include: Pulse, Cruncher, Replay, VirtualAgent, CruncherLite, Outbound, PulseOutbound & Velocity.
There are sort options and page size options available as well. Standard syntax for including multiple options in a single API call: ? for the initial option and & between subsequent options.
Example: Get the plan details
Request URL: <baseURL>/v3.0/accounts/{accountId}/plans/{planId}
This call returns a detailed list of the attributes for the specified plan. There are two items of specific interest: concurrency and maximumAps.
Concurrency is the number of ports of a given type assigned to the Plan. If, for example, the number is 8, then no campaign can use more than 8 ports; they can use less but cannot use more than the maximum of 8. The maximumAps is the CAPS rate which sets the limit for how quickly calls are placed into the target system.
This call is primarily needed to secure the concurrency number which is vital for creating campaigns. It is also important to know the concurrency number if you are looking to build a campaign queuing system. Launching campaigns needing more ports than are available in the overall plan will produce the same error as launching campaigns in parallel to other campaigns that are already using all the available ports.
Example: Get list of folders for an account
Request URL: <baseURL>/v3.0/accounts/{accountId}/directories/{type}/folders
This call returns the list of folders that are associated with the specified account. The folder types include TestCase, Block, Audio, Campaign, CrawlerModel, Service, CxModel, and Script. Each folder in the list will include the folderId that is used to generate content lists for a specific folder.
It is important to know the names of folders within an account so that the folders themselves can be searched when looking for specific test cases to execute or add to a campaign. It is recommended that you build an array to hold the folder name and the associated folderId for subsequent searches within a specific folder.
Example: Get list of contents within a folders
Request URL: <baseURL>/v3.0/accounts/{accountId}/directories/{type}/folders/{folderId}
This call returns the list of content within the specified folder as identified by the folder type. The valid content types include TestCase, Block, Audio, Campaign, CrawlerModel, Service, CxModel, and Script. Each item listed includes the unique ID that identifies the specific item. In the case of a Test Case, the unique ID is the testCaseId.
The resulting list can be sorted by including the following sort command at the end of the API call: ?sortField={field name}
The valid sort keys include: testCaseId, name, description, channel, stepCount, campaignCount, modified, direction, destination and URL.
Using the folderId from the prior API call, listing the test cases within a specific folder is now easy. The resulting JSON will contain the resultId along with testCaseId for each test case in the folder. The resultId is actually the testResultId and is the unique ID needed for retrieving the results from the most recent validation run of the test case to which it is associated. Capturing the testCaseIds into an array will make building campaigns much easier.
Example: Execute the identified test case
Request URL: <baseURL>/v3.0/accounts/{accountId}/testcases/{testCaseId}/execute
This call executes the test case specified by the testCaseId included in the API call. This is not a campaign run but a validation run that is the type of test case execution that would have occurred had you selected “Save & Run” from the Cyara Portal. This API call does not return results; it only runs the test case. Results are obtained in the next API call.
There are times when all you need to do is a validation run of an individual test case rather than create an entire campaign. This API call addresses that need. The JSON response body that this call produces includes a testRunTicketId that will be needed to secure the results of the validation run.
Example: Get results from executed test case
Request URL: <baseURL>/v3.0/accounts/{accountId}/testresults/{testRunTicketId}
This call returns the detailed results of the validation run for which the testRunTicketId was assigned. At the end of the report, the testResultId is shown and should be saved for future reference. While the testRunTicketId never expires, the testResultId is used in many API calls.
After the test case validation run is initiated, there is no way to know when the run is complete other than executing the API call to get the results. If the test case is still executing when you request the results, you will get back a 404 error indicating the results are not found (available). Repeat the API request until you get the results from the validation run.
Example: Create a new campaign
Request URL: <baseURL>/v3.0/accounts/{accountId}/campaigns
This call creates a new campaign and requires that a JSON file with all the campaign parameters is connected to the request.
The JSON file requires the following information:
{
"campaignSync": {
"isActive": false
},
"pauseTimeBetweenRetries": null,
"maximumRetries": null,
"concurrency": 1,
"maximumAps": 1,
"active": true,
"channel": "Voice",
"description": "This campaign runs a test case created by the API",
"name": "Dataset API Campaign",
"testCaseDistributionProfile": "RoundRobin",
"planType": "Velocity",
"planId": YOUR_VELOCITY_PLAN_ID,
"requestedRunDate": "ISO-8601_RUN_DATE",
"scheduledRunDate": "ISO-8601_RUN_DATE",
"testCases": [
{
"testCaseId": YOUR_TC_ID1,
"probability": 100
},
{
"testCaseId": YOUR_TC_ID2,
"probability": 100
},
{
"testCaseId": YOUR_TC_ID3,
"probability": 100 }
]
}
Campaigns are one or more test cases combined with run schedules and assigned a unique name. The testCaseIds are drawn from the folder content listing created earlier. The planType is also from an API call listed earlier. The planType options available control what type of campaigns can be created. Be sure to capture the campaignId for the newly create campaign so that you can execute it when desired.
Example: Execute a campaign
Request URL: <baseURL>/v3.0/accounts/{accountId}/campaigns/{campaignId}/execute
This call executes the designated campaign as per the scheduled run date in the campaign. The API call will not provide a status of the campaign run but does provide a campaignRunId that is a unique identifier for the results of the campaign. You must save the campaignRunId to check on the status of the running campaign. All campaign types including Pulse can be launched with this API.
This is the first step of a 3-part process. First, execute the campaign which is now done. Next, verify the status of the running campaign to make sure the campaign finishes successfully. The third and final step is to get the campaign’s test results. There are different IDs needed for each step so plan the keep track of various identifiers along the way.
Example: Return the status of a campaign run
Request URL: <baseURL>/v3.0/accounts/{accountId}/campaigns/{campaignId}/runs/{campaignRunId}
This call provides the current information about the campaign in question. The JSON body returned from this call has three important fields: Status, Result and runId. Status shows “Completed” when the campaign has finished running. Result shows “Success” or “Failure” depending on the outcome. “Success” does not reflect the outcome of the test cases; it reflects the result of running the campaign.
To get the results of the test cases, we use the runId in the next API example.
This is the second step of a 3-part process. This step is essentially a polling step looking for the value of the “Status” field to show “Completed”. If the status shows Queued or Running, check again in a few minutes. A status of “Aborted” means what it says and depending on where the campaign was when aborted, results that can be retrieved.
Example: Returns the results of a campaign run
Request URL: <baseURL>/v3.0/accounts/{accountId}/report/campaigns/{campaignId}/runs/{runId}/results
This call returns the results from the campaign with various sorting options and detail options.
If results of each step in a test case are desired, include ?stepResults=true in the request.
This is the final step of the 3-part process. The basic report summarizes the results for each of the test cases within the campaign. If you elect to include the step results in the report, the results of each step within each test case is included.
Example: Get test result feed for Pulse campaign
Request URL: <baseURL>/v3.0/accounts/{accountId}/{channel}/testresults/feed
This call is utilized for polling and is designed for use with Pulse.
The possible values for the “Channel” variable are: None, Voice, Web, AgentVoice, AgentChat, AgentDesktop, Email, Sms, and AgentWorkItem.
Necessary options that need to be included with the call are “planType”, “fromDate” and “fromTestResultId”
The options for “planType” are Pulse, Cruncher, Replay, VirtualAgent, CruncherLite, Outbound, PulseOutbound, Velocity. The format for inclusion in the API call is planType=Pulse
The “fromDate” returns the test case results that were completed on or after the time supplied. The format of the time stamp is ISO-8601 Date format. Example: 2015-05-23T12:43:58Z
The fromTestResultId is the testResultId that serves as the oldest result being sought and includes test case results with an equal or higher TestResultId (newer).
The purpose of this call is to continually pull results from an ongoing Pulse campaign and then push the results into dashboards or other logging systems. The initial API call is likely to utilize the fromData option to capture the initial data load followed by using the testResultID of the latest result to then make subsequent API calls. If there are multiple Pulse campaigns running, the JSON result body must be parsed in order to pull the specific results desired as the feed is specific to the channel and not the campaign.
Additional Information
The APIs examples included in this document are a sample of the comprehensive array of APIs that Cyara has available for all customers to utilize. If you want more examples of API usage, see https://developer.cyara.com/hc/en-us/articles/360002182755-API-Samples
If you want more information about the various unique IDs that Cyara utilizes, see https://developer.cyara.com/hc/en-us/articles/360003983436-API-IDs-Test-Cases-and-Campaigns
If you want more information about using Swagger, see https://developer.cyara.com/hc/en-us/articles/360001040256-Using-the-Cyara-3-0-API-in-Swagger
Comments
0 comments
Please sign in to leave a comment.