Developer Resources

Estimated Wait Time API


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 CCAI Platform SDK, or for custom notifications or triggers.

Example Request

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



Field Name










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





Returns menus of a specific channel



Optional param





Returns menus of specific types




All (default)






Returns records if they have a wait greater than the value

Validation:Positive Int only





Returns records if they have a wait less than the value

Validation:Positive Int only





Queue structure to retrieve the ewt

Ex: "en" "es" "fr" "de"

"it" "ja" "ko" "pt"

"pt-BR" "sv"


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



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

Callback Call API


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


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:


Field Name












Note: server code refers to all inbound call requests, including call-back calls, as 'incoming'.





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)




_granted - call will be recorded

_denied - call will not be recorded





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


outbound_ number



Outbound phone numbers to be used for call

Validation:Should be number owned by tenant, that agent has access to





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.





Determines specific ticket to Pop

Validation:If both a ticket_id and end_user_number are passed in, the ticket_id will take precedence





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 \ \

-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",


"ticket_id": 177821


Multiple Mobile Apps (MMA)


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


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.

  1. Go to Settings > Queue > Mobile, and click Edit/View.

  2. Click on Edit to access the Mobile queue structure edit screen.

  3. 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

  1. Go to Settings > Developer Settings.

    There will be a 'Mobile Apps' section if you have an existing app configured:

  2. 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.

  3. 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

  4. 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.

  5. To enable the ability for agents to send an SMS to download your app, switch the setting to On.

  6. Enter the appropriate URLs for the App and Play stores.

  7. 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.

  8. 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.

  9. 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.

  10. 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

  1. Go to Settings > Developer Settings and scroll to the Mobile Apps section.

  2. Click Add Mobile App and complete the mobile-app configuration pop-up as described above.

  3. 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.

  1. Go to Settings > Queue > In-App > Edit / View.

  2. Click on a top-level queue.

  3. In the queue menu settings, scroll to the Direct Access Point section.

  4. Click on the Create direct access point link.

  5. 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.

  6. Name the Access Point.

  7. 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.

  8. Click Create to save.

  9. Repeat to assign a Mobile App DAP to each top-level queue menu if you have more than one app.


  • 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.

  1. Go to Settings > Queue > IVR | Edit / View.

  2. Click on a top-level queue.

  3. In the queue menu settings, scroll to the Direct Access Point section.

  4. Click the Create direct access point link.

  5. Select Mobile App as the Access Point Type. This option is only available for top-level queue menus.

  6. Name the Access Point.

  7. 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.

  8. 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)

  • 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

  1. Go to Settings > Developer Settings.

  2. Return to the mobile app management section. You will see that the mobile app "Off / Activate" toggle is now enabled.

  3. Toggle switch to Active to activate the mobile app.

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

  4. 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.

  • 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).