Callback calls are calls that are requested by an end-user. With the callback call API, you can programmatically schedule callback calls and cancel scheduled calls. With these capabilities, you can create applications that let end-users request callback calls from a queue that you specify. End-users can also cancel calls that they previously scheduled. For information about authentication with the callback call API, see Basic authentication.
Use the callback call API
You can use the callback call API to schedule callback calls and cancel scheduled calls.
Schedule a call
To schedule a call, call POST https://<subdomain>.<domain>/apps/api/v1/calls
and include a request body similar to the following:
{
"call_type": "ScheduledCall",
"menu_id": 12345,
"end_user_number": "+18005550100",
"scheduled_at": "2025-09-02T14:30:00Z"
}
A successful request returns a call object, including the call ID.
Cancel a scheduled call
To cancel a scheduled call, call PATCH
https://<subdomain>.<domain>/apps/api/v1/calls/scheduled/{id}/cancel. Specify
the ID of the call that you want to cancel.
A successful request returns information about the canceled call.
Cancel multiple scheduled calls
To cancel multiple scheduled calls, call PATCH
https://<subdomain>.<domain>/apps/api/v1/calls/scheduled/cancel. Include a
request body that contains a call_ids array of the call IDs for the calls to
be canceled.
See the following code sample:
{
"call_ids": [123, 456, 789]
}
A successful request returns a response with a response header that contains
a Location URL for checking the status of the cancellation.
Use callback calls with CRMs
You can use the callback calls API with Salesforce, Zendesk, and ServiceNow CRM integrations.
General callback behavior
If you're using any supported CRM (Salesforce, Zendesk, or ServiceNow), the following conditions affect scheduled callback behavior:
A record is open and already has an active scheduled call: If a ticket ID lookup indicates that the record is open and already has an active scheduled call, the call isn't scheduled. The following comment is attached to the CRM record:
A scheduled call was not created because the record already has an active scheduled call.The CRM can't be reached: If a ticket ID lookup indicates that the CRM can't be reached, the call is canceled. The following comment is attached to the CRM record:
A scheduled call was canceled because the CRM was unreachable.
Callback behavior with closed records
The way callback calls are handled for closed records varies depending on which CRM you're using:
Zendesk and ServiceNow users: If a ticket ID lookup indicates that the record is closed, the call isn't scheduled. The following comment is attached to the CRM record:
A scheduled call was not created because the record is closed.Salesforce users: See Callback calls with Salesforce to configure how your instance handles scheduled calls for closed records.
Callback calls with Salesforce
If you've integrated CCAI Platform with Salesforce, you can configure how your instance handles scheduled calls for closed records. Here are the configuration options for Salesforce integrations:
Don't check the record status
You can configure CCAI Platform so that it doesn't check the record status before making a scheduled call. With this configuration, the call is made as scheduled regardless of whether the record is open or closed.
To configure CCAI Platform to not check the record status, follow these steps:
In the CCAI Platform portal, click Settings > Operation Management. If you don't see the Settings menu, click Menu.
Go to CRM Record Creation Details > Closed record options when initiating an API-scheduled call.
Select Don't check the record status. Always initiate the API-scheduled call.
Click Save General.
Check the record status and reopen closed records
You can configure CCAI Platform to check the record status before making a scheduled call and reopen records that are closed. With this configuration, if the record status is closed, the following actions take place:
The call is made as scheduled.
The record is reopened.
The following comment is attached to the CRM record:
The record was reopened at the time of a scheduled call.
To configure CCAI Platform to check the record status and reopen closed records, follow these steps:
In the CCAI Platform portal, click Settings > Operation Management. If you don't see the Settings menu, click Menu.
Go to CRM Record Creation Details > Closed record options when initiating an API-scheduled call.
Select Check the record status. If the record is closed > Reopen the record.
Click Save General.
Check the record status and cancel scheduled calls for closed records
You can configure CCAI Platform to check the record status before making a scheduled call and cancel scheduled calls for records that are closed. With this configuration, if the record status is closed, the following actions take place:
The scheduled call is canceled.
The following comment is attached to the CRM record:
A scheduled call was canceled because the record is closed.
To configure CCAI Platform to check the record status and cancel scheduled calls for closed records, follow these steps:
In the CCAI Platform portal, click Settings > Operation Management. If you don't see the Settings menu, click Menu.
Go to CRM Record Creation Details > Closed record options when initiating an API-scheduled call.
Select Check the record status. If the record is closed > Cancel the scheduled call.
Click Save General.