Ring groups and follow-me

Two mechanisms ring more than one destination. They overlap, so the useful distinction is where the definition lives:

	Ring group	Follow-me
Defined in	tenant.yaml, named and reusable	inline in the dial step
Shape	one list, rung simultaneously or one by one	ordered stages, each a parallel list
Per-target timing	one timeout for the whole group	a timeout per stage
Reachable from	dialplan steps and inbound routes	dialplan steps only

In both, the first answer wins and the remaining legs are cancelled.

Ring groups

configs/tenants/acme/tenant.yaml

ring_groups:
  support:
    strategy: simultaneous
    targets: ["100", "101", "external:0612345678"]
    timeout: 30s

  escalation:
    strategy: sequential
    targets: ["101", "100", "external:0612345678"]
    timeout: 15s

Field	Required	Meaning
strategy	yes	simultaneous or sequential.
targets	yes	At least one target reference.
timeout	no	For simultaneous, the total ring time. For sequential, the time per target.

• simultaneous rings every target at once for timeout.
• sequential rings the targets one at a time, each for timeout, moving on when a target does not answer.

Using it:

- id: ring-support
  type: dial
  timeout: 40s          # overrides the group's own timeout
  target:
    kind: ring_group
    group: support

A timeout on the step overrides the group's. Without either, the default is 30s.

A ring group is also a valid inbound route destination:

inbound_routes:
  - did: "+31201234568"
    destination: {type: ring_group, target: support}

Follow-me

Follow-me is defined where it is used, which suits per-extension escalation patterns that are not worth naming:

- id: follow-me
  type: dial
  moh: default
  target:
    kind: followme
    stages:
      - targets: ["101"]                          # first Bob's desk
        timeout: 15s
      - targets: ["100", "external:0612345678"]   # then Alice and a mobile
        timeout: 25s
      - targets: ["tenant:globex/900"]            # then the partner's desk
        timeout: 20s

Stages run in order. Each stage rings all of its targets in parallel for its own timeout; if nobody answers, the next stage starts. When the last stage is exhausted, the step has not answered and the dialplan continues with the next step — the announcement, or a moh step, or a hangup.

A stage without a timeout falls back to the step's timeout, then to 30s.

Targets

All three reference forms work in either mechanism:

Form	Meaning
"101"	An account extension of this tenant.
external:0612345678	A number placed through the outbound routes.
tenant:globex/900	Another tenant's extension, when inter-tenant calling is enabled.

Validation checks every reference at startup: an extension must belong to an account of the tenant, an external target must be non-empty, and a tenant: reference must be permitted by both switches and point at a real extension.

At call time, a reference that resolves to nothing — typically an extension with no registered device — is skipped. A stage where everything is skipped rings nobody and moves on immediately.

Which to use

• One list of people who should all ring → ring group, simultaneous.
• A fixed escalation order used from several places → ring group, sequential.
• A per-extension escalation with different timings per step, mixing internal and external targets → follow-me.

Ringback or music

By default the caller hears ringback. Setting moh on the dial step plays a music-on-hold class instead, which is the usual choice when the first stage is long enough that silence-plus-ringing feels like a dead line:

- id: follow-me
  type: dial
  moh: default
  target: {kind: followme, stages: [...]}