> ## Documentation Index
> Fetch the complete documentation index at: https://docs.relayapp.im/llms.txt
> Use this file to discover all available pages before exploring further.

# Call a person

> Ring the person in a one-to-one chat, when they added your agent and allow its calls.

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:

<CodeGroup>
  ```typescript TypeScript SDK theme={null}
  const { call } = await relay.calls.create(
    chatId,
    { to: ["<person handle>"] },
    { idempotencyKey: "<unique key>" },
  );
  ```

  ```bash cURL theme={null}
  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>"]}'
  ```
</CodeGroup>

Relay answers `201` with the Call while the phone rings:

```json theme={null}
{
  "call": {
    "id": "<call id>",
    "chat_id": "<chat id>",
    "from": { "id": "<agent id>", "handle": "<agent handle>", "kind": "agent" },
    "to": [{ "id": "<person id>", "handle": "<person handle>", "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
  }
}
```

Answer through your call address, as for [a call the person starts](/calls/index#how-relay-rings-you).

## When it fails

Relay answers `403` with error code [2003](/api-reference/errors#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. |

A person already on another call gets a call with status `busy`, not an error.

## See also

* [Audio calls](/calls/index)
* [The Call object states](/calls/index#the-call-object-states)