Developer Resources

Estimated Wait Time API

Overview

This API endpoint returns the calculated estimated wait time (EWT) per queue.

This can be used for custom support channel EWT displays on web pages or mobile apps outside of the Contact Center AI Platform (CCAI Platform) SDK, or for custom notifications or triggers.

Example Request

URL: http://{{subdomain}}.{{domain}}/apps/api/v1/wait_times

Parameters

ID	Field Name	Type	Required	Description	Values	Notes
1	menu_id	id	No	Response will filter all menus (queues) in that menu's sub-menu, including that menu	Root Menu (default) Specific menu	If nothing is passed, will return whole queue structure
2	channel_type	enum	No	Returns menus of a specific channel	voice_call chat	Optional param
3	menu_type	enum	No	Returns menus of specific types	ivr_menu mobile_menu web_menu All (default)	optional
4	wait[from]	int	No	Returns records if they have a wait greater than the value		Validation:Positive Int only
5	wait[to]	int	No	Returns records if they have a wait less than the value		Validation:Positive Int only
6	lang	enum	Yes	Queue structure to retrieve the ewt	Ex: "en" "es" "fr" "de" "it" "ja" "ko" "pt" "pt-BR" "sv"

Responses


ID	Field Name	Type	Required	Description
1	menu_id	id	yes	Foreign key to the /menus manager api endpoint
2	wait	INT	yes	Wait time in minutes
3	Materialized path	String	Yes	Materialized path as found in the /menus api

Example

http://{{subdomain}}.{{domain}}apps/api/v1/wait_times?lang=en&menu_id=10

Menu ID 10 estimated wait time is 120 seconds (or two minutes)

Callback Call API

Overview

The Callback Call API provides an API endpoint for initiating calls. This enables you to create a customized consumer experience with the ability to send the call to a specific queue. Because the call is initiated by the system after the consumer requests the call, the call type is labeled as "Call-back." The Call-back call will be assigned to an available agent, with the system automatically initiating the outbound call to the consumer (end-user).

Customers can programmatically create Call-back calls from any web-based or connected application allowing an extra level of customization for user interface design and workflow experience.

URI and authentication

The base URI for this new endpoint should be:

POST https://<subdomain>.<domain>/apps/api/v1/calls

Authentication

Basic authentication based on API Key and Secret. The Key and Secret can be accessed within the Admin Portal in Settings > Developer Settings.

API operations

Body and params

The body of the API request should have the following fields:

ID	Field Name	Type	Req?	Description	Values	Notes
0	call_type	String	Yes	IncomingCall	IncomingCall	Note: server code refers to all inbound call requests, including call-back calls, as 'incoming'.
1	recording_permission	String	No	Option to set recording permissions. Recording permissions value is only evaluated if queue level 'call recording option' is set to "Ask user permission to record'	recording_permission_not_asked (default) recording_permission_denied recording_permission_granted	Recording_permission:_not_asked _granted - call will be recorded _denied - call will not be recorded
2	end_user_number	String	Yes	Number to be called by the agent		Validation:If both a ticket_id and end_user_number are passed in, the ticket_id will take precedence
3	outbound_ number	String	No	Outbound phone numbers to be used for call		Validation:Should be number owned by tenant, that agent has access to
4	menu_id	id	Yes	Menu for attribution	Only menu_id's for IVR and web will be accepted.	Validation:invalid menu Id will prevent API call; API will return error response.
5	ticket_id	String	No	Determines specific ticket to Pop		Validation:If both a ticket_id and end_user_number are passed in, the ticket_id will take precedence
6	lang	enum	No	Will associate to a language		Default: English

Outbound number logic

	Phone Number Specified (well formed) that is not the global number	Phone Number Specified (not well formed)	Phone number not specified
Queue with many outbound numbers	Call is made via specified phone number	First available outbound (if available) or global number is used automatically
Queue with 1 number	Call is made via specified phone number	First available outbound (if available) or global number is used automatically
Queue with 0 numbers	Call is made with global number

Error and success

Ticket ID

'ticket_id' is provided

'ticket_id' is not provided

Call process

An instant call will be made and assigned to the specified ticket

Standard 'find/create' ticket process; i.e.

if there is an existing / open ticket for this end user for specified menu ID, that ticket is used, else a new ticket is created.

Recording permissions

Recording permissions for the API are primarily controlled on a queue level basis with the "Call Recording Options" configuration in the CCAI Platform Admin portal (see Recording Calls - Configuration Options). In order for the Incoming Call API to define recording permissions; i.e. after asking end user via customer's own UI, the destination queue's 'call recording option' needs to be set to "Ask User for Permission to Record".

When the queue configuration is set to:

Record - all API calls will be recorded (regardless of the API 'recording_permission' parameter value)
Do Not Record - all API calls will be not be recorded (regardless of the API 'recording_permission' parameter value)
Ask User for Permission to Record - call recording depends on the value passed in via the 'recording_permission' parameter; i.e.: if it is set to:

API samples

Response definition

The api responds with a single call object, as seen in the model from /calls .

Sample API response

Success response sample

{

"id": 6868,

"lang": "en",

"call_type": "IncomingCall",

"status": "queued",

"created_at": "2019-04-04T15:42:14.000Z",

"queued_at": "2019-04-04T15:42:14.000Z",

"assigned_at": null,

"connected_at": null,

"ends_at": null,

"scheduled_at": null,

"wait_duration": 0,

"call_duration": 0,

"hold_duration": 0,

"rating": null,

"has_feedback": false,

"out_ticket_id": null,

"out_ticket_url": null,

"verified": false,

"recording_url": null,

"voicemail_reason": "not_voicemail",

"deflection": "no_deflection",

"disconnected_by": "disconnected_by_unknown",

"fail_reason": "nothing",

"fail_details": null,

"support_number": "+18888888888",

"selected_menu": 12,

"menu_path": null,

"queue_priority_level": 0,

"agent_info": null,

"end_user": null,

"photos": [],

"videos": [],

"transfers": [],

"participants": [],

"offer_type": "cascade",

"offer_events": [],

"answer_type": "manual",

"outbound_number": "+18888888888"

}

API request sample

curl -X POST \

https://ujetzdco.ujet.co/manager/api/v1/calls/instantcall \

-H 'Authorization: Basic MTUyMDYyNDQ2VAKSHJVY34IUfsd3ya3EGSDF7EmIxOjA4ZDc1NGMxZWJmYmJjBkYzJkMjc5MzY4NmI1MzgzNTASJDCHBSY8jsns68489gsdhdDFGtKLUfasdaKHSDFHHYzZjMWYyMDlkZjYwI5NGNlNDQ=' \

-H 'Content-Type: application/json' \

-H 'Postman-Token: 40c3c2bb-ce39-4dfe-f0ff-9d4e3c871a620' \

-H 'cache-control: no-cache' \

-d '{

"call_type": "IncomingCall",

"outbound_number": "+18888888888",

"end_user_number": "+19999999999",

"menu_id":12,

"ticket_id": 177821

Multiple Mobile Apps (MMA)

Overview

Allow the mobile (Pro) SDK to be integrated into multiple, distinct mobile apps.

You can control technical settings, queue structures, and routing separately for each app if you have two different iOS and Android apps, one for customers and one for employees.

::: warning If you have no need to update your existing app configuration or support multiple mobile apps, it is recommended that you do not update the configuration of your existing mobile app. :::

Admin Config

Option to activate Multi Mobile App (MMA) mode in order to manage existing or new mobile apps

In-App Queue Management per Mobile App: Define distinct queue structures and agent assignments per mobile app.
Languages & Messages: Define distinct in-app messages for each mobile app and language combination.
PSTN Fallback to IVR Queue per Mobile App: Assign each mobile app to a top-level IVR queue for fallback calls when VoIP calls aren't possible

Note: for IVR messages used within the MMA setup, only English language is currently supported.

Guide

Step 1: SDK Integration

Integrate our latest iOS and/or Android SDKs into your mobile app(s)

Scenario 1: Single app existing SDK integration

It is recommended, but not strictly necessary to upgrade our SDK in your mobile app, however, CCAI Platform portal based configuration for PSTN fallback and data connectivity threshold levels is only available via SDK v 0.30+.

Scenario 2: New SDK integration Integrate our latest SDK into your mobile apps.

Step 2: Mobile app queue menu structure

Scenario 1: Existing Mobile Queue Structure Modify your existing queue structure by moving the entire structure for your existing app, into a single new top-level queue menu.

Go to Settings > Queue > Mobile, and click Edit/View.
Click on Edit to access the Mobile queue structure edit screen.
Create separate top-level Mobile queue structures for each mobile app.

Scenario 2: New mobile app

Create your Mobile queue menu structure. Start by creating a top-level queue for each mobile app and then add the app-specific queue structures within each top-level queue menu. See

Step 3: MMA app configuration

Scenario 1: Existing mobile app

Go to Settings > Developer Settings.

There will be a 'Mobile Apps' section if you have an existing app configured:
To prepare your existing app for MMA mode, click on the edit (pencil) icon and complete the required fields in the Edit Mobile app window.
Mobile app name (required): Must be a unique name across previously defined mobile apps.

Mobile Identifier iOS / Android - at least one of these is required
Enter the Mobile App identifiers. Without the correct identifier(s), notifications and the SmartAction functionality (via Agent call adapter) will not work.

At least one identifier (OS or Android) needs to be defined

The same identifier can be used for both iOS and Android

The same identifier can not be the same across mobile apps.

Note: ensure you are entering the correct mobile identifier(s).
To enable the ability for agents to send an SMS to download your app, switch the setting to On.
Enter the appropriate URLs for the App and Play stores.
Fallback phone number: requires the inclusion of country code; e.g. in the US: 1 714 450 5656

If the mobile SDK detects that the data connectivity for a given call does not meet the configured minimum threshold set below, the call will fall back to a PSTN phone call using the number defined here.
Fallback phone number threshold (required if PSTN number is specified): A threshold based on the condition of the caller's data network connectivity, determining whether a call should occur via VoIP or via the fallback PSTN phone number.

Valid range 0 to 1. A high threshold number like 0.98 indicates that a call will occur via PSTN unless data connectivity is excellent. A threshold value of 0 would initiate via VOIP, even for relatively poor data connectivity conditions, likely resulting in reduced call quality. A threshold value of 1, initiates all calls via PSTN.

If the data network connection can simply not support a VOIP call, PSTN fallback still occurs even with value set to 0.
Don't permit PSTN calls from outside the app: Mark this checkbox if you want to restrict PSTN fallback calls to those made from within the mobile SDK.

When enabled, callers making a direct call from outside the app will be directed to a customizable message and the call is automatically ended after the message has played.

All calls from the mobile app (assuming suitable data connectivity), will include the custom data flow from the app to the CRM / agent.
Push Notifications (required): Certificate PEM file (iOS), FCM (Android) Key

Ensure that PEM file is added if the iOS identifier is specified

Ensure FCM Key is added if Android identifier is specified

Configure Push notification settings based on the readme documents.

Scenario 2: Add your first mobile app

Go to Settings > Developer Settings and scroll to the Mobile Apps section.
Click Add Mobile App and complete the mobile-app configuration pop-up as described above.
Click Submit to save.

Mobile app list - configured app status - not assigned to In-App Queue

When the mobile app status shows an inactive "Off / Active" toggle and a warning triangle, the only available option is to go to the next step and assign the mobile app to an In-App queue.

Step 4: In-App queue structure - Mobile App Direct Access Point (DAP) assignment

Define dedicated Mobile top-level queues for each mobile app.

In order to activate a mobile app in Settings > Developer Settings, the mobile app must be assigned as a Mobile App type Direct Access Point (DAP) in the Mobile queue menu structure.

Go to Settings > Queue > In-App > Edit / View.
Click on a top-level queue.
In the queue menu settings, scroll to the Direct Access Point section.
Click on the Create direct access point link.
Select Mobile App as the Access Point Type. This option is only available for top-level queue menus, so if you don't see it, make sure there isn't a queue above the one you have selected.
Name the Access Point.
Select the mobile app to assign this queue structure to.

Each mobile app can only be applied once as a DAP within the entire In-App queue structure. A mobile app that has already been assigned to a different top-level queue will not be available for selection in another top-level queue.
Click Create to save.
Repeat to assign a Mobile App DAP to each top-level queue menu if you have more than one app.

Details

In-App Queue DAP evaluation will follow existing priority - user segment and general DAPs are evaluated before mobile app.
Alert: Ensure that the DAP evaluation logic conforms to the MMA parent queues and doesn't route end-users from, for example, MMA A to parent queue B because of another DAP.

Step 5 - Mobile App DAP assignment to IVR queue menu

PSTN fallback calls generated from a specific mobile app can be sent to a configured Mobile App DAP in the IVR menu. Mobile app-specific messages will be applied.

Similar to how a mobile app is assigned to a top-level Mobile queue menu via DAP, a mobile app can be assigned to an IVR queue via a Mobile App type DAP.

Go to Settings > Queue > IVR | Edit / View.
Click on a top-level queue.
In the queue menu settings, scroll to the Direct Access Point section.
Click the Create direct access point link.
Select Mobile App as the Access Point Type. This option is only available for top-level queue menus.
Name the Access Point.
Select the mobile app to assign this queue menu structure to.

Each mobile app can only be applied once as a DAP within the entire IVR queue structure. A mobile app that has already been assigned to a different top-level queue will not be available for selection in another top-level queue.
Click Create to save.

Dial '0' edge case

In PSTN fallback to IVR scenarios it is initially possible for an end-user to navigate to the top of the IVR queue structure by pressing '0' once, or the requisite number of times, depending on where in the queue that is initiated.

This can be averted by updating the "Dial 0" routing per queue, which offers the ability to prevent a user from inadvertently reaching the mobile queue.

Step 6 - Messages Setup

On the Settings > Messages & Languages page, it is possible to customize the following messages for each mobile app:

After hour message
Audible messages
- In order to be able to specify audible messages per app, the mobile app DAP (for each mobile app) must be applied to the appropriate IVR menu app(s). See Step 5 - Mobile App DAP assignment to IVR queue menu.
Voicemail message
IVR messages (excluding only the 'purchase flow' messages)

Note: only available in English
Custom Callback Messages

Important: The channel drop-down selection automatically regulates all message configurations listed in both "Mobile & Web SDK" and "Audible Messages" sections for the selected mobile app, with the following exceptions:

IVR 'purchase flow' messages
All IVR specific messages can only be configured for English

Step 7: Mobile App Activation

Go to Settings > Developer Settings.
Return to the mobile app management section. You will see that the mobile app "Off / Activate" toggle is now enabled.
Toggle switch to Active to activate the mobile app.

Activated app - an existing mobile app will hereby be upgraded to MMA mode.

Note: Once you activate an existing mobile app for multi-app mode, you can not revert that app back to single app mode.
Once Active:

New apps - all new apps will automatically be generated in MMA mode.

Additional apps - you will be able to define and manage multiple apps from this page.

Step 8: Test Push Notifications

You now have the ability to test push notification functionality on a mobile app by mobile app basis. A drop down enables the admin/developer to select the specific mobile app to engage the testing with.

Changes with MMA Mode Activated

Changes to Portal Settings

After you have upgraded your mobile app to MMA or have created your first MMA app, the following changes are applied:

Settings > Operation Management > Send SMS links section - will be removed from the page. This configuration will then be accessible via the mobile app config pop-up.
In-App Queue Structure - ability to assign a mobile app DAP to top level queues.
Settings > Languages & Messages - ability to select specific messaging per mobile app will be added
IVR Queue Structure- ability to assign a mobile app DAP to top-level queues for English language.

Note: allows for specific IVR queue assignment per mobile app PSTN fallback number.
Settings > Developer Settings > Test Push Notifications - a mobile app drop down is added. Select the appropriate app for which you want to test sending notifications.
Agent Call Adapter - has added app selection list for sending links to install and open the app via SMS.

Changes to Mobile Session Flow

Mobile menu session flow with MMA mode enabled
Calls / Chats: When MMA mode is enabled, all incoming calls and chats are directly assigned to the appropriate mobile app assigned through the Mobile App DAP at the top-level queue menu.
Mobile SDK menu: Once a mobile app has been assigned to an in-app top-level queue and the mobile app is activated, the SDK only retrieves menu items in the assigned top-level in-app menu to which it was assigned via DAP.
Languages: Mobile queue languages are applied automatically.

Changes to Agent Adapter and actions

Session Transfers

Session transfers will adopt the following rules:

Transfers to queue

Sessions originating from 'mobile app A' can only be transferred to (sub) queues within that apps' parent queue via the agent call adapter transfer UI. I.e. an agent looking to transfer a 'mobile app A' session to another queue will only be able to:
- See destination queues in the originating parent queue, such as 'mobile app A' parent queue.
- Select a destination queue in the originating parent queue.
Transfer to agent - a session can be transferred to any available agent, including agents not assigned to any queues in the 'mobile app A' parent queue.
- Follow-on transfer considerations = same rules as the original transfer agent, queue options

Sending 'App Install' / 'Open App' SMS messages

For the following scenarios the agent needs to select the appropriate mobile before they can send the app info via SMS; i.e. 'Send SMS to Install' and 'Send SMS to Open App' for:

Outbound calls
IVR calls

In the Agent Adapter, when multiple mobile apps have been configured and the agent is either making an outbound call or handling an inbound IVR call, the agent will be presented with a second screen to select the appropriate mobile app after selecting one of the 'Send SMS to Install / Open App' SmartActions. The list presents the names of the active, configured mobile apps.

Left mobile app screen - various SMS / SmartAction options
Right mobile app screen - 'Send SMS to install App' option selected. Agent then selects the appropriate app (note: the actual configured app names; e.g. App1, App2 in this example) will be shown in this list).