How can we help?

Note: This feature is currently in Preview for select customers.

Index

• Overview
• Example Use Cases
• Prerequisites
• Required Information
• Workflow Steps
• Best Practices
• Managing Scheduled Callbacks
• Agent Experience
• Reporting and Analytics

Overview

This article explains how to use the callback scheduling API to automatically create a callback from a website, bot, automation flow, or other external system. This lets you capture a customer’s preferred callback time and route it into Talkdesk without requiring an agent on an active call to schedule it manually. 

For more information, please consult our Scheduled Callbacks API documentation.

Use Cases

• A website form lets a customer request a callback for a specific date and time.
• An AI assistant collects callback preferences in a digital conversation and submits them automatically.
• A backend workflow schedules a follow-up after a support interaction.
• A business process creates callbacks without requiring an agent to manually enter them.

Prerequisites

Make sure you have:

• Scheduled Callbacks installed for your account.
• A valid API token with the required scope schedule-callbacks:write.
• A valid assignment target, such as specific agent(s) or queue(s)/ring group(s).

Required Information

When creating a scheduled callback through the API, include the following information:

• Contact phone number: The number to call back in E.164 format.
• Scheduled time to call: The exact date and time for the callback in the UTC timezone.
• Timezone: Used to interpret the scheduled time correctly.
• Assignment type: The agent or ring group that should handle the callback.
• Assignee(s): The specific agent(s) or ring group(s).
• Caller ID: The number will be used to place the callback.
• Dialing mode: Use “PREVIEW”.
• Interaction ID: Leave it blank or optionally provide a valid interaction ID if you want to link the callback to a previous interaction.
• Notes: Optional context for the agent.

Workflow Steps

The suggested workflow:

1. Collect the customer’s callback details on your website, form, bot, or workflow.
2. Send a request to the callback scheduling API.
3. Confirm that the API returns a successful response.
4. Show a confirmation message to the customer or continue your automation flow.
5. Verify the callback appears in the Callback Manager if you need to review or manage it later.

Best Practices

• Use a clear timezone: Always capture the customer’s timezone in the supported format. This helps ensure the callback is scheduled at the intended local time. A useful way is to capture the timezone from the customer's ip address as the default timezone (there are a lot of useful free and enterprise options) and let the customer confirm or override it.
• Prevent invalid requests: Always ensure callbacks are not scheduled for a past time, via an invalid caller ID or assigned to agent(s) or queue(s)/ring group(s) that cannot receive it. Requests must have a minimum lead time of at least 1 minute from the time the request is sent.
• Avoid duplicated callbacks: Before submitting the callback scheduling request, use the Get Scheduled Callbacks endpoint to check if there are any active callbacks for this phone number in the system to avoid duplications. To update a previously scheduled callback, use Update a Callback endpoint.
• Provide useful notes: Add short notes when possible so agents have context when they receive the callback. If you link the callback to a prior interaction, the related notes may be used automatically.
• Keep the schedule realistic: The callback may not begin at the exact second requested. It will be launched when an agent becomes available, so allow for some flexibility in your customer messaging.

Managing Scheduled Callbacks

Once a callback is created, supervisors can manage it in the Callback Manager. API-created callbacks are marked with API as the origin.

Agent Experience

When an agent handles a callback created through the API:

• It appears in the callback flow like a regular scheduled callback.
• The agent can make the call, reschedule it, or cancel it.
• The callback thread may show the callback as API-originated.
• Any notes you send can appear as context for the agent.

If the callback is linked to a previous interaction, the agent can also see that context.

Reporting and Analytics

API-created callbacks are included in scheduled callback reporting and datasets, with the origin marked with API. This allows supervisors to review performance and volume alongside callbacks created through other channels.