Bindings

A binding enables intelligence on a point of ingress — a voice trunk or number. Give it a configuration and every conversation arriving there is analysed automatically under that configuration, with no per-conversation API call. Leave the configuration off and the calls are simply tracked, so you can start a session on demand for any of them.

A binding with a configuration is the standing counterpart to a session: where a session applies a configuration to one live conversation you start yourself, a binding applies one to everything arriving at a trunk or number, and the platform starts the session for you. A binding resolves to its configuration by the configuration's stable uuid, so editing the configuration takes effect everywhere it is bound without touching the binding.

Tracking vs automatic analysis

A call can only be analysed — automatically or on demand — if it is being tracked, and a binding is what turns tracking on for a target:

• With a configuration_id — every conversation at the target is tracked and analysed automatically under that configuration, with no per-conversation API call.
• Without a configuration_id — conversations at the target are tracked only. Nothing is analysed until you start a session for a specific call, which you can do on demand for any live call there. This is the lightest-touch option.

There is no account-wide switch — tracking is opted into one trunk or number at a time, so a call is never tracked unless you have bound its ingress point.

Targets

A binding's target is the ingress point it applies to:

Field	Meaning
medium	The ingress plane. voice today — every call, whether over PSTN or WhatsApp, is voice.
type	The ingress kind: trunk (every call over the trunk) or number (a single number/DDI).
key	The identifier — the trunk id, or the number in E.164 for a number target.

A target can hold only one binding; binding a configuration to a target that is already bound returns 409. Park or delete the existing binding to rebind the target.

Precedence

A single call can match more than one binding — a number binding for the dialled number and a trunk binding for the trunk it arrived on. The most specific wins: a number binding takes precedence over a trunk binding. If you also start a session explicitly for a call, that session is what runs — an explicit session is the per-call override of the standing binding.

Lifecycle

• enabled — whether the binding is in force. Set it false to park a binding without deleting it.
• target_status — active while the target trunk/number is present and owned by your account; missing if it has been removed on the carrier side. A missing binding stops applying, and is removed after a grace period — so bindings do not accumulate against ingress points that no longer exist.
• sync_state — live once the running platform reflects the binding, or pending until the next sync cycle. A change is durable immediately; it takes effect on new conversations once sync_state is live.

Finding what a configuration governs

Before you edit or retire a configuration, list bindings filtered by configuration_id to see every ingress point it currently governs — the blast radius of the change. Deleting a configuration removes its bindings. Parking one (is_active: false) leaves its bindings in place but stops the automatic analysis: those targets stay tracked, so on-demand sessions still work, and automatic analysis resumes when the configuration is active again.

API reference — BindingsCreate, list, get, and delete bindings.