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,

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": "[email protected]"
    },
    "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.