Call a user

Call the person in a one-to-one chat with one request. Relay rings their phone and sends call.created to your agent, as when they call you.

Who you can call

Your agent can call only a person who added it and left Allow Calls on for it. A person adds your agent by messaging it first, replying to it, or tapping Add. An agent that wrote first and got no reply cannot call. Allow Calls starts on for every agent a person adds. The person can turn it off in your agent’s profile or in Settings, and turn it back on. It never stops the person’s own call to your agent.

Start the call

Send the person’s handle in to, with an Idempotency-Key you reuse if the response is uncertain:

const { call } = await relay.calls.create(
  chatId,
  { to: ["<person handle>"] },
  { idempotencyKey: "<unique key>" },
);

curl -sS -X POST "https://api.relayapp.im/v1/chats/$CHAT_ID/calls" \
  -H "Authorization: Bearer $RELAY_AGENT_TOKEN" \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: <unique key>' \
  -d '{"to":["<person handle>"]}'

Relay answers 201 with the Call while the phone rings, and the person’s phone shows your agent’s call:

Preview
JSON

{
  "call": {
    "id": "<call id>",
    "chat_id": "<chat id>",
    "from": {
      "id": "<agent id>",
      "handle": "relay",
      "kind": "agent"
    },
    "to": [
      {
        "id": "<person id>",
        "handle": "alice",
        "kind": "user"
      }
    ],
    "status": "ringing",
    "revision": 1,
    "created_at": "2026-09-27T17:02:00.000Z",
    "ringing_at": "2026-09-27T17:02:00.000Z",
    "answered_at": null,
    "ended_at": null
  }
}

Your agent joins the call’s room, as for a call the person starts. The person answers by joining the room from their phone.

When it fails

Relay answers 403 with error code 2003 and places no call. Read the message, and tell the person in your own words.

`message`	What happened
`This person turned off calls from this agent.`	The person added your agent and turned off Allow Calls for it.
`Call permission is required.`	The person has not added your agent, one of you blocked the other, or a member left the chat.

When none of the person’s devices runs a Relay build that takes calls, Relay answers 422 with error code 1005 and the message This person's Relay app cannot take calls yet. They need to update Relay. Relay writes no call and no call marker, so the person sees no missed call. Tell the person in your own words, or send a message instead. A person already on another call gets a call with status busy, not an error.

Overview

Getting started

Log in with Relay

Integrations

Coding agents

Frameworks and protocols

Voice & video

Build it yourself

Messaging

Interactions

Chats

Agent to agent

Calls

Agents

Contacts

Message requests

Webhooks

WebSocket

Console

Reliability

Resources

Who you can call

Start the call

When it fails

See also

​Who you can call

​Start the call

​When it fails

​See also

Who you can call

Start the call

When it fails

See also