Compatibility API (Twilio and Telnyx)

New code should use the native API (README.md). This section documents the Twilio- and Telnyx-compatible APIs, kept so that existing code migrates by changing its SDK base URL:

The interactive reference is the Compatibility tab (spec https://api.contactivity.io/docs/compat/openapi.yaml). Its paths map to the compatible base URLs: /v1/voice/X is what /compat/twilio/2010-04-01/Accounts/{AccountSid}/X.json reaches, and /v1/voice/call-control/X is what /compat/telnyx/v2/X reaches. Call them through the /compat base URLs. The SDKs contactivity (Twilio) and contactivity-callcontrol (Telnyx), for Node and Python, default to those base URLs.

Native equivalents:

The rest of this page is the compatibility reference.

Authentication

API keys are created per project in the portal, can be limited to voice, and are stored as hashes. Requests over plain HTTP are refused.

Compatibility API

Requests are application/x-www-form-urlencoded, with Twilio's parameter names. Responses are JSON. The project comes from the credentials, so paths don't repeat the AccountSid. Moving from Twilio means changing the base URL from /2010-04-01/Accounts/{AccountSid} to /v1/voice and dropping the .json suffix. Code written against Twilio's REST URLs can instead keep them: migrating from Twilio, set your SDK base URL to https://api.contactivity.io/compat/twilio and the same handlers serve /compat/twilio/2010-04-01/Accounts/{AccountSid}/... (Telnyx: https://api.contactivity.io/compat/telnyx/v2). See compat-migration.md.

Calls

POST /Calls parameters:

The call resource returned:

{
  "sid": "CA5f2c8a1e7d4b4e0f9a1c2d3e4f5a6b7c",
  "account_sid": "AC91ab…",
  "parent_call_sid": null,
  "to": "+13105550000",
  "from": "+15551234567",
  "status": "queued",
  "direction": "outbound-api",
  "start_time": null,
  "end_time": null,
  "duration": null,
  "price": null,
  "price_unit": "USD",
  "answered_by": null,
  "quality": null,
  "date_created": "Thu, 09 Oct 2026 10:15:00 +0000",
  "uri": "/v1/voice/Calls/CA5f2c…",
  "subresource_uris": {
    "recordings": "/v1/voice/Calls/CA5f2c…/Recordings"
  }
}

price is the call's price, filled in when the call ends.

Call quality

quality is our extension to the Twilio call resource (Twilio keeps this in Voice Insights): the media quality of this leg, null until the leg has ended or when it carried no audio. Each leg is its own call resource, so the quality of a <Dial> leg is on the child call (GET /Calls?ParentCallSid=…).

"quality": { "mos": 4.41, "jitter_ms": 1.5, "packet_loss_pct": 0.2, "packets": 1500, "source": "engine" }

Portal call logs show the quality of each leg.

Recordings

Dual-channel. RecordingChannels=dual (Calls API, POST /Calls/{CallSid}/Recordings), <Dial record="record-from-answer-dual"> / record-from-ringing-dual and Call Control record_start channels: "dual" record a stereo WAV: the caller (the call's own leg) on the left channel, the other party on the right. The recording's channels is 2 (Call Control channels: "dual"), and so is the callback's RecordingChannels. SIP trunk recordings are always dual. Transcription mixes both channels down to one track.

Encryption at rest. Every recording file (and its MP3 copy) is encrypted before it is stored, with a random 256-bit key per project: AES-256-GCM in 64 KiB chunks, each with its own nonce and tag, so tampering or truncation is detected on read. The project keys are stored wrapped by a master key held only in the API's environment (RECORDING_MASTER_KEY). Downloads always go through the API, which decrypts while it streams; signed links work as before. Deleting a project deletes its key. Recordings stored before encryption was turned on are served as they are.

Retention. Recordings, transcriptions, AI agent transcripts and call inspector logs are never erased. DELETE archives a recording or transcription (hidden, the file kept). Project retention settings (PUT /v1/projects/{id}/compliance) are accepted and ignored; GET returns them as null.

Transcription redaction. With the project's transcription_redaction, PII in transcription_text is replaced by tokens like [PHONE] before it is stored and sent to the callback.

A transcription is Twilio's Transcription resource: sid (TR…), recording_sid, status (in-progress, completed, failed), transcription_text, duration (audio seconds), price (negative, USD, per audio minute), price_unit, type (fast), date_created, date_updated, uri. API key scopes: recordings:read and recordings:write. Deleting a recording deletes its transcription. The portal reads a recording's transcript at GET /v1/projects/{project_id}/recordings/{RecordingSid}/transcription ({sid, recording_sid, status, text, language, provider, model, duration, billed_secs, price, error, created_at, updated_at}, 404 when the recording was not transcribed).

Conferences and participants

{CallSid} in participant paths can also be the participant's label.

Queues and members

Call Control API

Requests and responses are JSON. Every command accepts:

• client_state: base64 string, echoed in every later webhook for this call;
• command_id: a repeated id within 60 seconds is ignored, so retries are safe.

Calls

Response of POST /v1/voice/call-control/calls:

{
  "data": {
    "record_type": "call",
    "call_control_id": "v3:…",
    "call_leg_id": "4f8c…",
    "call_session_id": "9a1d…",
    "is_alive": false
  }
}

Actions: POST /v1/voice/call-control/calls/{call_control_id}/actions/{command}

With answering_machine_detection (detect or detect_words), dialed calls send call.machine.detection.ended with result: human, machine, fax or not_sure. detect_beep and greeting_end also wait for the end of a machine's greeting and then send call.machine.greeting.ended (beep_detected, ended or not_sure). premium sends call.machine.premium.detection.ended (human_residence, human_business, machine, silence, fax_detected, not_sure, plus confidence 0–1) and, for machines, call.machine.premium.greeting.ended (beep_detected or no_beep). answering_machine_detection_config takes total_analysis_time_millis, after_greeting_silence_millis, greeting_duration_millis and initial_silence_millis (the Twilio thresholds above). Detection runs before the next command is accepted. | refer | sip_address | call.refer.started, call.refer.completed or .failed | | speak | payload, payload_type (text or ssml), voice, language | call.speak.started, call.speak.ended | | playback_start | audio_url, loop, overlay (true: mixed over the audio already playing, at once, not queued behind the running command; WAV only, played once; playback_stop stops it) | call.playback.started, call.playback.ended | | playback_stop | stop (current or all) | call.playback.ended | | gather | minimum_digits, maximum_digits, timeout_millis, terminating_digit, valid_digits, inter_digit_timeout_millis | call.gather.ended | | gather_using_speak | gather fields + payload, voice, language, input (dtmf, speech, dtmf speech), hints | call.gather.ended (with digits or speech) | | gather_using_audio | gather fields + audio_url | call.gather.ended | | gather_stop | — | call.gather.ended (status cancelled) | | record_start | format (wav, mp3; recordings are WAV for now, mp3 is accepted and recorded as WAV), channels (single, dual), play_beep (default false: a short tone as the recording starts), max_length (seconds, 0–14400, 0 = no limit: the recording is then stopped and saved), transcription (bool), transcription_language (default en-US), transcription_engine (accepted, ignored) | call.recording.saved (after stop and upload); with transcription, then call.recording.transcription.saved (recording_id, recording_transcription_id, status, transcription_text) | | record_stop, record_pause, record_resume | — (a pause leaves the paused audio out of the recording) | — | | send_dtmf | digits, duration_millis | — | | enqueue | queue_name, max_wait_time_secs, max_size | call.enqueued, call.dequeued | | leave_queue | — | call.dequeued | | streaming_start | stream_url, stream_track (inbound_track, outbound_track, both_tracks), stream_bidirectional_mode (rtp: the server's media messages, PCMU, are played to the caller for as long as the stream runs, between and after other commands; mp3 is refused with 400, like other invalid parameters) | streaming.started, streaming.stopped, streaming.failed | | streaming_stop | — | streaming.stopped | | transcription_start | language (default en-US), transcription_tracks (inbound, outbound, both), interim_results (bool), transcription_engine (accepted, ignored) | call.transcription with transcription_data: transcript, confidence, is_final, transcription_track | | transcription_stop | — | — | | ai_agent_start | voice_app_id (an ai_agent app), parameters (object of strings) | call.ai_agent.started, call.ai_agent.ended (status, transfer_to, error); the agent app's agent.* webhooks | | gather_using_ai | parameters (JSON schema of the fields to collect: properties, required; 1–20 properties), greeting, voice (voice id), language (default en-US), assistant (instructions, model), message_history ([{"role": "user" or "assistant", "content"}], up to 50: the conversation so far), timeout_secs (30–1800, default 120; ours); send_partial_results is accepted and ignored | call.ai_gather.ended with status (completed, partial, timeout, caller_hangup, error), result (the collected fields), message_history and error. Same agent as CoXML <AIGather>, billed as an AI agent | | suppression_start | direction (inbound (default, the caller's audio), outbound (audio sent to the caller), both); noise_suppression_engine is ignored (one engine: RNNoise) | — | | suppression_stop | — | — | | coxml_redirect | url or coxml | (hands the call to CoXML; Call Control webhooks stop) |

Responses: 200 {"data": {"result": "ok"}}. A command for a call that has ended returns 422 with error call_has_ended.

Noise suppression (suppression_start) runs RNNoise in the media server on the chosen direction; everything downstream of it (the bridged party, recordings, streams, transcription, AI agents) gets the cleaned audio. A second suppression_start changes the direction; it ends with the call. Price: $0.002 per minute while it runs (placeholder; ai_rates part noise_suppression), rounded up to the billing increment, debited from the prepaid balance once per call at hangup (ledger kind noise_suppression, external id ns:<call sid>). It is billed the same way when started by CoXML <Start><NoiseSuppression> or an AI agent with noise_suppression set.

Conferences

Conference webhooks (Telnyx envelope and keys): conference.created (when the first participant enters) and conference.ended (reason: all_left, ended_via_api, host_left) go to the webhook of the conference's first Call Control participant, normally the call that created it, with that call's ids. conference.participant.joined / left go to each Call Control participant's own webhook, with its ids. All carry conference_id. A conference record_start sends conference.recording.saved (conference_id, recording_id, recording_urls, channels, format, recording_started_at / recording_ended_at; the call ids are null) to the conference's webhook after upload. They work the same when participants are on different engine nodes.

Answering machine detection

The engine listens to the called party's audio from answer (voice/src/amd.rs), 20 ms at a time:

• Greeting shape: a short greeting followed by silence (MachineDetectionSpeechEndThreshold) is a person; speech reaching MachineDetectionSpeechThreshold is a machine, unless its cadence is a person's ("Hello? … Hello?": pauses most of the time). In between, many words in a row (a recording's cadence) mean a machine.
• Beep: a single tone between 350 and 2000 Hz holding most of the audio's energy for 160 ms, found by a Goertzel scan; it survives line noise down to about 0 dB SNR. A beep after any greeting, even a short "Leave a message", makes the call a machine (machine_end_beep, or machine_start with Enable).
• Fax: CNG (1100 Hz, before anyone speaks) or CED (2100 Hz).
• Premium (MachineDetectionEngine=premium, Call Control premium): the first 6 s of the greeting also go to speech-to-text. Voicemail phrases ("leave a message", "after the tone", "not available", "mailbox", "voicemail", "you've reached …") make a short greeting a machine; a business answering ("thank you for calling …, how can I help") keeps a long greeting a person (human_business). A decision waits at most 2.5 s for the transcript; without one the audio decision stands.

Price: standard detection is included in the call. Premium is $0.0075 per call that runs it (placeholder; Twilio prices AMD per call), debited from the prepaid balance once the detection ends (ai_rates part amd_premium, whose rate_per_min column holds the per-call price; ledger kind amd, external id amd:<call sid>).

Webhooks

Compatibility API

CoXML requests and status callbacks use form-encoded POSTs with Twilio's parameter names.

Call Control API

JSON POSTs to the voice app's webhook URL:

{
  "data": {
    "record_type": "event",
    "id": "0ccc7b54-4df3-4bca-a65a-3da1ecc777f0",
    "event_type": "call.answered",
    "occurred_at": "2026-10-09T10:15:04.123Z",
    "payload": {
      "call_control_id": "v3:…",
      "call_leg_id": "4f8c…",
      "call_session_id": "9a1d…",
      "connection_id": "app_42",
      "client_state": "eyJzdGVwIjoxfQ==",
      "from": "+15551234567",
      "to": "+13105550000",
      "direction": "outgoing",
      "state": "answered"
    }
  },
  "meta": { "attempt": 1, "delivered_to": "https://example.com/hooks" }
}

Event types:

• Call: call.initiated, call.answered, call.hangup (with hangup_cause, hangup_source, sip_hangup_cause), call.bridged, call.dtmf.received, call.gather.ended, call.speak.started / ended, call.playback.started / ended, call.recording.saved, call.machine.detection.ended, call.machine.greeting.ended, call.machine.premium.detection.ended, call.machine.premium.greeting.ended, call.refer.*, call.enqueued, call.dequeued, call.ai_agent.started / ended, call.ai_gather.ended, call.error.
• Streaming: streaming.started, streaming.stopped, streaming.failed.
• Conference: conference.created, conference.ended, conference.participant.joined, conference.participant.left, conference.recording.saved.

Signing (both APIs)

Delivery

• Timeout 10 seconds per attempt. Any 2xx counts as delivered.
• Retries for status callbacks and Call Control events: 1 s, 5 s, 30 s, 2 min, 10 min, then the failover URL if one is set.
• Events can arrive out of order or more than once. Use data.id (Call Control) or SequenceNumber (status callbacks) to sort and deduplicate.
• CoXML document fetches are not retried (the call can't wait); they go to the fallback URL instead.

Errors

JSON error body for both APIs:

{ "code": 21211, "message": "The 'To' number +1555 is not a valid phone number.", "more_info": "https://docs.contactivity.io/errors/21211", "status": 400 }

Rate limits