Contactivity
Voice.md

Conferences and queues

Conferences are created by CoXML <Dial><Conference>; this API reads them, ends them, plays announcements and manages participants. Queues hold callers until an agent takes them (<Enqueue>, the enqueue action). Paths are relative to https://api.contactivity.io/v1/projects/{project_id}; see the overview.

Method Path Scope Purpose
GET /conferences conferences:read List conferences (paged)
GET /conferences/{conference_id} conferences:read Fetch a conference
POST /conferences/{conference_id}/actions/{action} conferences:write end or announce
GET /conferences/{conference_id}/participants conferences:read List participants (one page, up to 1000)
POST /conferences/{conference_id}/participants conferences:write, calls:write Dial a participant in
GET /conferences/{conference_id}/participants/{call_id} conferences:read Fetch a participant
PATCH /conferences/{conference_id}/participants/{call_id} conferences:write, calls:write Mute, hold, coach, announce
DELETE /conferences/{conference_id}/participants/{call_id} conferences:write, calls:write Remove (hang up) a participant
POST /queues queues:write Create a queue
GET /queues queues:read List queues (paged)
GET /queues/{queue_id} queues:read Fetch a queue
PATCH /queues/{queue_id} queues:write Change max_size
DELETE /queues/{queue_id} queues:write Archive an empty queue
GET /queues/{queue_id}/members queues:read Waiting calls (one page, up to 5000)
GET /queues/{queue_id}/members/{call_id} queues:read A member, or front
POST /queues/{queue_id}/members/{call_id}/dequeue queues:write, calls:write Take a call off the queue

In participant paths {call_id} may also be the participant's label.

Conferences

Object: id (CF…), name, status (init, in_progress, completed), created_at, updated_at. List filters: name (exact), status.

Actions: end (no body) and announce ({"announce_url": "https://…"}, CoXML or audio played to everyone). Both return 200 and the conference. Errors: 404 unknown_action, 404 not_found, 400 invalid_parameter (param announce_url), 422 call_state (not in progress), 503 engine_unavailable.

sh
curl -X POST https://api.contactivity.io/v1/projects/$PROJECT_ID/conferences/$CONF_ID/actions/end \
  -H "Authorization: Bearer $CONTACTIVITY_API_KEY" -H "Idempotency-Key: $(uuidgen)"

Participants

Object: call_id, conference_id, label, status (e.g. connecting, ringing, connected, complete, failed), muted, on_hold, start_conference_on_enter, end_conference_on_exit, coaching, coaching_call_id, created_at.

Add (POST, returns 201):

Field Type Rules
from string Required. A number of the project or a verified number
to string Required. E.164, client:<name> or SIP URI
label string Up to 64 letters, digits, _, ., -
muted boolean Default false
start_conference_on_enter boolean Default true
end_conference_on_exit boolean Default false
beep string true (default), false, on_enter, on_exit
timeout_secs integer 5-600, default 30
coaching_call_id string A call (CA…) this participant coaches
record boolean
status_callback_url, status_callback_events, recording_status_callback_url Callbacks for the new call

Update (PATCH, returns 200): muted, on_hold, hold_audio_url, announce_url (played to this participant), coaching, coaching_call_id.

sh
curl -X PATCH https://api.contactivity.io/v1/projects/$PROJECT_ID/conferences/$CONF_ID/participants/agent-1 \
  -H "Authorization: Bearer $CONTACTIVITY_API_KEY" -H "Content-Type: application/json" \
  -d '{"muted": true}'

Errors: 400 invalid_parameter (param to, from, beep, timeout_secs, label, coaching_call_id, hold_audio_url, announce_url, ...), 402 insufficient_balance, 403 caller_id_not_verified, 403 destination_blocked, 404 not_found, 422 call_state (conference not in progress), 503 engine_unavailable. Removing returns 204.

Queues

Object: id (QU…), name, max_size, current_size, average_wait_secs, created_at.

Create: name (required, 1-64 characters, unique in the project), max_size (1-5000, default 100). Errors: 400 invalid_parameter (param name, max_size), 409 already_exists. Update takes max_size. Delete archives the queue: 204, or 409 queue_not_empty. An archived queue refuses new callers and keeps its name taken.

sh
curl https://api.contactivity.io/v1/projects/$PROJECT_ID/queues \
  -H "Authorization: Bearer $CONTACTIVITY_API_KEY" \
  -H "Content-Type: application/json" -H "Idempotency-Key: $(uuidgen)" \
  -d '{"name": "support", "max_size": 50}'

Members

Object: call_id, queue_id, position (1 = front), wait_secs, enqueued_at. Use front as {call_id} for the longest-waiting caller.

Dequeue sends the call to new CoXML: give one of coxml_url (+ coxml_method, default POST) or app_id (a CoXML voice app with a voice URL). Returns 200 and the member. Errors: 400 invalid_parameter (param coxml_url, coxml_method, app_id), 404 not_found, 422 call_state, 503 engine_unavailable.

sh
curl https://api.contactivity.io/v1/projects/$PROJECT_ID/queues/$QUEUE_ID/members/front/dequeue \
  -H "Authorization: Bearer $CONTACTIVITY_API_KEY" \
  -H "Content-Type: application/json" -H "Idempotency-Key: $(uuidgen)" \
  -d '{"coxml_url": "https://example.com/connect-agent.xml"}'