The Create scheduled callback endpoint creates a callback task for an agent at a scheduled time. This is useful when you want to schedule callbacks from a third party system, such as a CRM.

Requirements: Base URL, Authentication, Error codes

Scope: tasks.scheduled_callbacks.manage

What this does

When you send a Create scheduled callback request, Voiso creates a scheduled callback task for the specified agent.

If the request is accepted, the API returns a scheduled_callback object that includes the callback ID and current status.

When to use it

Schedule a callback for an agent from a CRM or ticketing tool
Follow up with a contact at a specific time
Create a callback linked to a previous call

Prerequisites

Scheduled callbacks must be enabled for your contact center.
The agent must have permission to use scheduled callbacks.
The agent must be signed in when the callback is due.

Endpoint


POST /api/v4/tasks/scheduled_callbacks

Request body

Required fields

user_id
The agent ID in the contact center (UUID).
scheduled_at
Date and time when the callback is scheduled to be placed (ISO 8601).
destination
Where the callback should go. This is a typed object. See Destination types.

Optional fields

caller_id_group_id
Caller ID group to use for the callback.
timezone
IANA time zone used to interpret scheduled_at when a local time is provided.
note
Notes for the agent. Maximum length is 64 characters.

Destination types

The destination object must include a type and the fields required by that type:

phone_number
Use when you want to schedule a callback to a specific phone number.
related_call
Use when you want to create the callback in relation to an existing call.
external_system
Use when you want to store external system metadata for the callback.

Examples

Schedule a callback to a phone number

curl -X POST "https://{cluster_id}.voiso.com/api/v4/tasks/scheduled_callbacks" \
  -H "Authorization: Bearer <contact_center_api_key>" \
  -H "Content-Type: application/json" \
  -d '{
    "user_id": "0b97ce11-b6e0-49b4-8f92-68040aa324bf",
    "scheduled_at": "2025-12-12T10:00:00Z",
    "destination": {
      "type": "phone_number",
      "phone_number": "18885658889"
    },
    "note": "Follow up call"
  }'

Schedule a callback related to an existing call

curl -X POST "https://{cluster_id}.voiso.com/api/v4/tasks/scheduled_callbacks" \
  -H "Authorization: Bearer <contact_center_api_key>" \
  -H "Content-Type: application/json" \
  -d '{
    "user_id": "0b97ce11-b6e0-49b4-8f92-68040aa324bf",
    "scheduled_at": "2025-12-12T10:00:00Z",
    "caller_id_group_id": 1,
    "destination": {
      "type": "related_call",
      "call_id": "54ae2354-2f6e-485a-bad5-dbdf1463ea2d"
    }
  }'

Schedule a callback with external system metadata

curl -X POST "https://{cluster_id}.voiso.com/api/v4/tasks/scheduled_callbacks" \
  -H "Authorization: Bearer <contact_center_api_key>" \
  -H "Content-Type: application/json" \
  -d '{
    "user_id": "0b97ce11-b6e0-49b4-8f92-68040aa324bf",
    "scheduled_at": "2025-12-12T10:00:00Z",
    "timezone": "Europe/Riga",
    "destination": {
      "type": "external_system",
      "system": "mycrm",
      "account_id": "ACC01"
    }
  }'

Response

If successful, the API returns the created scheduled callback.

{
  "scheduled_callback": {
    "id": 149,
    "phone_number": "18885658889",
    "scheduled_at": "2025-12-12T12:00:00.000+02:00",
    "user": {
      "id": "0b97ce11-b6e0-49b4-8f92-68040aa324bf",
      "name": "Jane Doe",
      "email": "jane.doe@contactcenter.com"
    },
    "caller_id_group": {
      "id": 1,
      "name": "Default"
    },
    "note": "Follow up call",
    "related_call": null,
    "source": {
      "system": "zoho",
      "account_id": "ACC01"
    },
    "status": "pending"
  }
}

Notes

scheduled_at must be a valid ISO 8601 timestamp.
Time and availability rules may be enforced by contact center configuration. If a requested time is not allowed, the API returns a validation error.

Troubleshooting

401 Unauthorized

What to check:

You are sending Authorization: Bearer <contact_center_api_key>.
Your Base URL includes the correct {cluster_id}.

403 Forbidden

Common causes:

Scheduled callbacks are not enabled for the contact center.
The agent does not have permission to use scheduled callbacks.

What to check:

Scheduled callbacks are enabled in the contact center configuration.
The agent’s security access group has scheduled callbacks enabled.

422 Unprocessable Entity

The request is well formed JSON, but one or more fields failed validation.

Common causes:

user_id is missing, not a UUID, or does not match an existing user.
scheduled_at is missing or not a valid ISO 8601 timestamp.
destination.type is missing or invalid.
Destination fields do not match the selected destination.type.

429 Too many requests

What to do:

Reduce request frequency and retry with backoff.

201Created

400Bad Request

401Unauthorized

403Forbidden

422Unprocessable Entity

429Too many requests