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.

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.

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.

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

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

Scheduled time should be from 08:00 to 21:59 in the specified time zone

If you see this error, "error": “scheduled_time”: “should be from 08:00 to 21:59 in the specified time zone”, enter a time from 08:00 to 21:59 in the contact's time zone.

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.