Configuration · guide

Setting up courtesy callback in Unified CVP

Cisco Unified CVP

Verified 2026-10-01 · 88 sources · tier 2–5

For Unified CCE or Packaged CCE administrators who already run a working Unified CVP queuing call flow and want to enable Courtesy Callback using Cisco's sample scripts..

In Unified CVP Courtesy Callback, a caller queued by Unified CVP can hang up and be called back when an agent is close to becoming available, which Cisco calls preemptive callback 52. Preemptive callback does not change how long a customer waits to reach an agent; it only lets the caller hang up instead of staying in queue listening to music 78.

Before you start

Cisco's Courtesy Callback documentation states that a callback cannot be scheduled for a specific time 43. The CallBack table's CallBackType column still holds P for preemptive and S for scheduled 9. WarmTransfer's reading of the sources is that none of the 15.0(1) configuration material reviewed exposes a way to configure scheduled callbacks, so only preemptive callback can be planned for 62.

Calls that allow callback must be queued using a Unified CVP VXML Server 77.
The Unified CVP Reporting Server is a prerequisite for Courtesy Callback 56.
A courtesy callback is placed through the same ingress gateway through which the original call arrived 61, and Courtesy Callback cannot place its outbound calls through any other egress gateway 42.
Cisco states that Courtesy Callback is supported for IP-originated calls as well as TDM calls 31.
If the Reporting Server is not back online within the CallbackWait retry window, the pending entry is not called back 54. The CallbackWait application's WaitLoop retry count defaults to 6 retries in the Check Retry element and can be raised to give a longer window before the call is dropped 79. Failure of a CVP Reporting Server has no impact on call survivability 82.
Field reports suggest that offering callback to too many callers at once skews the wait estimate; one integrator recommends starting with a fraction of eligible callers and not re-offering after 2 declines 26. In the field, an integrator also recommends capturing numbers from unsuccessful callbacks and adding them to an outbound campaign for later attempts 25.

What changes by situation

Pick your answers to see only your path. Nothing is sent anywhere until you make a plan.

Which Cisco contact center deployment runs your Unified CVP?

What estimated wait time should trigger a callback offer?

When may the system place callbacks?

Which callback numbers will you allow?

Four questions. One permanent page you can send to your manager.

Step 1 Confirm the prerequisites and limitations

Do

Confirm that the calls you want to make eligible are queued using a Unified CVP VXML Server 77. Confirm that a Unified CVP Reporting Server is available, because it is a prerequisite for Courtesy Callback 56. WarmTransfer's reading of the sources is that each ingress gateway also needs to reach the PSTN for outbound calls, because the callback is placed through the same ingress gateway the original call arrived on 61 and cannot use any other egress gateway 42. Exclude call flows that transfer to agents using DTMF *8, TBCT or hookflash, because those calls cannot use Courtesy Callback 40. Tell the business that answering machine detection is not available for Courtesy Callback 39. Also tell them that callbacks are best effort: after a limited number of attempts to reach the caller, the callback is terminated and marked as failed 2. If you use Cisco Virtualized Voice Browser instead of a VXML gateway, no special Courtesy Callback configuration is required on it 76.

Verify

Suggested check: for each target queue, write down its queuing path, the ingress gateways its calls arrive on, and the reporting server that will hold callback data.

Step 2 Configure the ingress gateway

Do

Make sure survivability.tcl, along with the other CVP gateway script files, has been copied to the gateway 83. Add the ccb parameter to the cvp-survivability service in the form id:<host name or IP>;loc:<location name>;trunks:<number of callback trunks> 11. Bind the cvp-survivability service to the incoming POTS dial peer for the called number, and add an outgoing POTS dial peer for the PSTN destinations that callbacks will use 12. Under voice service voip, configure signaling forward unconditional so that SIP INFO messages are forwarded 66. Reload the service with call application voice load cvp-survivability 3. Add a sip-profile configuration on the ISR only if you deploy an IOS-XE version affected by CSCts00930 67.

Verify

Suggested check: display the running configuration and confirm that the ccb parameter and both dial peers are present.

Size the trunks value deliberately: an older technote, not re-verified for the current release, says gateway capacity validation fails when the callbacks counted for that gateway (pending, in progress or tentative, plus completed and connected in Callback_Current) reach the ccb trunks value 28. When gateway capacity is exceeded, the caller is not offered a callback and goes straight to queue whatever the EWT, and Validate logs the result none with the EXCEED_CAPACITY_GW bit set 29.

Rollback

Suggested rollback: remove the ccb parameter and the outgoing callback dial peer you added.

Reload the service again with call application voice load cvp-survivability 3.

Step 3 Point Courtesy Callback at the Reporting Server

Unified CCE (CVP administered from the Unified CVP Operations Console)

Do

In the Unified CVP Operations Console, open System > Courtesy Callback 44. On the General tab, select the Reporting Server that stores callback data; leaving it blank associates no Reporting Server with the Courtesy Callback deployment 55. Optionally check "Enable secure communication with the Courtesy Callback database", which secures Call Server to Reporting Server communication for callbacks 64. On the Call Server Deployment tab, move the Call Servers from the Available list to the Selected list and click Save & Deploy 4. Cisco advises deploying later changes to this configuration, such as a different Reporting Server, in a maintenance window, because restarting the Reporting Server can cancel currently scheduled callbacks 33.

Verify

Suggested check: reopen the page and confirm that the selected reporting server and the selected call servers were saved.

Rollback

Clear the Reporting Server selection, which leaves no Reporting Server associated with the Courtesy Callback deployment 55, and deploy the change in a maintenance window 33.

Packaged CCE (CVP administered from Unified CCE Administration)

Do

In Unified CCE Administration, open Overview > Features > Courtesy Callback and set the Reporting Server 45. To script the change instead, the Courtesy CallBack API at /unifiedconfig/config/ccb/{datacenter} reads and updates the CVP Reporting Server address through the reportingAddress parameter 47. Cisco advises deploying later changes, such as a different Reporting Server, in a maintenance window, because restarting the Reporting Server can cancel currently scheduled callbacks 33.

Verify

Suggested check: send a read request to the API and confirm it returns the address you set.

A 201 response means the setting was saved in the AW database but the update failed for one or more CVP devices, and a 503 response means a sync is still in progress 46.

Rollback

Set reportingAddress back to its previous value through the same API 47, in a maintenance window 33.

Step 4 Set the callback dialed-number policy

Only numbers matching patterns you list as allowed

Do

In Packaged CCE, the dialed-number settings are on the same Unified CCE Administration page as the Reporting Server, under Overview > Features > Courtesy Callback 45. Leave "Allow Unmatched Dialed Numbers" unchecked, which is the default and restricts callbacks to numbers in the Allowed Dialed Numbers list 1. Initially there are no allowed dialed numbers, so add patterns for every range you will call back 41. In these patterns, "." and "X" each match a single character in any position 80. The characters ">", "*", "!" and "T" match multiple characters but can only be used at the end of a pattern 81. Optionally set "Maximum Number of Calls Per Calling Number"; the default of 0 means unlimited callbacks, and the maximum is 1000 35.

Verify

Suggested check: confirm that every number range in your callback population matches at least one allowed pattern.

An exact match takes highest precedence, and when an allowed and a denied pattern are equally specific, the denied pattern wins 17.

Rollback

Suggested rollback: remove the allowed patterns you added.

Any number unless it matches a denied pattern

Do

In Packaged CCE, the dialed-number settings are on the same Unified CCE Administration page as the Reporting Server, under Overview > Features > Courtesy Callback 45. Check "Allow Unmatched Dialed Numbers" so that every number not in the Denied list is allowed 1. Review the Denied Dialed Numbers list, which is prepopulated only when the local language is en-us 16. In the patterns you add, "." and "X" each match a single character in any position 80. The characters ">", "*", "!" and "T" match multiple characters but can only be used at the end of a pattern 81. Optionally set "Maximum Number of Calls Per Calling Number"; the default of 0 means unlimited callbacks, and the maximum is 1000 35.

Verify

Suggested check: confirm that the premium-rate, emergency and international ranges you must never dial are covered by denied patterns.

An exact match takes highest precedence, and when an allowed and a denied pattern are equally specific, the denied pattern wins 17. After upgrading CVP from 12.x to 15.0(1) with this box checked, uncheck and save it, re-check and save it on the Courtesy Callback page, then restart the CVP Reporting Server 50.

Rollback

Uncheck "Allow Unmatched Dialed Numbers" to restrict callbacks to numbers in the Allowed Dialed Numbers list again 1.

Step 5 Load the Courtesy Callback media

Do

Unzip %CVP_HOME%\OPSConsoleServer\CCBDownloads\CCBAudioFiles.zip and copy the contents to your media server 38. Courtesy Callback application media goes under en-us\app and Say It Smart media under en-us\sys; if the Say It Smart media is already present, only the en-us\app files are needed 37.

Verify

Suggested check: fetch one application prompt from the media server's en-us/app path in a browser.

Rollback

Suggested rollback: delete the application prompt files you copied.

Step 6 Import and customise the Call Studio projects

Do

Import the 5 Call Studio projects in CourtesyCallbackStudioScripts.zip: BillingQueue, CallbackEngine, CallbackEntry, CallbackQueue and CallbackWait 27. Cisco says not to modify CallbackEngine and CallbackQueue, which keep the VoIP leg alive and handle the in-queue keepalive; BillingQueue, CallbackEntry and CallbackWait are the customisable ones 19. Update each project's Default Audio Path URI with the media server's IP address and port 15. In the CallbackEntry project's Callback_Set_Queue_Defaults node, set the keepalive greater than the length of your queue music; the sample's default is 120 seconds 7. The element's Keepalive Interval setting defaults to 180 seconds, with a minimum of 1 and a maximum of 300 32. Keep Ring No Answer Timeout, which defaults to 30 seconds and ranges 0 to 300, less than the Keepalive Interval 60. Set the required settings Queue Name and Calling Line ID, the CLI used on the callback 58. Review the per-queue caps: Maximum Percentage defaults to 50 with a range of 0-100, and Maximum Count defaults to 9999999 53. Review the retry settings, which take "attempts;interval-seconds" values and default to 3;300 for no response and 4;300 for busy, no answer, trunks busy and error 59.

Verify

Validate all 5 Courtesy Callback projects in Call Studio before deploying them 73.

Rollback

Suggested rollback: re-import the unmodified projects from the original archive.

Step 7 Set the wait-time threshold that triggers an offer

Keep the default of 900 seconds

Do

Leave Maximum Estimated Wait Time in CallbackEntry's Callback_Set_Queue_Defaults at its default of 900; callbacks are offered for the queue only when the EWT is greater than or equal to that number of seconds 36.

Verify

Suggested check: confirm the field still shows its default value.

Set your own threshold in seconds

Do

Set Maximum Estimated Wait Time in CallbackEntry's Callback_Set_Queue_Defaults to your threshold in seconds; callbacks are offered for the queue only when the EWT is greater than or equal to that value 36. Cisco's example callback criteria include an expected queue wait exceeding a maximum number of minutes, an assigned customer status such as gold, or the service the caller requested 13.

Verify

Validate all 5 Courtesy Callback projects in Call Studio again before deploying them 73.

Rollback

Set Maximum Estimated Wait Time back to its default of 900 36.

Step 8 Set the hours when callbacks may be placed

Any time of day, every day (the default)

Do

Leave each Sunday-to-Saturday time range in Callback_Set_Queue_Defaults at its default of 00:00:00-23:59:59 14.

Verify

Suggested check: confirm that every day's range still shows its default value.

Only within time ranges you define for each day

Do

Set each Sunday-to-Saturday time range in Callback_Set_Queue_Defaults to your callback window, and set the value none for any day on which no callbacks are allowed 14.

Verify

Validate all 5 Courtesy Callback projects in Call Studio again before deploying them 73. During the end-to-end test, a call refused outside the window shows the time-of-day failure bit 0x0010 in CallBackQueue.ValidationStatus 74.

Rollback

Restore 00:00:00-23:59:59 on each day 14.

Step 9 Deploy the applications to the VXML Server

Unified CCE (CVP administered from the Unified CVP Operations Console)

Do

Deploy each Courtesy Callback application to the VXML Server by running deployApp.bat from that application's admin folder 18.

Verify

Run status.bat in %CVP_HOME%\VXMLServer\admin to verify that all the Courtesy Callback applications are running on the VXML Server 68.

Rollback

Suggested rollback: redeploy the previous application versions with the same procedure.

Packaged CCE (CVP administered from Unified CCE Administration)

Do

Deploy the Courtesy Callback Call Studio applications to the VXML Server from Unified CCE Administration under Overview > Call Settings > IVR Settings > File Transfers 48.

Verify

Run status.bat in %CVP_HOME%\VXMLServer\admin to verify that all the Courtesy Callback applications are running on the VXML Server 68.

Rollback

Suggested rollback: transfer the previous application archives through the same page.

Step 10 Configure the CCE routing script

Do

Copy the sample routing script CourtesyCallback.ICMS from \CVP\Downloads and Samples\ on the CVP install media to a CCE Admin Workstation 30. Enable the ECC variables user.CourtesyCallbackEnabled, user.microapp.ToExtVXML (an array of up to 5 elements) and user.microapp.FromExtVXML (an array of up to 4 elements) 20. Confirm that the VXML_Server_Interruptible and VXML_Server_Noninterruptible Network VRU scripts exist 75. Set the "Set media server" node to your VXML Server URL, for example http://<ip>:7000/CVP, and map the script's routes and skill groups to your own 65. In Block 3, the sample passes the CallbackEntry application, the EWT, qname=billing, queueapp=BillingQueue and the caller's ANI to the VXML Server through ToExtVXML[0] to ToExtVXML[3], so replace the queue name and queue application with your own 69. Cisco states that Courtesy Callback requires an accurate EWT calculation to behave optimally 22. The sample EWT formula multiplies calls in queue plus 1 by the skill group's average handle time (20 seconds if invalid), divides by the larger of Ready agents and agents talking, and returns 100 if the result is invalid 24. For precision queues, Cisco recommends queuing the call to a single precision queue, avoiding Consider If expressions and using minimal or no wait time between steps 51.

Verify

Import the script into the CCE Script Editor and run its validation tool to find nodes that need extra configuration 63.

Rollback

Suggested rollback: point the call type back to its previous routing script.

Step 11 Test end to end

Do

Place a test call into a queue whose EWT meets your Maximum Estimated Wait Time, because callbacks are offered only then 36. Accept the offer: the caller records a name and gives a number, a database record is written, and only the TDM side of the call is disconnected while the IP call keeps its place in queue 70. Answer the callback: the recorded caller name is played, the CallbackWait application confirms through the IVR that the right person answered, and the caller is briefly queued and connected to an agent with a screen pop 10. Repeat the test without answering the callback to exercise the retry settings, which default to 3;300 for no response and 4;300 for busy, no answer, trunks busy and error 59. After a limited number of attempts, the callback is terminated and marked as failed 2.

Verify

Callback_Validate exits with preemptive when the callback is valid, none when it is not allowed, refresh when the DBServlet needs a reference-data refresh so SetQueueDefaults must run first, or error 72. Its element data records result, ewt (the EWT passed from Unified ICM), gw, loc and capacity 71. If a call was refused, decode CallBackQueue.ValidationStatus: 0x0001 is OK, 0x0010 a time-of-day failure, 0x0020 an EWT failure, 0x0100 EXCEED_CAPACITY_GW and 0x0200 EXCEED_CAPACITY_QUEUE 74.

Rollback

Suggested rollback: point the call type back to its previous routing script.

Step 12 Set up callback reporting

Do

Import the Pending Callbacks report, which covers the last 30 minutes, and the Historical Callbacks report for older callbacks from CVP's Unified Intelligence Center templates 49. Set the callback database as their data source, otherwise an error occurs 57. The CallBack, CallBackEvent and CallBackQueue tables live in a separate callback database on the Reporting Server because of their OLTP nature 5. The CallBack table is a view over Callback_Current and Callback_Historical, and data moves from current to historical every 30 minutes 6. The CallBackEvent table keeps 7 days of data and is purged daily 8. When a caller cannot be reached after the retries, the callback is aborted and its database status updated, and these reports can be run to decide whether manual callbacks are needed 34.

Verify

Suggested check: confirm that your test calls from the previous step appear in the reports.

Callback event types in EventTypeRef are 20 Canceled, 21 Pending, 22 In Progress, 23 Tentative, 24 Complete, 25 Recover, 26 Created, 27 Dropped from queue, 28 Added to queue and 29 Max allowed callbacks to this ANI exceeded 21.

Rollback

Suggested rollback: remove the imported reports.

Applicability

Applies to: Cisco Unified Customer Voice Portal, Cisco Packaged Contact Center Enterprise, and Cisco Unified Customer Voice Portal 12.5. Deployments: on-premises. Sources checked 2026-10-01. As of 2026-09-24, Cisco's CVP support page lists 15.0(1), released 30 April 2025, as the latest Unified CVP release 84. Unified CVP 12.5(1), 12.6(1) and 12.6(2) are Not Orderable, with End-of-Support on 31 December 2027 85. Cisco's 12.5/12.6 end-of-life bulletin covers CVP among its on-premises contact center applications 86 and encourages customers to move to version 15 or higher 87. Packaged CCE is a predesigned, bounded deployment model of Unified CCE that uses the browser-based Unified CCE Administration interface 88.

What remains uncertain

Courtesy Callback configuration on a VXML gateway, as opposed to Cisco Virtualized Voice Browser, is not covered by the sources below. Which IOS-XE versions are affected by CSCts00930 is not covered by the sources below. Whether callback dialing rules on permitted hours, consent or caller ID apply to courtesy callbacks is not covered by the sources below.