Please refer to the detailed API endpoint specification: Create scheduled callback

Purpose

To schedule a callback, use a Create scheduled callback request to your Voiso contact center. Use this 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.

Prerequisites

The Scheduled Callback feature must be activated for your contact center.
The Scheduled Callback feature must be enabled in the System Settings 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 (roles) that will use the feature.
The agent must be logged in.
The agent's status must be Available.

Making requests

Authentication

The create_scheduled_callbacks API requires the Base URL and the contact center API key.

Request parameters

The create_scheduled_callbacks API uses the contact center API key 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 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 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 for more information.
related_call_id	The UUID of a call related to the callback.	string	Optional	You can use the List CDRs 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

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.contact_center_name.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 List CDRsAPI.

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 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 (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 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.

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 List users 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 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 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 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.