Calls

A person calls your agent from the Relay app, and your agent answers by joining the call’s room. Relay sends call.created on the webhook or WebSocket your agent already uses for messages, and carries the voice and camera over WebRTC. Your backend runs the agent; it registers nothing for calls.

Answer a call

When call.created arrives with status: "ringing", join the room for call.id within 32 seconds. Joining is the answer: the call becomes in-progress. A call nobody joins ends no-answer. Each package below joins the room and runs the WebRTC connection for you, so your code never handles SDP, ICE or TURN credentials. Choose the one that matches your agent’s runtime.

TypeScript
Python
Pipecat
LiveKit

Install the SDK with the WebRTC packages it lists as optional peer dependencies. Add node-webcodecs only if your agent sends or receives video.

npm install @relaymessenger/sdk@staging werift @evan/opus rtp-packet

import Relay from "@relaymessenger/sdk";
import { RelayCallTransport } from "@relaymessenger/sdk/calls";

const relay = new Relay({ apiKey: process.env.RELAY_AGENT_TOKEN!, baseURL: "https://api.staging.relayapp.im" });

// In your call.created handler:
const transport = new RelayCallTransport({ relay, callId: event.data.call.id });

transport.on("audio", ({ samples, sampleRate, channelCount }) => {
  // Interleaved PCM16 from the person, 48 kHz stereo by default.
});

await transport.connect(); // resolves once media is connected
await transport.writeAudio({ samples, sampleRate: 48_000, channelCount: 1 });

The calls extra installs aiortc, PyAV and NumPy. Python 3.10 or newer.

pip install "relaymessenger[calls] @ git+https://github.com/RelayMessenger/Relay-SDK@staging#subdirectory=python/relaymessenger"

import os

from relaymessenger.calls import RelayAudioFrame, RelayCallTransport


async def answer(call_id: str) -> RelayCallTransport:
    call = RelayCallTransport(
        api_key=os.environ["RELAY_AGENT_TOKEN"],
        call_id=call_id,
        base_url="https://api.staging.relayapp.im",
    )

    @call.on("audio")
    def heard(frame: RelayAudioFrame) -> None:
        ...  # frame.samples, frame.sample_rate, frame.channel_count

    await call.connect()  # returns once media is connected
    return call

RelayTransport is a Pipecat transport: the person’s voice and camera come into your pipeline, and your bot’s audio and video go back into the call. Python 3.11 or newer, with pipecat-ai 1.11 or newer.

pip install \
  "relaymessenger[calls] @ git+https://github.com/RelayMessenger/Relay-SDK@staging#subdirectory=python/relaymessenger" \
  "relaymessenger-pipecat @ git+https://github.com/RelayMessenger/Relay-SDK@staging#subdirectory=python/relaymessenger-pipecat"

import os

from pipecat.frames.frames import LLMRunFrame
from pipecat.pipeline.pipeline import Pipeline
from pipecat.pipeline.worker import PipelineWorker
from pipecat.workers.runner import WorkerRunner
from relaymessenger_pipecat import RelayParams, RelayTransport


async def answer(call_id: str) -> None:
    transport = RelayTransport(
        api_key=os.environ["RELAY_AGENT_TOKEN"],
        call_id=call_id,
        base_url="https://api.staging.relayapp.im",
        params=RelayParams(audio_in_enabled=True, audio_out_enabled=True),
    )
    # stt, llm and tts are your Pipecat services; the aggregators hold the LLM context.
    worker = PipelineWorker(
        Pipeline([transport.input(), stt, user_aggregator, llm, tts, transport.output(), assistant_aggregator]),
        cancel_on_idle_timeout=False,  # a quiet call is still a call
    )

    @transport.event_handler("on_first_participant_joined")
    async def start(transport, participant_id):
        await worker.queue_frames([LLMRunFrame()])  # the model speaks first, in its own words

    @transport.event_handler("on_participant_left")
    async def hang_up(transport, participant_id, reason):
        await worker.cancel()

    runner = WorkerRunner()
    await runner.add_workers(worker)
    await runner.run()

RelayLiveKitCall plugs a Relay call into a LiveKit Agents AgentSession in place of a LiveKit room. Both packages carry video too: Python hands the session the person’s camera, and TypeScript exposes it as call.videoInput (video calls).

# pip install \
#   "relaymessenger[calls] @ git+https://github.com/RelayMessenger/Relay-SDK@staging#subdirectory=python/relaymessenger" \
#   "relaymessenger-livekit @ git+https://github.com/RelayMessenger/Relay-SDK@staging#subdirectory=python/relaymessenger-livekit"
import asyncio
import os

from livekit.agents import Agent, AgentSession
from relaymessenger_livekit import RelayLiveKitCall


async def answer(call_id: str, session: AgentSession) -> RelayLiveKitCall:
    call = await RelayLiveKitCall.connect(
        api_key=os.environ["RELAY_AGENT_TOKEN"],
        call_id=call_id,
        base_url="https://api.staging.relayapp.im",
    )
    call.attach(session)  # audio in, audio out, and the camera

    @call.transport.on("ended")
    def ended(_frame: dict) -> None:
        asyncio.ensure_future(call.aclose())

    await call.wait_for_peer_audio(15_000)
    await session.start(Agent(instructions="You are a helpful voice agent."))
    return call

// npm install @relaymessenger/sdk@staging @relaymessenger/livekit@staging @livekit/agents @livekit/rtc-node
import type { AgentSession } from "@livekit/agents";
import Relay from "@relaymessenger/sdk";
import { RelayLiveKitCall } from "@relaymessenger/livekit";

const relay = new Relay({ apiKey: process.env.RELAY_AGENT_TOKEN!, baseURL: "https://api.staging.relayapp.im" });

async function answer(callId: string, session: AgentSession) {
  const call = await RelayLiveKitCall.connect({ relay, callId });
  call.attach(session); // audio in and audio out
  call.transport.on("ended", () => void call.close());
  await call.waitForPeerAudio(15_000);
  // Start your AgentSession here.
  return call;
}

The person’s audio reaches your agent once both sides are connected. Your agent’s first words are held until the person can hear them, so nothing your agent says early is cut off. Send and receive audio covers formats, playout and interruption; video calls covers the camera.

Show video or Rive in a call

Your agent can show the person something while it talks. It sends live video, or it names a Rive file that the person’s phone draws and your agent drives. When video from your agent is arriving, the phone shows the video; otherwise it shows the Rive file.

Video

Publish a camera track and capture frames into it with transport.publishTrack(LocalVideoTrack) and VideoSource.captureFrame. Video calls covers frame formats, rates and bitrates. Show a talking avatar turns your agent’s speech into a lip-synced face with Simli.

Rive

Set a .riv file on your agent’s Contact Card, then open the call’s rive channel with transport.rive() to set View Model values, fire triggers and switch files, timed to your agent’s speech. Show Rive in a call walks through it.

Decline a call

To decline a ringing call, end it without joining. A call your agent ends while it rings becomes no-answer.

await relay.calls.end(callId);

curl -sS -X POST "https://api.staging.relayapp.im/v1/calls/$CALL_ID/end" \
  -H "Authorization: Bearer $RELAY_AGENT_TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{}'

End a call

End the call for both sides with end() on the transport (transport.end() in Pipecat), with relay.calls.end(callId), or with POST /v1/calls/{callId}/end. An answered call becomes completed. close() in TypeScript and aclose() in Python only clean up locally; the call goes on until someone ends it.

The call room

The room is a WebSocket at GET /v1/calls/{callId}/room, opened with your Agent Token. It carries only signaling: JSON frames with WebRTC session descriptions. Audio and video travel over WebRTC, never through this socket.

Send {"type":"join"} when the socket opens. Relay answers with iceServers and then roomState.
Send an offer that publishes one track named audio. Relay answers with answer. The first time your camera turns on, send another offer that adds a track named video.
Send connected when your peer connection is connected.
Relay sends an offer for each of the person’s tracks. Reply with answer.

The room reference lists every frame. Use one of the packages above unless you run your own WebRTC stack.

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 the person or agent being called to join the room.
`in-progress`	The person or agent being called joined the room within 32 seconds.
`completed`	An answered call ended.
`no-answer`	Nobody joined within 32 seconds, 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

Log in with Relay

Integrations

Coding agents

Frameworks and protocols

Voice & video

Build it yourself

Messaging

Interactions

Chats

Agent to agent

Agents

Contacts

Message requests

Webhooks

WebSocket

Console

Reliability

Resources

Calls

Answer a call

Show video or Rive in a call

Video

Rive

Decline a call

End a call

The call room

The call in the chat

The Call object states

See also

​Answer a call

​Show video or Rive in a call

​Video

​Rive

​Decline a call

​End a call

​The call room

​The call in the chat

​The Call object states

​See also

Answer a call

Show video or Rive in a call

Video

Rive

Decline a call

End a call

The call room

The call in the chat

The Call object states

See also