List scheduled callbacks

Returns a paginated list of all callbacks of the Callcenter, of all three types, ordered from newest to oldest. Requires the tasks.scheduled_callbacks.read scope. The list works with "Enable agent callback" on or off in System settings.

The product calls a callback to one agent "Agent callback". Paths, scope names and operation names of this API keep the older name "scheduled callback".

The type field tells the three types apart:

  • agent_callback: an Agent callback, a callback to one agent, booked by that agent or through this API.
  • in_queue_callback: an In-queue callback. A caller waiting in a queue presses 2 to get a call back, and the first try starts five minutes later.
  • api_queue_callback: an API queue callback, booked to a queue through this API for a chosen time.

In-queue callbacks and API queue callbacks are both Queue callbacks. The queue strategy picks the agent at each try, and tries follow the "Queue callbacks" group in System settings. No try of a Queue callback starts from 22:00 to 08:00 in its time zone: such a try moves to the next 08:00.

The List scheduled callbacks endpoint returns scheduled callback tasks created in your contact center.

Requirements: Base URL, Authentication, Error codes

Scope: tasks.scheduled_callbacks.manage

What this does

When you send a List scheduled callbacks request, Voiso returns a paginated list of scheduled callback objects.

When to use it

  • Show upcoming callbacks in a CRM or admin tool
  • Sync callback tasks into an external system
  • Retrieve callback IDs to use with Get scheduled callback

Prerequisites

  • Scheduled callbacks must be enabled for your contact center.

Endpoint


GET /api/v4/tasks/scheduled_callbacks

Query parameters

All query parameters are optional.

  • limit
    The number of items to return. Default is 100. Maximum is 100.
  • offset
    The number of items to skip before collecting results. Default is 0.

Examples

Minimal request

curl -X GET "https://{cluster_id}.voiso.com/api/v4/tasks/scheduled_callbacks" \
  -H "Authorization: Bearer <contact_center_api_key>" \
  -H "Content-Type: application/json"

Request the third page of results (20 per page)

curl -X GET "https://{cluster_id}.voiso.com/api/v4/tasks/scheduled_callbacks?limit=20&offset=40" \
  -H "Authorization: Bearer <contact_center_api_key>" \
  -H "Content-Type: application/json"

Response

If successful, the API returns an array of scheduled callback objects and pagination metadata.

{
  "scheduled_callbacks": [
    {
      "id": 149,
      "phone_number": "18885658889",
      "scheduled_at": "2025-12-12T12:00:00.000+02:00",
      "user": {
        "id": "1234",
        "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"
    }
  ],
  "metadata": {
    "total": 100
  }
}

Notes

  • scheduled_at is returned in ISO 8601 format.
  • note, related_call, and source can be null if they were not provided when the callback was created.

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.
  • Your API key does not have access to scheduled callback resources.

429 Too many requests

What to do:

  • Reduce request frequency and retry with backoff.
Query Params
integer
≥ 0
Defaults to 0

The number of items to skip before starting to collect the result set.

integer
0 to 100
Defaults to 100

The number of items to return.

Responses

Language
Credentials
Bearer
URL
LoadingLoading…
Response
Click Try It! to start a request and see the response here! Or choose an example:
application/json