Live call routing and IVR (ONC-016)

Embed
Preview of the card
<a href="https://forumulate.com/p/watchtower/docs/live-call-routing"><img src="https://forumulate.com/api/public/orgs/watchtower/spaces/docs/pages/a4750176-e43a-4d97-ab2f-656cd26f1684/social-card.svg?v=3e7ae33eec8b" alt="Live call routing and IVR (ONC-016)" width="600" height="315"></a>

Bring your own telephony: register a Twilio or Vonage number you own, attach a call flow, and point the number's voice webhook at the notifier path /voice/inbound/{number_id} (shown as webhook_path on the number). Requires the ManageOnCall permission.

API

  • POST|GET /v1/orgs/{org}/voice/flows, GET|PUT|DELETE /v1/orgs/{org}/voice/flows/{id}

  • POST|GET /v1/orgs/{org}/voice/numbers, GET|PATCH|DELETE /v1/orgs/{org}/voice/numbers/{id}

The number's auth_token (Twilio auth token, Vonage signature secret) is sealed on write and never returned, logged or audited. Another org's flow or number is a 404.

Flow graph

{start, nodes[]} with at most 50 nodes. Node types:

type

fields

next

say

text, voice, lang, next

next (none hangs up)

menu

prompt, options {digit: node}, timeout_s, retries (max 5), fallback

by digit; after the retries, fallback

hours

tz, windows [{days, start, end}], open, closed

by local time

route_oncall

schedule or escalation_policy, ring_s (max 60), fallback

rings up to 5 current on-call targets in order; fallback when none answers

voicemail

max_s

the provider records; the recording URL and caller become a note on a new alert. We store no audio

hangup

Every node must be reachable, and a cycle must pass through a menu (it waits for the caller).

Security and history

A request that fails the provider signature (Twilio X-Twilio-Signature, Vonage signed JWT) gets 403 and no flow runs. Interpreter state travels in signed callback URLs that expire after 10 minutes. Each call writes voice.call.inbound, voice.call.routed and voice.call.voicemail; the caller is masked to the last four digits unless the number has keep_caller set. Callers do not use on-call seats.

Updated