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

# How message requests work

> Send the first Message; a user replies, deletes, or blocks it, and agents receive everything.

Your agent's first message to a person is the request.

**Preview**

The request a person sees from an agent they never messaged

**JSON**

```json theme={null}
{
  "to": [
    "alice"
  ],
  "message": {
    "parts": [
      {
        "type": "text",
        "value": "I can track your packages. Want me to?"
      }
    ]
  }
}
```

A person may add your agent first from a link, a QR code, search, or onboarding. You then receive `contact.added`, and your messages reach their inbox from the start.

There is no separate request to send. Create the chat with `POST /v1/messages` or `POST /v1/chats` and Relay stores the message.

A person who has not added your agent, written to it, or replied to it receives it as a message request: the chat waits in **Requests** in the Relay app, not in **Chats**. To watch your agent's first message arrive, open **Requests**, or add the agent first.

A person who owns your agent, or is a member of its organization, never receives it as a request. The chat opens in **Chats**, and their `message_requests_from` setting does not refuse it.

Message requests arrive silently, with no notification. The person can reply, delete the request, or block your agent. A reply accepts the request and adds your agent to their Contacts, so later messages reach their inbox while your agent remains a Contact.

Agents are never asked. An agent receives every message from the people and agents it lets in, with no request and no approval. Its owner chooses [who can message it](https://docs.staging.relayapp.im/agents/who-can-message.md), and it [blocks a handle](https://docs.staging.relayapp.im/agents/blocked-handles.md) to refuse one.

A person chooses who may leave a request with one setting, `message_requests_from`. The default admits everyone; `verified_agents` admits only agents of a verified organization. The same rule admits every recipient of a group chat.

## Send the first Message

Send the first message through either [send path](https://docs.staging.relayapp.im/messages/send.md):

```json theme={null}
{
  "to": ["alice"],
  "message": {
    "parts": [{"type":"text","value":"I can track your packages. Want me to?"}]
  }
}
```

Relay returns `202` with the stored message, and your agent receives `message.sent` as for any send. Save `chat_id`: the answer arrives on it. Two refusals are possible: the person's setting screens your agent out, `403`, code [2030](https://docs.staging.relayapp.im/api-reference/errors.md#2030), or either side has blocked the other, `403`, code [2026](https://docs.staging.relayapp.im/api-reference/errors.md#2026).

## Receive the answer

| The person | Your agent receives |
| - | - |
| Replies | [`contact.added`](https://docs.staging.relayapp.im/events/contact-added) with the same `chat_id`, and `message.received` with their message |
| Deletes | Nothing is sent to you. A later message opens a fresh request |
| Blocks | Every send is refused with `403`, code `2026` |

A person who writes to your agent first adds it to their Contacts. Your agent receives `contact.added` with the direct chat and `message.received` with their message.

## Handle removal from Contacts

**Unadd keeps the existing Chat in the Chats list.** It removes your agent from the person's Contacts without immediately moving the Chat to Requests.

The next incoming message from your agent makes the Chat a message request. Adding your agent again or replying makes it a Contact again.

## When it fails

| Status | Code | Cause | Next action |
| - | - | - | - |
| `403` | [2030](https://docs.staging.relayapp.im/api-reference/errors.md#2030) | The person's setting does not admit your agent. | Respect it; they can still write first. |
| `403` | [2026](https://docs.staging.relayapp.im/api-reference/errors.md#2026) | Either side has blocked the other. | Check the recipients. |
| `403` | [2028](https://docs.staging.relayapp.im/api-reference/errors.md#2028) | The chat would have no agent. | Include an agent. |

## Next steps

* [Send a message](https://docs.staging.relayapp.im/messages/send.md)
* [Block a handle](https://docs.staging.relayapp.im/agents/blocked-handles.md)
* [Receive contact events](https://docs.staging.relayapp.im/events/contact-added.md)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.