Position Announcements

Position announcements tell a waiting caller where they are in line (“you are caller number 3”). SIP.IO’s implementation is push-based and change-aware, so it stays accurate without ever turning hold music into a stutter of repeated numbers.

How it works

When announcements are enabled on a queue, the per-account PresenceDO arms an alarm for each waiting caller:

• The first announcement fires after announce_first_sec (default 15s).
• It then re-fires every announce_interval_sec (default 30s).
• An announcement is spoken only when the caller’s position has actually changed since the last one.

The audio is pushed to the caller’s edge node via the position op on the node-agent channel, which breaks the hold audio to speak and then resumes it. Because the brain pushes only on a real, changed position, rather than the edge polling on a timer, there’s no recurring gap in the music from announcements that say nothing new.

caller enqueues ──▶ alarm @ announce_first_sec
                     │  position changed?  ── no ──▶ stay quiet, re-arm
                     │            └─ yes ──▶ push "you are caller N" to the node
                     ▼
                 re-arm @ announce_interval_sec ... until bridged/exited

Enabling announcements

Set the announcement fields on the queue:

{
  "id": "q_01j160r23gw5zkpfjme3fwzs5k", "name": "Support",
  "announce_position": 1,
  "announce_first_sec": 15,
  "announce_interval_sec": 30,
  "language": "es-ES"
}

Field	Default	Purpose
announce_position	0	1 to enable position announcements.
announce_first_sec	15	Delay before the first announcement.
announce_interval_sec	30	Repeat interval (0 = announce once).
language	inherit	Per-queue announcement language override (else the account/system default).

Set announce_interval_sec to 0 to announce position once and then stay quiet.

Multilingual & gender-correct

Announcements are spoken in the queue’s language (or the account default), using the account’s chosen narrator voice. Numbers are rendered with the proper grammar for each language, including gender-correct number agreement across languages like Hebrew, Arabic, Spanish, French and Russian. In Hebrew, for example, the position number agrees masculine with “number” (מספר) while estimated-wait minutes agree feminine with “minutes” (דקות). Each unique spoken line is synthesized once and cached, content-addressed, so repeated positions reuse the same audio. See Media & Multilingual TTS.

Interaction with hold audio

Announcements break the hold audio to speak, then resume:

• With moh_mode: "stream", the shared shared-stream is rejoined at its current position, effectively gapless.
• With moh_mode: "file", the per-caller file restarts from the top after the announcement.

Either way, because the brain only interrupts on a genuinely changed position, callers aren’t subjected to a number every interval regardless of movement.

Position semantics

Position is 1-based: the front caller is “number 1.” A caller’s position only goes down (or stays) as those ahead are served or abandon, so each announcement is reassuring rather than confusing.

Guide

For a step-by-step, see Add position announcements.