---
title: "Scheduled callbacks"
slug: "docs-scheduled-callbacks"
updated: 2024-10-25T15:16:25Z
published: 2024-10-25T15:16:25Z
canonical: "docs.voiso.com/docs-scheduled-callbacks"
---

> ## Documentation Index
> Fetch the complete documentation index at: https://docs.voiso.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Scheduled callbacks

Use the **scheduled_callbacks** API to create a scheduled callback from a third-party application, such as a CRM. Agents are identified by their email in the agent field. A callback is a phone call scheduled to occur in the future.

Benefits of scheduled callbacks:

- Allows agents to prepare for calls in advance.
- Ensures contacts are called at their preferred time.
- Helps agents manage call volumes during peak hours by scheduling calls for off-peak times.

Please refer to the detailed API endpoint specification [here](/v1-api/apidocs/scheduled-callbacks).

## Prerequisites

- The **Scheduled Callback** feature must be activated for your contact center.
- The **Scheduled Callback** feature must be enabled in the [System Settings](https://docs.voiso.com/v1/docs/administration-system-settings#scheduled-callback) for your contact center.
- The **Scheduled Callback** feature must be enabled for agents. To do this, select the **Enable Scheduled Callback** permission for the [security access group](https://docs.voiso.com/docs/administration-security-access-groups#outbound) (roles) that will use the feature.
- The agent must be [logged in](https://docs.voiso.com/docs/agent-panel-getting-started#login).
- The agent's status must be [Available](https://docs.voiso.com/docs/agent-panel-getting-started#status-menu).

## Making requests

### Authentication

The **create_scheduled_callbacks** API requires the [base URL](/v1-api/apidocs/base-endpoint) and the [contact center API key](/v1-api/apidocs/authentication).

### Request parameters

The **create_scheduled_callbacks** API uses the [contact center API key](/v1-api/apidocs/authentication) in the `Authorization: Bearer token` in the **header**.

| Parameter | Description | Type | Required | Notes |
| --- | --- | --- | --- | --- |
| contact_number | Phone number for the callback | string | Required | Must be in [E.164 format](https://www.itu.int/rec/T-REC-E.164) without the preceding '+'. For example: `447414992548` |
| agent | The email address of the agent handling the callback. | string | Required | Must match the email address the agent uses to sign in to Voiso. For example: `name@email.com`. It tells Voiso which agent should get the call. The call starts automatically on the agent's configured Web-RTC softphone, known as **Agent Panel** at the designated time. |
| scheduled_time | The time of the scheduled callback. | string | Required | Must be in ISO 8601 format. Only 00 and 30 are accepted for minutes. Time is UTC +0. For example: `2024-06-30T10:30:00Z`. |
| time_zone | The time zone of the contact. | string | Optional | Used to determine whether the callback occurs between 0800h and 2200h in the contact's time zone. Calls outside this window are rejected. The default is the agent's time zone. For example, `America\Halifax`. Refer to [IANA](https://www.iana.org/time-zones) for a list of supported values. |
| context_notes | Information about the call for the agent. | string | Optional | Maximum 64 characters. |
| cid_group | The Caller ID group for the callback. | string | Optional | The default Caller ID for the contact center is used by default. Refer to [Caller ID groups](https://docs.voiso.com/docs/outbound-cid-groups) for more information. |
| related_call_id | The UUID of a call related to the callback. | string | Optional | You can use the [CDR](/v1-api/apidocs/call-detail-records-cdr) to retrieve the UUID of an existing call. |
| external_contact_id | The ID of the contact in an external CRM. | string | Optional |  |
| external_system_id | The name of the external CRM. | string | Optional |  |

          Important

          

You may only schedule a callback within the next 30 days. Callback times are restricted to 08:00 to 22:00, using 30-minute intervals.

Here is an example of a complete request:

```
{
  "method": "POST",
  "url": "https://cluster1.voiso.com/api/task/v1/scheduled_callbacks",
  "headers": {
    "Authorization": "Bearer 8a7b2c9d3e4f5g6h7i8j9k0l1m2n3o4p5q6r7s8t9u0v1w2x",
    "Content-Type": "application/json"
  },
  "body": {
    "contact_number": "15065555555",
    "agent": "myagent@example.com",
    "scheduled_time": "2024-06-20T15:00:00Z",
    "time_zone": "America/Halifax",
    "context_notes": "Interested in the transplant procedure.",
    "cid_group": "Sales North America",
    "related_call_id": "123e4567-e89b-12d3-a456-426614174000",
    "external_contact_id": "49563892",
    "external_system_id": "My CRM"
  }
}
```

## Response

If a scheduled callback is successfully created, an ID for the interaction is returned. You can use this ID to get information about the call using the [CDR](/v1-api/apidocs/call-detail-records-cdr) API.

## Troubleshooting

The following issues are sometimes encountered:

### Not found

If you see a 404 error , `"error": "Not found"`, the specified contact center was not found or the Scheduled Callback feature is not activated for the contact center. If you want to activate the Scheduled Callback feature for your contact center, contact your Voiso account representative.

### Scheduled Callbacks feature is disabled

If you see this error, `"error": "Scheduled Callbacks feature is disabled"`, the **Scheduled Callback** feature must be enabled by an admin in the [System Settings](https://docs.voiso.com/v1/docs/administration-system-settings#scheduled-callback) for your contact center.

### Agent does not have access

If you see this error, `"error": "Agent does not have access"`, the **Scheduled Callback** feature must be enabled for the agent. To do this, an admin must select the **Enable Scheduled Callback** permission for the [security access group](https://docs.voiso.com/docs/administration-security-access-groups#outbound) (roles) that will use the feature.

### Invalid agent login ID

The **scheduled_callbacks** API uses the agent's login ID to identify the user who is making the click-to-call request. If you see this error, the value specified for the `agent` parameter is invalid.

### Agent logged off

If you see this error,`"error": "Agent logged off"`, the target agent is not logged in to their softphone. Ensure that agents are [logged in](https://docs.voiso.com/docs/agent-panel-getting-started#login) to their Voiso account.

### The API key specified is invalid

The **scheduled_callbacks** API uses the contact center API key to validate the request. If you see this error, `"error": "The API key specified is invalid"`, check that you use the correct contact center API key. For more information about API keys, refer to [Authentication](/v1-api/apidocs/authentication).

### Phone number is missing

If you see this error,`"error": "contact_number": "phone number is missing"`, the `contact_number` parameter has no value. Add a valid phone number in E.164 format. Verify the phone number is correct and in the correct format without the preceding '+'. For example: `447414992548` .

### Incorrect phone number

If you see this error,`"error": "contact_number": "incorrect phone number"`, the phone number provided for the `contact_number` parameter is not a valid phone number in E.164 format. Verify the phone number is correct and in the correct format without the preceding '+'. For example: `447414992548` .

### Agent is missing

If you see this error,`"error": “agent”: “agent is missing”`, the `agent` parameter has no value.

### Email address does not exist

If you see this error,`"error": “agent”: - “[email address] does not exist”`, the login ID for the specified agent does not exist in the contact center. Check the email address for the specified agent. You can use the [Users](/v1-api/apidocs/user-management) API to retrieve a list of agent email addresses.

### Time zone is not included in the list

If you see this error,`"error": “time_zone”: “is not included in the list”`, verify that you are using the correct time zone name from the list found at the [IANA](https://www.iana.org/time-zones) website.

### Scheduled time incorrect format

If you see this error,`"error": “scheduled_time”: “incorrect format. Use YYYY-MM-DDThh:mm:ssTZD (iso8601)”`, ensure that the time you specify for the `scheduled_time` parameter follows the [ISO 8601](https://www.iso.org/iso-8601-date-and-time-format.html) standard format like this: YYYY-MM-DDThh:mm:ssTZD, where YYYY is the year, MM is the month number, DD is the day number, hh is the hour using the 24-hour clock, mm is minutes and is either 00 or 30, and ss is seconds and is 00.

### Scheduled time should be in the future

If you see this error,`"error": “scheduled_time”: “should be in the future, but less than 30 days from now”`, the time that was specified for the `scheduled_time` parameter is either in the past or is more than 30 days in the future. You may only schedule callbacks for up to 30 days in the future.

### Scheduled time can't be blank

If you see this error,`"error": “scheduled_time”: “can't be blank”`, enter a valid time following the [ISO 8601](https://www.iso.org/iso-8601-date-and-time-format.html) standard format. The time must be up to 30 days in the future and may only be on the hour or half-hour.

### Scheduled time hours should be between 08 and 22 hours in the specified time zone

If you see this error, `"error": "Scheduled time hours should be between 08 and 22 in the specified time zone"`, enter a time between 08h and 22h.

### Scheduled time minutes should be either 00 or 30

If you see this error, `"error": "Scheduled time minutes should be either 00 or 30"`, enter either 00 or 30 for minutes. Only scheduled callbacks on the hour and half-hour are supported.

### Scheduled time minutes should be either 15 or 45

If you see this error, `"error": "Scheduled time minutes should be either 15 or 45"`, enter either 15 or 45 for minutes. For specific time zones, such as Kathmandu (UTC+05:45), only scheduled callbacks on the quarter- and three quarter-hours are supported.

### Scheduled time seconds should be 00

If you see this error, `"error": "Scheduled time seconds should be 00"`, enter 00 for seconds. Scheduled Callbacks does not support scheduling by the second.

### Context notes is too long

If you see this error,`"error": “context_notes”: “is too long (maximum is 64 characters)”`, the text that is specified for the `context_notes` parameter exceeds the 64 character limit.

### Too many requests

If you see this error, `"error": "Too many requests"`, the number of permitted requests to the server is exceeded, and requests are being throttled.