Making calls

Place and receive calls over PSTN, SIP, and WebRTC. Bring your own telephony provider or let Wordcab originate the leg.

Wordcab agents handle outbound and inbound calls over PSTN, SIP, and WebRTC. The media path is flexible: Wordcab can originate the leg itself, or you can bring your own telephony provider (Twilio, Telnyx, Plivo, Zoom, a SIP trunk).

Outbound calls

call = client.agents.calls.create(
    agent_id="agent_abc",
    phone_number="+14155551234",
    context={
        "customer_name": "Jane Doe",
        "appointment_time": "2:00 PM",
        "purpose": "appointment_reminder",
    },
    max_duration=300,     # seconds
    record=True,
    idempotency_key="reminder-2026-04-16-user-55123",
)

Call lifecycle

1. initiating — call object created, media leg coming up.
2. ringing — PSTN ringing the far side.
3. in_progress — answered; agent is running.
4. completed — both sides hung up normally.
5. failed — technical error. See call.error.
6. no_answer — rang through without being picked up.

Inbound calls

Provision a number (from Wordcab, or from your own provider) and associate it with an agent. Incoming calls to that number route to the agent automatically.

client.agents.update(
    agent_id="agent_abc",
    phone_numbers=["+14155559999"],
)

Twilio media streams

Bridge Twilio calls into a Wordcab agent with TwiML <Stream>. Your Twilio webhook returns:

<Response>
  <Connect>
    <Stream url="wss://api.wordcab.com/v1/media/twilio?agent_id=agent_abc" />
  </Connect>
</Response>

Wordcab receives the audio over WebSocket (μ-law @ 8 kHz), runs STT → LLM → TTS, and writes back audio frames in the same stream.

SIP

For on-prem PBX (Avaya, Genesys, Cisco, FreeSWITCH), deploy Wordcab's SIP gateway into your network. It speaks standard SIP + RTP and terminates TLS/SRTP where required.

helm install wordcab-sip wordcab/sip-gateway \\
  --set trunk.host=pbx.internal.example.com \\
  --set trunk.codec=g711a \\
  --set agents.defaultId=agent_abc

Recordings

When record=True, the full call audio is stored in the configured object store. The retention window (default 30 days on cloud, configurable on self-hosted) is set per deployment.

call = client.calls.get("call_abc123")
if call.recording_url:
    audio = client.calls.download_recording(call.id)
    with open("call.wav", "wb") as f:
        f.write(audio)