Conference control

POST /v1/conferences/{conference_id}/actions

Check GET /v1/capabilities for this estate and caller before offering actions. Conference control requires estate enablement, an explicit scope grant and configured call-state, executor credential and allowed hosts. A feature flag does not prove executor reachability or live acceptance. An FFB sandbox must use isolated test call-state and an isolated executor.

Access and request contract

Keep an estate token with an explicit conferences:write grant on your application's server. This grant is independent of partner provisioning approval. Current token-owner permissions, the verified account hierarchy and the global API read-only guard still apply.

Each action requires a safe conference_id room token, a full fs_uuid live channel UUID and a UUID Idempotency-Key header. Obtain the room and anchor from an independently verified estate integration. The server resolves the anchor's account and node, authorises the account, reads the named room's members and verifies the owned anchor is present before returning room data or sending a mutating action. Targeted actions also verify the target belongs to that room.

To control a dialled SIP or AI leg, keep the original caller's owned live UUID in fs_uuid and put the target leg's UUID in member. A dialled leg without its own account-owned call-state record cannot serve as the anchor and returns 404.

A successful dial returns sip_leg_uuid, the channel UUID the server assigns to the new leg before originating it. Pass it as member to mute, kick, hang up or kill that leg later. The response is returned once the call is started, before it is answered: until the leg joins the room, or if it is never answered, actions targeting it return 409 call_ended.

{"data": {"conference_id": "DDI-12345678-1234-4234-8234-123456789abc-support", "status": "ok", "action": "dial",
  "number": "+447700900123", "sip_leg_uuid": "3f1c2b7a-9d4e-4c61-8a2f-5b6e7d8c9a01", ...}}

POST /v1/conferences/DDI-12345678-1234-4234-8234-123456789abc-support/actions
Authorization: Bearer <server-held-estate-token>
Idempotency-Key: 87654321-4321-4321-8321-abcdef123456
Content-Type: application/json

{
  "action": "mute",
  "fs_uuid": "12345678-1234-4234-8234-123456789abc",
  "member": "7"
}

All actions use POST, including list, and require the scope, feature and idempotency key. Room tokens contain 1–128 letters, digits or _.+@- and start with a letter or digit. A member is a positive numeric ID of up to ten digits or a full channel UUID. For kill, the API resolves that member and sends only its verified channel UUID to the executor.

Dial accepts 1–20 PSTN digits with an optional leading +, or a conservative SIP address (sip:agent@example.com or agent@example.com, optionally with a port). CLI and DDI accept the same PSTN syntax. Supply ddi for dial unless the room starts with a numeric DDI prefix; cli defaults to ddi. Whitespace, command fragments, SIP parameters and embedded credentials are rejected. See the OpenAPI reference for field schemas. Successful responses wrap the executor result in data; fields vary by action.

Room moves, transfers, call discovery and conference event subscription/delivery are unsupported. Provisioning a conference service does not establish an event-delivery contract or enable runtime conference control.

Retries and errors

Use a fresh UUID Idempotency-Key for each intended action; preserve it when retrying the identical request. Recorded responses can be replayed. An executor may have acted before a timeout or lost response. Reconcile live call state before retrying a billable or destructive action after an ambiguous timeout or 5xx.

Missing scope or a disabled feature returns 403; global read-only mode returns 403 api_read_only. Missing or inaccessible anchors/rooms return a generic 404; ended rooms or members may return 409 call_ended; invalid fields or idempotency keys return 422. Executor failures return 502 node_unreachable; missing runtime wiring returns 503 conference_unavailable. Per-token rate limits return 429.

Legacy global router

Earlier versions of this page recommended a shared Lambda URL and cc_… router tokens. That is a separate historical integration, not the entrypoint or release acceptance evidence for this per-estate API. Existing router users should coordinate with its owner. Do not redirect credentials to another host or infer sandbox isolation from an old URL or token prefix.