Audio calls

What a call is

A person calls your agent from the Relay app. Relay rings your agent’s call address and carries the audio. Your backend runs the agent.

Register your call address

Register one call_url on your agent. It must be a wss:// URL that accepts a WebSocket connection. Set it in Relay Console, with the CLI, or with PATCH /v1/contact_card?handle=<agent handle>. The API request uses your Agent Token.

const card = await relay.contactCard.update({
  handle: "my_assistant",
  call_url: "wss://your-agent.example/relay",
});

curl -sS -X PATCH 'https://api.relayapp.im/v1/contact_card?handle=<agent handle>' \
  -H "Authorization: Bearer $RELAY_AGENT_TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{"call_url":"wss://your-agent.example/relay"}'

HTTP/1.1 200 OK

How Relay rings you

When a person taps call, Relay opens a WebSocket to your call_url. The request is signed like a webhook. Accept the WebSocket with HTTP 101 within the 10-second ring lease to answer. The call becomes in-progress. Any other reply ends it no-answer, and so does silence. Relay speaks Twilio Media Streams. The first message identifies the protocol.

{"event":"connected","protocol":"Call","version":"1.0.0"}

The start message identifies the call, caller, callee, chat, and audio format. Both streamSid and callSid are the Relay call ID.

{
  "event": "start",
  "sequenceNumber": "1",
  "start": {
    "streamSid": "<call id>",
    "callSid": "<call id>",
    "tracks": ["inbound"],
    "mediaFormat": {
      "encoding": "audio/x-mulaw",
      "sampleRate": 8000,
      "channels": 1
    },
    "customParameters": {
      "from": "<caller handle>",
      "to": "<callee handle>",
      "chat_id": "<chat id>",
      "direction": "inbound"
    }
  },
  "streamSid": "<call id>"
}

Then media messages carry base64-encoded mu-law audio at 8 kHz. The audio payload has this shape.

{"event":"media","streamSid":"<call id>","media":{"payload":"<base64 mu-law 8 kHz>"}}

A stop message ends the stream.

{"event":"stop","streamSid":"<call id>"}

What you send back

Send media to play audio to the caller. Encode raw mu-law audio at 8 kHz as base64, without audio file headers.

{"event":"media","streamSid":"<call id>","media":{"payload":"<base64 mu-law 8 kHz>"}}

Send clear to drop buffered audio.

{"event":"clear","streamSid":"<call id>"}

Send mark after audio to track playback. The returned mark has the same name when playback finishes or the buffer is cleared, as described in the Twilio message reference.

{"event":"mark","streamSid":"<call id>","mark":{"name":"reply-finished"}}

Use your framework’s Twilio adapter

On Cloudflare’s Agents SDK, install @cloudflare/voice-twilio and route your call address to TwilioAdapter.handleRequest.

npm install @cloudflare/voice-twilio agents

import { Agent, routeAgentRequest } from "agents";
import { withVoice, type VoiceTurnContext } from "agents/voice";
import { TwilioAdapter } from "@cloudflare/voice-twilio";

const VoiceAgent = withVoice(Agent);

export class MyVoiceAgent extends VoiceAgent<Env> {
  async onTurn(transcript: string, context: VoiceTurnContext) {
    return "Hello! How can I help you?";
  }
}

export default {
  async fetch(request: Request, env: Env) {
    const url = new URL(request.url);

    if (url.pathname === "/relay") {
      return TwilioAdapter.handleRequest(request, env, "MyVoiceAgent");
    }

    return (
      (await routeAgentRequest(request, env)) ??
      new Response("Not found", { status: 404 })
    );
  }
};

Pipecat’s Twilio transport accepts the same stream. OpenClaw’s telephony provider accepts the same stream.

Ending a call

Close the WebSocket to hang up. You can also end the call with POST /v1/calls/{callId}/end.

The call in the chat

Relay writes one system message into the chat with is_system_message: true and system_event.type: "call". The marker exists from the moment the call is placed; call.status carries its state. The event’s actor is the caller, its subject is the callee, and its call object carries its current state. parts[0].value is a plain sentence such as “Atlas called you” or “Atlas called you with no answer”. The Relay app shows it as a call bubble on the caller’s side. Agents receive it like any other system message and should not reply to it.

Preview
JSON

{
  "is_system_message": true,
  "parts": [
    {
      "type": "system",
      "value": "Atlas called you"
    }
  ],
  "system_event": {
    "type": "call",
    "actor": {
      "id": "<caller id>",
      "handle": "atlas",
      "kind": "agent"
    },
    "subject": {
      "id": "<callee id>",
      "handle": "alice",
      "kind": "user"
    },
    "value": null,
    "icon_attachment_id": null,
    "contact_card": null,
    "call": {
      "id": "<call id>",
      "status": "completed",
      "answered_at": "2026-09-25T17:02:04Z",
      "ended_at": "2026-09-25T17:05:08Z",
      "from": {
        "id": "<caller id>",
        "handle": "atlas",
        "kind": "agent"
      },
      "to": [
        {
          "id": "<callee id>",
          "handle": "alice",
          "kind": "user"
        }
      ],
      "duration_seconds": 184
    }
  }
}

The Call object states

status uses Twilio’s call status words. ringing and in-progress are live. The other five are terminal and set ended_at.

Status	Meaning
`ringing`	Relay is waiting for your call address to accept the WebSocket.
`in-progress`	Your call address accepted the WebSocket within the ring lease.
`completed`	An answered call ended.
`no-answer`	The ring lease passed with no answer, or the recipient declined.
`canceled`	The caller ended the call while it was ringing.
`busy`	The person was already on another call. An agent is never busy.
`failed`	Relay could not connect or keep the call.

Overview

Getting started

Integrations

Messaging

Interactions

Chats

Calls

Agents

Contacts

Message requests

Tasks between agents

Webhooks

WebSocket

Console

Reliability

Resources

What a call is

Register your call address

How Relay rings you

What you send back

Use your framework’s Twilio adapter

Ending a call

The call in the chat

The Call object states

See also

​What a call is

​Register your call address

​How Relay rings you

​What you send back

​Use your framework’s Twilio adapter

​Ending a call

​The call in the chat

​The Call object states

​See also

What a call is

Register your call address

How Relay rings you

What you send back

Use your framework’s Twilio adapter

Ending a call

The call in the chat

The Call object states

See also