API Direct Access Point for IVR Calls
Overview
Direct Access Points allow you to direct voice calls to a specific queue in the IVR queue structure. The API Direct Access Point (DAP) allows for routing logic to be implemented directly from an API source that can be outside of your CRM. The request is processed via JSON in order to route calls to a specific queue based on the phone number (ANI) of the caller. POST and GET HTTP request methods are supported. Unlike other DAP options, "AND" logic can be used with multiple key/value pairs.
Optionally, the specific inbound support number can be included so that when a Support phone number is entered, all key and value pairs AND the support number need to match in order for the caller to be routed to the selected queue.
Requirements
API URL: A URL endpoint that is able to receive a phone number via the request and return a JSON response
Test phone number: Once the DAP is set up, a test phone number needs to be used to ensure the configuration correctly returns results (typically in JSON format)
API credentials: Basic authentication is required for a non-Salesforce endpoint
OR
Salesforce Configuration: Follow the steps in API Direct Access Point - Salesforce REST API for initial setup in Salesforce
Routing logic and options
There are 2 possible routing configuration options. Please work with your CSM or CCAI Platform Support to enable the desired configuration.
Option 1 - Check API value first
When a call comes in, CCAI Platform uses the incoming phone number (ANI) to look up any specific routing matches. This option is used when the data in the API response is more important than what phone number is dialed by the caller. An example would be callers who are routed via fields in the CRM that they might not know about, such as sending a new customer to an onboarding queue or a caller at an at-risk account to a retention team queue. The API DAP can also have a combined phone number requirement so that the caller must call the selected phone number AND meet the API
API DAP
Phone number DAP
User segmentation
Option 2 - Check phone DAP first
When a call comes in, CCAI Platform uses the incoming phone number to look up any specific routing matches. In this case, the most important indicator for where to route the call is what number was dialed. An example of this would be connecting all incoming calls to a 24-hour Diamond level support queue based on phone number dialed without taking other DAP types into account.
Phone number DAP
API DAP
User segmentation
CCAI Platform Portal configuration
Enable CRM access
Go to Settings > Operation Management > Allow CRM access.
Mark the checkbox to Allow CRM Access for user segment information.
Click Set General to save.
Developer Settings
Go to Settings > Developer Settings > Scroll to the API Request Direct Access Point section.
Enter the APIRequest URL. Only one endpoint can be configured per environment.
Select the Authentication Method.
Basic Authentication: Username and password.
OAuth: Only available when using Salesforce.
Custom Header: Uses HTTP headers for authentication with the ability to manage a list of header key/value pairs.
To add a new header key/value pair, select Custom Header for authentication
Click Add field .
Enter the Field Key and Field Value and click Save.
Add more pairs as needed.
Click the pencil icon on each row to make edits. Click the X icon to remove that pair.
Enter the Authentication Credentials (username/password) if using Basic Authentication.
Set the API Request Timeout. The default is 2 seconds.
The time needed will vary based on your server response time. HTTP tools like Postman can check the return rate to give you a better idea of the time needed.
Remember that callers are waiting to be connected to an agent during this time, so it should be long enough for any API responses but short enough that the caller's wait time is impacted as little as possible.
If the request times out and no match is made, the next DAP type will be checked for a match. If no match, the call will be sent to the top of the queue. If you have multiple languages enabled, the language selection message will play for the caller.
Select an API Request Method. Only one endpoint can be configured per environment.
POST
Example: https://some.server/api_dap (POST)
{"phone": "+12223334444"}
GET
Example: https://some.server/api_dap?phone=+12223334444
Select the Phone Number Format used where the phone numbers are stored. Phone number is used to look up the contact record information that is used to route the caller.
Enter the Request parameter where the server request should be pointed. The entry can be any string and is case sensitive.
If this field is not an exact match with the parameter on your server, routing will fail regardless of timeout setting.
Example GET request: https://some.server/api_dap?[request_parameter]=+12223334444
Check the desired boxes to pass the response data to the CRM record in the Push API Response Data to CRM section.
CCAI Platform will format the response data as a key/value pair and add it as a comment to the record associated with the incoming call.
CCAI Platform will push the response data in the exact JSON format received as a comment to the CRM ticket for the incoming call.
Click Save.
Test the configuration
CCAI Platform has a field that allows you to quickly test that the connection has been properly configured. You will need a phone number that is linked to a contact that you know will return the value you are looking for from the queried server.
From the CCAI Platform Portal, go to Settings > Developer Settings > API Request Direct Access Point.
Enter the test phone number in the Test Connection section.
Click Test this connection.
View the JSON response from the call to the API.
If null or no results, check:
Is the connection pointed to a database with the correct data?
Is the phone number associated with a contact?
Is the phone number format correct?
Does the response header match exactly?
If the response is timing out, increase the timeout value in the settings above the test section.
If the timeout becomes so long that it will lengthen wait times, investigate how to optimize your server response time.
If the results look good, move on to the next step.
Creating Direct Access Points
Important logic details
CCAI Platform uses the exact order in which all API DAPs in your environment are created to route calls, making the specific order in which the API DAPs are created extremely important. If you have existing API DAPs created and they have any overlap with new API DAPs you are creating, you may need to recreate the DAPs in a new order to achieve the desired routing.
Each condition can be a compound set of key/value pairs or a single key/value pair, and once the qualification is met, CCAI Platform will stop checking for matches and will route the call. For this reason, the most complex conditions should be created before the least complex, to ensure the more complex conditions are checked first.
Correct example
CCAI Platform will match 1 first, then 2, then 3.
"brand = Generico" AND "Customer type = lead" AND "product = retail"
"brand = Generico" AND "Customer type = lead"
"brand = Generico"
Incorrect example
If DAPs are created in this order, it will match in order 1, then 2, and then 3. Conditions 2 and 3 will never be reached since all requests will meet the first condition.
"brand = Generico"
"brand = Generico" AND "Customer type = lead"
"brand = Generico" AND "Customer type = lead" AND "product = retail"
Create API DAPs in Queue Setup
You will now designate where in the Queue structure the caller should be routed by setting up a Direct Access Point (DAP).
Go to Settings > Queue > IVR.
Select the Language of the menu for the API DAP (ex. English).
Click on the queue name, then scroll down and click Create direct access point.
Select API Response from the Access Point Type dropdown.
Click Add Key & Value.
Click Save.
Optional: Add a Support Phone Number to indicate the phone number that the caller has to be calling into in order for the DAP endpoint to be triggered. When a Support phone number is entered, all Key and value pairs AND the support number need to match in order for the caller to be routed to the selected queue.
Optional: Add a greeting by typing a Text-to-Speech message or uploading an audio file that will play to callers routed to this queue via the DAP.
Click Create.
The created access point(s) will show next to the queue name in the queue structure for quick reference.
Test call routing
Call the IVR using a phone number which should trigger the API DAP.
Confirm the call is routed to the correct queue and any entered greeting is played.
Twinning
Overview
Twinning allows a primary extension (web desktop adapter) and a secondary extension (for example, mobile phone number) to operate as a single phone. Twinning is ideal for support agents who are frequently on the go, since it allows them to forward support calls to their preferred phone number while also allowing them to handle calls at their desk using their web adapter. Another example is a front desk phone set up as the office's primary extension; you can use Twinning to forward those calls to a mobile phone. Twinning supports international phone numbers.
Main benefits:
Full flexibility: When the forward calls to phone number setting is elected in the Agent Adapter, the call is sent to the phone number but Agents will continue to receive call notifications in their web adapter. They are still able to answer the call there if desired. Agents are able to receive all types of incoming calls using this method including: IVR, Mobile, Callbacks, Scheduled Calls.
Supports routing using DID. Twinning is able to route calls using a unique identifier known as a Direct Inward Dialing (DID) number. A DID number is a telephone number that is used to directly connect to a specific extension or department within an organization.
CRM ticket generation: Twinned calls handled through an extension on a mobile phone still generate a CRM ticket.
Reporting and monitoring: Twinned calls will be displayed in reporting and on all Monitoring Pages. For now, the record appears as a regular call and does not identify whether it was answered through an extension.
No internet connection required: The call is made over PSTN.
Compatible with Multicast and Deltacast. Note about Multicast: If certain agents in the queue are set to receive calls on their phone while others are not, all agents will still receive the call. This allows agents to use their phone, while others can use their Agent Adapter.
Configuration considerations
Agents will receive the calls from whatever is set as the Global default outbound phone number.
Agents should add the phone number to their contacts to avoid having the call marked as spam.
When you select Forward calls to phone number in the Agent Adapter, any incoming calls for the agent will now be routed to the phone number entered in the user profile.
If agents intend to have the web adapter actively open at the same time, we recommend that you turn off Auto Answer.
Because twinned calls are not using the Agent Adapter, the following adapter features are not accessible when Twinning is enabled: Transfers, SmartActions, Hang up and Call back.
Grant Mobile Calls permissions
By default, the Agent role does not allow agents to forward calls to their phone. Admins must create a new custom role and grant the Mobile calls permission. Make sure to assign the new role to any users you want to be able to forward calls.
If you intend to apply the Mobile Calls permission to existing users, the new custom role can include the Mobile Calls permission only. All other permissions are handled by the users' existing role(s). When you assign a user a new custom role, their permission set will be the superset of their prior roles plus the new one.
For more details, see the roles and permissions documentation.
Enable agents to receive calls on their mobile
Go to Settings > Operation Management > Agent Status.
Under Availability Preferences select Allow agents to receive calls on their mobile phone.
(Optional) Increase Deltacast timeout for mobile Agents
Agents who are on-the-go may require more time to pick up a call than agents sitting at a desktop. If you are using Deltacast, you can increase the amount of time Agents have to pick up calls. To change Deltacast timeout:
Go to Settings > Operation Management > Deltacast.
Set the Deltacast timeout value. The default value is 5 seconds.
Set up call forwarding for Agents
Before you can configure the agents, the two prerequisites listed below must be met:
- The Mobile Calls permission must be granted to the agent (see previous section).
- Availability Preference settings must be enabled (see previous section).
Under Admin, select My Profile.
In the Mobile Calls > Phone Number field, enter the phone number you want to receive calls on.
Set the call to forward to another extension in Agent Adapter
Agents who have the Mobile Calls permission will see the new Availability Preferences feature in their call adapter.
The current default setting is Only Web Agent Adapter (Desktop). Even when set to Forward calls to phone number, the Agent will continue to receive call notifications in their web adapter and are still able to answer the call there if desired.
Open the Availability Preferences menu.
Select Forward calls to phone number.
Click Save. Any incoming calls for the agent will now be sent to the phone number specified in their user profile.
Check an Agent's phone number
Supervisors can check an Agent's configured phone number. They are not able to change the agent's phone number.
Go to Users and Teams.
Select Edit a User to view the phone number.
Percent Allocation Groups
Overview
Percent Allocation Groups allow you to specify the percent of calls or chats that each group assigned to a queue will receive.
For example, a support operation may have multiple contact centers or teams that have varying levels of expertise. Admins can then specify that Team 1 receives 60% of incoming calls, while Team 2 gets 40% of calls from that queue.
Percent Allocation Groups can help direct a contractually-mandated amount of traffic to a third-party support team or BPO.
CCAI Platform Portal set up
Per-queue setting
Percent Allocation is set on a per-queue basis and is accessible through the Assign Agents setup page.
Go to Settings > Queue > Select the channel to edit.
Select a queue.
Click click Assign agents and then toggle to Percent Allocation Group.
Add groups by clicking Add New Allocation Group.
Assign agents by searching for specific agent names or team names.
Assign the percentage of calls to each group. The total of allocations across all groups must equal 100%
Click Save.
Operation Management settings configuration
Go to Settings > Operation Management > scroll to Group Settings
% Allocation Group: Configure if the call should move to the next group if the first doesn't pick up the call in the set threshold:
Mark the checkbox for calls/chats to also be offered to the other groups set up for the queue menu options if not picked up by the selected group after a defined length of time.
Leave this unselected if you do not want calls or chats to go to another % allocation group. Ex. You need 50% of all of your calls to go to one team and never offer those same calls to another team or group.
Routing details
For this feature, call routing rules apply to Groups first based on percentages that you set.
Example - Two groups are set up for a queue, Group 1 (60%) and Group 2 (40%)
60% of calls will be routed to Group 1
40% of calls will be routed to Group 2
Percent allocation is the first leg of the call routing journey. After a group is chosen based on the percent, then calls are routed using the Deltacast and Multicast settings you have configured. See Call Routing: Deltacast and Multicast for more information about routing options.
Depending on your call routing settings, the following may take place after the initial percent allocation of incoming traffic occurs:
Example 1: Deltacast Timeout is before the Percent Allocation timeout
The call gets routed to the longest-idle agent in the chosen group (Deltacast)
If the agent does not pick up the call before the assigned timeout (see Operation Management settings configuration) it will stay in the Deltacast queue and broadcast to the rest of the selected group for the rest of the percent allocation timer.
If none of the agents from the selected group pick up the call and the setting is enabled, the call will be Multicast to all groups.
Example 2: Deltacast Timeout is after the Percent Allocation timeout
The call gets routed to the longest-idle agent in the chosen group (Deltacast).
If the agent does not pick up the call before the assigned timeout set in Operation Management it will stay in the Deltacast queue and broadcast to the longest idle agent of each group assigned to the queue for the rest of the Deltacast timer.
If none of the Deltacast agents from the assigned groups pick up the call, the call will be Multicast to all members of all groups.
Example 3: Deltacast is not enabled
The call gets Multicast to all agents assigned to the selected group.
If none of the agents pick up the call before the configured timeout, the call is then broadcast to all members of all assigned groups.
Example 4: Percent Allocation - Routing Options is not enabled
The call gets Deltacast/Multicast as configured within the assigned group.
The call is not broadcast to any other groups assigned to the queue.
Cascade Groups
Overview
Cascade groups allow multiple sets of teams or agents to answer calls for a specific queue. It also allows for tiered routing by notifying Group 1 first, then including the next group(s) sequentially. This means if your call isn't answered by one agent or group of agents, you can set up a custom routing configuration to make sure it's taken care of by the right agents.
Cascade Group behavior
Group 1 will be notified first, then Group 2, then Group 3, etc. Each group in the process will be notified along with previous groups after the time limit selected in the Operation Management settings, in the Group Settings section. The setting impacts the whole environment (all queues and channels).
If a call has moved to the next group but an agent from a higher level group becomes available, the call will always go to the highest level group.
If no agents are available in the first group, the first group is skipped and the call is offered to the second group.
If there are no agents assigned to the first group, the first group will be skipped to the next group where there are agents assigned.
Groups receiving notifications will continue to get them as more groups are notified until the call is answered.
Estimated Wait Time will be calculated based on all assigned cascade group agents.
When Scheduled Calls are enabled for a queue with cascade groups, if no agents are available to assign a call to, the first available agent from any cascade group will be assigned.
When used with Deltacast:
The Deltacast timer and the cascade group timer start at the same time.
The call will only be routed via Deltacast for the first attempt and will alert the agents via Multicast until the call is answered.
CCAI Platform Portal configuration
Creating groups and assigning agents
Cascade Group settings
Go to Settings > Operation Management > Cascade Group.
Set the duration the system should wait for before notifying the next cascade group.
Click Set General to save changes.
Queue Priority
Overview
The queue priority feature enables admins to define the priority value of a selected queue. Call or chat sessions from higher priority queues will be routed to available agents first. Admins can also enable prioritization by wait time where the priority of a given session will automatically increase based on wait time until the session has reached the highest available priority.
Queue Priority details
When an agent is assigned to multiple queues, calls and chats will be routed to the agent based on their routing order.
Queue priority can be customized from +10 to -5 and defaults at 0.
Queue priority can be configured for queues with no sub-queues. If a queue has a sub-queue nested within, you cannot configure the top queue.
The priority of calls/chats can be automatically increased based on wait time using time intervals. These automatic increases can be call and chat channel-specific.
Transfer behavior and example routing
Within a specific queue, 3 session types have higher priority than regular inbound sessions: sessions from priority users scheduled calls, and transferred sessions. See Priority User Segments
Across multiple queues, the agent will get the session from the highest priority queue first.
Examples
If an agent is assigned to 2 queues, queue A (priority 1) and queue B (priority 2), and there is a transferred call arriving in queue B, and an inbound call in queue A, the agent will receive the call from the higher priority queue B.
Within a queue, transferred calls have a higher priority compared to inbound calls. If there are multiple transfers into a given queue, the call transferred from a higher priority queue will retain the higher priority among transferred calls into the destination queue.
Routing prioritization
Call/Chat priority is determined by type then by queue (High/Low priority)
Call/Chat Wait Time Prioritization can increase priority of lower value calls/chats types only
Admin Configuration
Enabling Queue Priority
Go to Settings > Operation Management.
TurnQueue Priority On with the toggle to activate (to save setting, see step 5).
Enable Wait Time Prioritization for Calls if you would like to increase the priority of a call by 1 queue priority in the interval of time set. This setting ensures that if waiting for long enough, a lower priority call will not get continuously pushed back in queue when other high priority calls come in.
Enable Wait Time Prioritization for Chats if you would like to increase the priority of a chat by 1 queue priority in the interval of time set. This setting ensures that if waiting for long enough, a lower priority chat will not get pushed back when many other high priority chats come in.
Click Set Queue Priority to save.
Setting Queue Priority level
Queue priority level is always set per-queue.
Go to Settings > Queue.
Click Edit/View to go to the editing section for queue menus within that channel.
Toggle Custom Queue Priority to On to activate for a leaf queue. This option is not available if there is a sub-queue below.
Slide the call priority slider left or right to lower or raise priority level for calls in this queue.
Slide the chat priority slider left or right to lower or raise priority level for chats in this queue.
Click Set Queue Priority.
Automatic Redirection
Overview
Queues can be set up in many different configurations - some intended to be routed to an agent, and others present different user flows for consumers. Automatic redirection allows for consumers to be routed to different options based on your needs.
Feature details
When a call is transferred to a queue with Automatic Redirection active, the call will follow the redirection path just as a new call would.
After Hours redirection will override Automatic Redirection in certain cases.
Transfers to a Call queue configured for automatic redirection will only occur if automatic redirection is set to "message" or "voicemail".
Automatic redirection to "queue" or "phone number" will take priority over After Hours deflections.
Transfers to a chat queue with automatic redirect set to web site will override after hour deflection.
For more info about After Hours Redirection see After Hour Deflection for Calls and Chats.
If a deflection option is set, then disabled, the previous setting will save when re-enabled.
Outbound SIP Headers Outbound SIP Transfers are a type of IVR redirection that transfers IVR calls to an external SIP destination automatically. Automatic Redirection is used to configure outbound SIP redirections at the IVR queue level. For more information see Configuring SIP Transfers as Automatic Redirection.
Example use cases
There's a natural disaster in the region where your contact center is and you want to play a message stating that your support operation is currently unavailable (message).
You want to use your regular menu flow, but give an option that sends callers outside of CCAI Platform (phone number).
Most queues don't want to use voicemail, but one option the customers can select goes right to voicemail so you can collect detailed information and call the customer back when the correct team member is available (voicemail for IVR queues only).
Customers can get to the same queue from multiple places in the queue structure, so you redirect repeating options using queue redirect (queuefor IVR queues only).
Present your users with product offerings based on their locations by directing to a specialized web page based on user ID (websitefor Mobile and Web queues only).
Agent experience
When transferring IVR calls, Agents will be able to see if a call is going to be redirected in the UI. This experience is available for IVR. For Mobile, Web, and SMS, the redirection will not be visually shown.
Configuring automatic redirection
From the CCAI Platform Portal, go to Settings > Queue.
Click Edit / View to the editing section for queue menus within that channel.
Select the queue to edit.
To enable Automatic Redirection, click on Hide/Show to show the redirection options for the queue menu option.
Message: Write a message that consumers will be redirected to. For IVR, the message will be read with text-to-speech and the call will end. For Mobile or Web, the text of the entered message will display.
To add hyperlinks to the message, follow the below structure. The output in the SDK will depend on the version of the Mobile or Web SDK your company has installed:
Text format structure: {{https://www.ujet.co | Visit our website}}
Web SDK and Mobile SDK versions >= 0.34.1
Text displayed: Visit our website
Mobile SDK versions < 0.34.1
Text displayed: Visit our website https://www.ujet.cx
Phone Number: Routes caller to another number. Enter number with + and country code. Numbers with extensions are not accepted.
Queue: (IVR only) Redirects caller to another queue. See Redirecting to a queue for more details below.
Voicemail: (IVR only) Routes caller to voicemail queue with an option to customize the voicemail greeting for the queue. If custom message is added, a unique greeting will play for the caller.
Website: (Mobile and Web only) Enter a mobile-friendly URL to display a webpage, insert a mobile app identifier, or insert a dynamic User ID. See Inserting a Dynamic User ID for details.
Set Redirection: Saves above settings.
Redirect to a queue
Currently available for IVR queues, redirecting one queue to another queue can be a powerful feature for complex, consumer-focused queue structures. Make sure the queue you are redirecting to is configured and has at least one agent assigned.
From the CCAI Platform Portal, go to Settings > Queue.
Click Edit / View below IVR.
Click to select the queue to edit.
Click Hide/Show to show the Automatic redirection options for the queue.
Click to select the Queue.
Enter the name of the queue to redirect to using the search field.
Click on the name of the queue to select and the name of the selected queue will now appear above the search field.
Optional - To set a greeting message specific to calls being redirected to a queue, click Additional Settings.
Optional - Enter the text to be used for Text-to-speech, or upload an audio file to play for redirected callers. This message will play after the caller has been redirected to the new queue. Click OK to save.
Click Set Redirection to save the new settings.
Configuring SIP Transfers as Automatic Redirection
Outbound SIP Transfers are a type of IVR redirection that transfers IVR calls to an external SIP destination automatically.
Automatic Redirection is used to configure outbound SIP redirections at the IVR queue level.
This functionality allows you to route calls to any platform that can handle incoming SIP calls.
You may, for example, construct a redirection that routes calls received by a certain queue to a group of agents via an external destination.
Configuring SIP Transfers
You can set up Automatic Redirections to a defined external SIP destination at the IVR queue level. Any calls that come in that queue will be sent to the SIP endpoint you specify.
Go to Settings > Queue > IVR.
Select the queue in which you want to create the redirection.
In the Automatic Redirection section and toggle the switch to Show (if necessary).
Click Configure SIP Transfer.
The Outbound SIP Configuration panel opens.
Enter the Destination SIP URI in
+ccNumber@fqdnformat.This is the endpoint to which calls to this queue should be redirected.
NOTE: There is a 256 character limit for this value.
Click Save.
Return to the Settings page.
Select the Outbound SIP Transfer option.
Click Save Redirection.