Voice

Place and receive voice calls on the same number that handles SMS. One subscription, one phone, both channels.

How voice works on Agent Number

Voice uses two WebSocket channels with different jobs. Both stay open during a live call.

• Presence WS — the signaling channel. Agent opens it once and keeps it open as long as it's accepting calls. The server pushes three event types over the call lifecycle: {event: "ringing", call_id, caller, stream_url} (incoming call), {event: "answered", call_id} (call picked up), and {event: "ended", call_id, missed} (call torn down).
• Stream WS — the audio channel. Agent opens it when it gets a stream_url (either from a presence ringing event or from a POST /voice/dial response). Send and receive audio as binary frames. Close it when the call ends.

The presence WS is a long-lived listener; the stream WS is per-call. They can coexist — presence keeps listening for additional incoming calls while a stream WS carries the current one.

Inbound call flow

1. Agent opens presence WS at wss://agentnumber.really.com/voice/presence/<phone> with Authorization: Bearer <token>. Server auto-answers any incoming call.
2. External caller dials your number.
3. Server pushes {event: "ringing", call_id, caller, stream_url} on the presence WS.
4. Agent opens stream WS at the provided stream_url.
5. Agent receives caller audio as binary frames, sends agent audio back the same way.
6. On hangup (either side), stream WS closes. Presence WS stays open for the next call.

Outbound call flow

1. Agent calls POST/voice/dial with phone_number (one of the subscription's owned numbers, the call's source) and to (destination).
2. Response: {call_id, stream_url, direction, caller, phone_number}. The target phone is now ringing.
3. Agent opens stream WS at stream_url and waits for connect.
4. On answer, audio flows both directions until hangup.

Place a call

curl -X POST https://agentnumber.really.com/voice/dial \
  -H "authorization: Bearer <token>" \
  -H "content-type: application/json" \
  -d '{"phone_number": "+15555550123", "to": "+15551234567"}'
# → {"call_id": "...", "stream_url": "wss://...", "direction": "outbound", "caller": "+15551234567", "phone_number": "+15555550123"}

Open the stream WS

Use any WS client. Audio is binary frames; the server handles cellular bridging. Auth on the stream WS uses the same bearer.

Endpoints

An internal/debug-only v1 status probe exists for fleet operations, but it is not part of the public API and is intentionally not advertised pending the post-launch security review.

Practical notes

• Same number for SMS + voice. No separate provisioning.
• Real cellular, not VOIP. Carrier-verified caller ID; downstream services treat the calls as legitimate consumer calls.
• Per-call mic permission is handled by the underlying hardware fleet — the agent's stream is the canonical capture path.
• Roaming. Numbers are US-issued and behave like normal US mobile numbers internationally; outbound dial to non-US destinations works subject to the standard carrier plan rules.

Common errors

llms.txt OpenAPI MCP server card x402.json mpp.json Agent card Agent skills SKILL.md sitemap.xml Glossary