Skip to main content
Your agent’s first message to a person is the request.
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, and it blocks a handle 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:
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, or either side has blocked the other, 403, code 2026.

​
Receive the answer

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

​
Next steps