Calls

Place outbound calls, list and fetch calls, and control live calls with actions. Paths are relative to https://api.contactivity.io/v1/projects/{project_id}; auth, errors, paging and idempotency are in the overview.

Recording starts and stops through actions (record_start, ...); the files are under recordings.

The call object

Place a call

POST /calls returns 201 and the call (status queued). Give exactly one source of call logic:

curl https://api.contactivity.io/v1/projects/$PROJECT_ID/calls \
  -H "Authorization: Bearer $CONTACTIVITY_API_KEY" \
  -H "Content-Type: application/json" -H "Idempotency-Key: $(uuidgen)" \
  -d '{"to": "+14155550100", "from": "+12125550123",
       "coxml": "<Response><Say>Your order has shipped.</Say></Response>",
       "status_callback_url": "https://example.com/status", "status_callback_events": ["answered", "completed"]}'

Errors: 400 invalid_parameter (param to, from, app_id, coxml, coxml_url, coxml_method, webhook_url, status_callback_url, status_callback_events, timeout_secs, time_limit_secs, machine_detection, record, client_state), 400 unknown_parameter, 402 insufficient_balance, 403 caller_id_not_verified (param from), 403 destination_blocked (param to), 403 account_inactive, 409 app_disabled (param app_id: the voice app is disabled), 429 rate_limit (calls per second or simultaneous calls), 503 engine_unavailable.

List and fetch

GET /calls filters: status, direction (inbound/outbound), from, to (+1NXXNXXXXXX also matches a stored 1NXXNXXXXXX), parent_call_id, app_id (exact matches), app_kind (coxml, call_control, ai_agent, flow; ai_agent also matches agents started from another app), created_after (inclusive) and created_before (exclusive) as RFC 3339, plus limit and starting_after.

curl "https://api.contactivity.io/v1/projects/$PROJECT_ID/calls?status=completed&limit=20" \
  -H "Authorization: Bearer $CONTACTIVITY_API_KEY"

GET /calls/{call_id}: 404 not_found when the call is not in the project.

GET /calls/{call_id}/detail (scope calls:read) returns everything stored about the call in one response:

An API key gets ai_agent only with apps:read, and recordings/transcriptions only with recordings:read. Every read is written to the access audit log as sensitive (it can carry transcripts).

DELETE /calls/{call_id} archives a finished call's record: it leaves GET /calls (list archived calls with ?archived=true) and is still returned by id with archived_at set. Its webhook deliveries, errors, events, recordings and transcriptions are kept. 204; 404 not_found; 409 archived (already archived); 422 call_state while the call is live.

Actions

POST /calls/{call_id}/actions/{action} returns 200 and the call. redirect and hangup work on every call. The other actions need a call-control call (placed with a call_control app or a webhook_url); on a CoXML call they return 409 call_state (use redirect to move a CoXML call to new CoXML).

Every action takes client_state (base64, at most 4096 characters). Other fields per action; anything else is 400 unknown_parameter:

curl https://api.contactivity.io/v1/projects/$PROJECT_ID/calls/$CALL_ID/actions/gather_using_speak \
  -H "Authorization: Bearer $CONTACTIVITY_API_KEY" \
  -H "Content-Type: application/json" -H "Idempotency-Key: $(uuidgen)" \
  -d '{"payload": "Press 1 for sales, 2 for support.", "maximum_digits": 1}'

curl https://api.contactivity.io/v1/projects/$PROJECT_ID/calls/$CALL_ID/actions/redirect \
  -H "Authorization: Bearer $CONTACTIVITY_API_KEY" \
  -H "Content-Type: application/json" -H "Idempotency-Key: $(uuidgen)" \
  -d '{"coxml_url": "https://example.com/after-hours.xml", "coxml_method": "GET"}'

The Idempotency-Key replaces Call Control's command_id: a retried action with the same key runs once.

Errors: 404 unknown_action (param action), 404 not_found, 400 unknown_parameter, 400 invalid_parameter (param client_state, coxml_url, coxml, coxml_method, or a value the voice engine refused), 409 call_state (the action needs a call-control call), 422 call_state (the call has ended or is not in a state that allows the action), 502 api_error, 503 engine_unavailable.

Events of call-control calls go to the app's webhook_url; see events.md.