Queue

QueueAction holds the caller in one of your queues until an agent answers, the caller hangs up, or maxWaitTime is reached. Queue is not a terminal verb.

2026-06-27

QueueAction holds the caller in one of your queues until an agent answers, the caller hangs up, or maxWaitTime is reached. Queue is not a terminal verb. Actions after it run when the caller leaves the queue, however that happened — which is how an unanswered caller reaches voicemail. If the queue is already at maxDepth the caller is not held at all, and the next action runs immediately. There is no limit on how long a caller can wait, and when an agent hangs up the next caller reaches them in about 170ms.

Parameter	Type	JSON key	Required	Description
`Name`	`string`	`name`	Yes	Name is the queue to join. Required, and deliberately BARE: there is no tenant attribute on this verb, because the PBX reads the workspace off the authenticated channel. If a callback could name the tenant, one workspace could park its caller in another workspace's queue. Constrained to [A-Za-z0-9._-] by validate — see ErrQueueName.
`WaitURL`	`string`	`waitUrl`	No	WaitURL is the hold audio played while the caller waits. Use a stable URL served with cache headers, or leave it empty and set the hold audio on the queue itself. Hold audio is cached by URL, so a URL that changes per call is downloaded again on every join, which delays the caller being placed in the queue. If the audio cannot be played the caller hears the queue's own hold audio, or a tone — never silence.
`CallerID`	`string`	`callerId`	No	CallerID is the number shown to the agent when the queue offers them the call. Set it to the caller's number so whoever answers knows who they are about to speak to, and can call back if the line drops. Only applies to queues whose agents are all your own devices. On a queue that can ring an outside number the switch ignores it, so a caller's number is never presented on an external leg.
`AnnounceVoice`	`string`	`announceVoice`	No	AnnounceVoice is the Google Cloud text-to-speech voice used for position announcements. Empty uses the default, en-GB-Standard-F. Google publishes no Kenyan, South African or Nigerian English voice, so en-GB-Standard-F is the closest neutral choice for the region. Swahili voices such as sw-KE-Chirp3-HD-Achernar are available, but a position announcement needs spoken numbers and those are not available in Swahili yet. Letters, digits and hyphens only. A value outside that is rejected rather than corrected — see ErrQueueAnnounceVoice.

res.json({
actions: [
  { queue: { name: "support", waitUrl: "https://cdn.example.com/audio/hold.mp3", announceVoice: "en-GB-Standard-F" } },
  { redirect: { url: "https://your-app.example.com/voice/queue-timed-out" } },
],
});

{
"actions": [
  {
    "queue": {
      "name": "support",
      "waitUrl": "https://cdn.example.com/audio/hold.mp3",
      "announceVoice": "en-GB-Standard-F"
    }
  },
  {
    "redirect": {
      "url": "https://your-app.example.com/voice/queue-timed-out"
    }
  }
]
}

<Queue waitUrl="https://cdn.example.com/audio/hold.mp3" announceVoice="en-GB-Standard-F">support</Queue>

Parameter

Type

JSON key

Required

Description

Name

string

name

Yes

Name is the queue to join. Required, and deliberately BARE: there is no tenant attribute on this verb, because the PBX reads the workspace off the authenticated channel. If a callback could name the tenant, one workspace could park its caller in another workspace's queue. Constrained to [A-Za-z0-9._-] by validate — see ErrQueueName.

WaitURL

string

waitUrl

WaitURL is the hold audio played while the caller waits. Use a stable URL served with cache headers, or leave it empty and set the hold audio on the queue itself. Hold audio is cached by URL, so a URL that changes per call is downloaded again on every join, which delays the caller being placed in the queue. If the audio cannot be played the caller hears the queue's own hold audio, or a tone — never silence.

CallerID

string

callerId

CallerID is the number shown to the agent when the queue offers them the call. Set it to the caller's number so whoever answers knows who they are about to speak to, and can call back if the line drops. Only applies to queues whose agents are all your own devices. On a queue that can ring an outside number the switch ignores it, so a caller's number is never presented on an external leg.

AnnounceVoice

string

announceVoice

AnnounceVoice is the Google Cloud text-to-speech voice used for position announcements. Empty uses the default, en-GB-Standard-F. Google publishes no Kenyan, South African or Nigerian English voice, so en-GB-Standard-F is the closest neutral choice for the region. Swahili voices such as sw-KE-Chirp3-HD-Achernar are available, but a position announcement needs spoken numbers and those are not available in Swahili yet. Letters, digits and hyphens only. A value outside that is rejected rather than corrected — see ErrQueueAnnounceVoice.

res.json({
actions: [
  { queue: { name: "support", waitUrl: "https://cdn.example.com/audio/hold.mp3", announceVoice: "en-GB-Standard-F" } },
  { redirect: { url: "https://your-app.example.com/voice/queue-timed-out" } },
],
});

{
"actions": [
  {
    "queue": {
      "name": "support",
      "waitUrl": "https://cdn.example.com/audio/hold.mp3",
      "announceVoice": "en-GB-Standard-F"
    }
  },
  {
    "redirect": {
      "url": "https://your-app.example.com/voice/queue-timed-out"
    }
  }
]
}

<Queue waitUrl="https://cdn.example.com/audio/hold.mp3" announceVoice="en-GB-Standard-F">support</Queue>