sidetone

Usage

Groups, queues and transfer

A ring group rings several phones for one number. A queue holds callers in line for whoever is free. Hold, transfer and pickup need nothing set up at all.

Ring groups

$ api -d '{"name":"sales","extension":"600","strategy":"hunt","members":["1001","1002"],"member_timeout":20,"no_answer":"1009"}' localhost:8080/v1/ring-groups

strategy is one of:

  • ring_all: everyone at once; the first to answer takes the call.
  • hunt: one by one, in the order listed, each for member_timeout seconds.
  • round_robin: a hunt that starts one further along each call, so the load spreads.
  • longest_idle: a hunt that starts with whoever has been off the phone longest.

Members who are on a call or not registered are skipped. When nobody answers, the call goes to no_answer: a user with voicemail, a menu, another group. An inbound number may point straight at a group. Call records show who picked up in answered_by.

Hold and transfer

Hold needs no setup: the held party hears music (music_on_hold in the settings; your own, as an uploaded sound, under music_on_hold_audio). The server absorbs the hold, so the other party's phone is never told and never renegotiates; it simply hears music until the call resumes.

Transfer works from the phone's transfer key, blind or attended. The new call is placed with the permissions of whoever transfers, so dialling restrictions still apply. Each conversation gets its own call record, tied to the others by linked_call_id. To pick up a call ringing at a colleague's desk, dial *8 and their extension; see pickup.

Queues

A queue is an extension where callers wait, with music, until one of its agents is free:

$ api -d '{"name":"support","extension":"800","agents":["1001","1002"],"strategy":"longest_idle","agent_timeout":20,"wrap_up":10,"max_wait":600,"max_callers":20,"overflow":"1003"}' localhost:8080/v1/queues
  • First come, first served. strategy picks among the agents who are free, as for ring groups; wrap_up is the rest an agent gets after a call before the next is offered.
  • With ring_all every free agent rings for the first caller in line, and the next caller is offered once that call is picked up. For a busy queue with several agents, longest_idle (the default) or round_robin serve several callers at the same time.
  • An agent steps out by dialling *45 and back in with *46, or you do it for them: PUT /v1/queues/{id}/agents/{username}/paused with {"paused":true}, or from the wallboard. A restart puts everybody back in.
  • A caller who has waited max_wait seconds, or who finds max_callers already waiting, goes to overflow: a user with voicemail, perhaps, a ring group, a menu, another queue. Without one the call ends.
  • music names uploaded audio for this queue; without it callers hear the hold music.

GET /v1/queues/{id}/status shows who is waiting and what each agent is doing. Call records carry queue and wait_seconds, and a caller who gave up is recorded as abandoned.

The wallboard

Wallboard in the console is for a screen on the wall; a read-only token is enough to sign in, and Full screen is for the wall. It shows incoming calls, who waits in which queue and for how long, every agent and what they are doing (free, ringing, on a call, wrapping up, logged out, without a phone), who is parked, and each queue's day: calls, answered, gave up, average and longest wait. An administrator can log an agent in or out from the board.

It is three requests however many queues there are, which any dashboard can make too: GET /v1/calls, GET /v1/queues/status, and GET /v1/queues/stats?since= with the start of your day, which the server cannot know.