The queue status endpoint

The queue status endpoint provides real-time data for leaf queues, including estimated wait times, agent availability, callback slot capacity, hours of operation, and holidays. This lets voice AI systems dynamically decide whether to escalate a call to a live agent or offer scheduled callback windows to the caller. For more information, see Queue status.

Queue status endpoint workflow

The queue status endpoint is exposed through the apps API and is designed to be called by trusted server-side applications such as voice AI platforms or orchestration services.

Here is the queue status endpoint workflow at a high level:

  1. Your app sends a request to the queue status endpoint with the following information:

    • One or more queue IDs.

    • A language code.

    • Optional callback window parameters, which determine how far into the future to calculate callback time slots.

  2. The request returns the following information:

    • Real-time queue metrics: Estimated wait time (EWT), calls in queue.

    • Agent metrics: Logged in, available, breakthrough.

    • Callback capacity estimation.

    • Queue configuration: Hours of operation (hoops), holidays.

  3. Your app uses the information to decide to do the following:

    • Route to a live agent if EWT and agent availability are acceptable.

    • Offer a callback and show the next available callback time slots.

Use cases

Although the queue status endpoint doesn't directly modify CRM records, it is commonly used by voice AI systems or orchestration systems that integrate with external platforms such as Salesforce, Zendesk, or ServiceNow. This section describes some typical use cases.

Real-time transfer decision

Here's a real-time transfer decision workflow:

  1. Your voice AI system calls /apps/api/v1/queues/status to get EWT and agent availability.

  2. If EWT is within an acceptable threshold and there are available agents, the voice AI system transfers the call to the queue.

  3. If EWT is too high or there are no available agents, the voice AI system instead offers a callback and uses the callback periods to present time options.

Callback scheduling helper

Here's a callback scheduling helper workflow:

  1. Before presenting callback options, your system calls the queue status endpoint to get the following:

    • Valid callback slots

    • Hours of operation and holiday context

  2. Your application calls the relevant Apps API callback creation endpoints, using only the time slots that the queue status endpoint has confirmed as available.

Holiday and after-hours behavior

When the queue status endpoint indicates that the queue is outside of hours of operation or on holiday, the voice AI system can do either of the following:

  • Offer only callbacks at valid future times.

  • Provide a tailored message—for example, "We're closed now, here are the next available callback times."

Any CRM-specific logic (for example, what to do if a ticket is closed, or whether to create or update a record before scheduling a callback) is handled in your integration or with other apps API capabilities. The role of the queue status endpoint is to supply the queue-side capacity and timing information.