# Relay Messenger

> Relay Messenger API v1 documentation.

- [Introduction](https://docs.staging.relayapp.im/index.md): Build agents that users message as Contacts in Relay Messenger.
- [Quickstart](https://docs.staging.relayapp.im/getting-started/quickstart.md): Receive one user Message through a webhook and send one reply.
- [Authentication](https://docs.staging.relayapp.im/getting-started/authentication.md): Authenticate Relay API requests with user sessions or Agent Tokens.
- [Client SDKs](https://docs.staging.relayapp.im/getting-started/sdks.md): Use the official TypeScript SDK for Relay v1 commands, webhooks, and WebSocket delivery.
- [Key concepts](https://docs.staging.relayapp.im/getting-started/key-concepts.md): Learn the shared Relay vocabulary used by every guide and endpoint.
- [AI coding agents](https://docs.staging.relayapp.im/getting-started/ai-agents.md): Give a coding agent the exact Relay documentation and audit prompts.
- [Best practices](https://docs.staging.relayapp.im/getting-started/best-practices.md): Build reliable Relay agents with durable events and idempotent commands.
- [Messaging](https://docs.staging.relayapp.im/guides/messaging/index.md): Send multipart Messages with text, media, links, replies, mentions, and reactions.
- [Sending Messages](https://docs.staging.relayapp.im/guides/messaging/sending-messages.md): Send a Message to a new or existing Relay Chat.
- [Mentions](https://docs.staging.relayapp.im/guides/messaging/mentions.md): Mention a current Contact in a group Chat using structured text metadata.
- [Message details](https://docs.staging.relayapp.im/guides/messaging/message-details.md): Read Message direction, delivery state, timestamps, parts, reactions, and history.
- [Message Parts](https://docs.staging.relayapp.im/guides/messaging/message-parts.md): Build ordered text, media, and link parts for a Relay Message.
- [Attachments](https://docs.staging.relayapp.im/guides/messaging/attachments.md): Allocate, upload, send, download, and delete Relay Attachments.
- [Voice memos](https://docs.staging.relayapp.im/guides/messaging/voice-memos.md): Send an uploaded audio Attachment as a Relay voice memo.
- [Rich link previews](https://docs.staging.relayapp.im/guides/messaging/rich-link-previews.md): Send one URL as a Relay link part.
- [Replies](https://docs.staging.relayapp.im/guides/messaging/replies.md): Reply to an exact Message part in a Relay Chat.
- [Reactions](https://docs.staging.relayapp.im/guides/messaging/reactions.md): Add or remove a standard or custom reaction on one Message part.
- [Delivery receipts](https://docs.staging.relayapp.im/guides/messaging/delivery-receipts.md): Read aggregate and per-recipient Delivered and Read state for direct and group Chats.
- [Chats](https://docs.staging.relayapp.im/guides/chats/index.md): Create and manage direct and group Relay conversations.
- [Group Chats](https://docs.staging.relayapp.im/guides/chats/group-chats.md): Create a Relay group Chat and update its name or photo.
- [Participants and Membership](https://docs.staging.relayapp.im/guides/chats/participants.md): Add, remove, leave, and interpret membership periods in a Relay group Chat.
- [Typing indicators](https://docs.staging.relayapp.im/guides/chats/typing-indicators.md): Start, refresh, stop, and receive ephemeral typing state for a Chat.
- [Sharing Contact Card](https://docs.staging.relayapp.im/guides/chats/share-contact-card.md): Share the authenticated agent's active Contact Card into an existing Chat.
- [Message history](https://docs.staging.relayapp.im/guides/chats/message-history.md): Page through visible Messages and ordered group-history events.
- [Contact Cards](https://docs.staging.relayapp.im/guides/contact-cards.md): Configure the name and photo an agent can share into a Chat.
- [Blocked Handles](https://docs.staging.relayapp.im/guides/chats/blocked-handles.md): Block direct Relay traffic while preserving existing history.
- [Agent Events](https://docs.staging.relayapp.im/guides/agent-events/index.md): Receive each Relay agent event through the path selected by saved webhook subscriptions.
- [Webhooks](https://docs.staging.relayapp.im/guides/webhooks/index.md): Receive signed Relay agent events at an HTTPS endpoint.
- [Webhook Subscriptions](https://docs.staging.relayapp.im/guides/webhooks/subscriptions.md): Create, list, update, and delete Relay webhook subscriptions.
- [Webhook Event Types](https://docs.staging.relayapp.im/guides/webhooks/events.md): Reference the Relay webhook envelope and current event types.
- [Webhook delivery](https://docs.staging.relayapp.im/guides/webhooks/delivery.md): Handle webhook timeouts, retries, duplicates, terminal state, and operator redrive.
- [WebSocket](https://docs.staging.relayapp.im/guides/websocket/index.md): Receive Relay agent events over durable WebSocket connections when no webhook subscription is saved.
- [WebSocket Protocol](https://docs.staging.relayapp.im/guides/websocket/protocol.md): Reference Relay WebSocket ready, event, error, heartbeat, and disconnect behavior.
- [WebSocket Acknowledgements](https://docs.staging.relayapp.im/guides/websocket/acknowledgements.md): Commit Relay WebSocket events durably before sending a cumulative ACK.
- [WebSocket FULL Sync](https://docs.staging.relayapp.im/guides/websocket/full-sync.md): Reconnect, replay current events, and rebuild durable state when a checkpoint is outside retention.
- [Idempotency](https://docs.staging.relayapp.im/guides/platform/idempotency.md): Retry Relay Message commands without creating duplicates.
- [Limits](https://docs.staging.relayapp.im/guides/platform/rate-limits.md): Reference Relay Message, Attachment, Chat, pagination, and delivery limits.
- [Debugging](https://docs.staging.relayapp.im/guides/platform/debugging.md): Use trace IDs, event IDs, and resource IDs to debug Relay integrations.
- [Examples](https://docs.staging.relayapp.im/examples/index.md): Choose a tested Relay integration path for webhooks, WebSocket, groups, or media.
- [Error Codes](https://docs.staging.relayapp.im/error/index.md): Handle Relay API errors by HTTP status, numeric code, and trace ID.
- [Error 1004: Handle is not in the Chat](https://docs.staging.relayapp.im/error/codes/1xxx/1004.md): Resolve Relay error 1004.
- [Error 1005: Invalid request](https://docs.staging.relayapp.im/error/codes/1xxx/1005.md): Resolve Relay error 1005.
- [Error 2001: Resource not found](https://docs.staging.relayapp.im/error/codes/2xxx/2001.md): Resolve Relay error 2001.
- [Error 2003: Permission denied](https://docs.staging.relayapp.im/error/codes/2xxx/2003.md): Resolve Relay error 2003.
- [Error 2004: Authentication required](https://docs.staging.relayapp.im/error/codes/2xxx/2004.md): Resolve Relay error 2004.
- [Error 2005: Attachment owner unavailable](https://docs.staging.relayapp.im/error/codes/2xxx/2005.md): Resolve Relay error 2005.
- [Error 2006: Invalid content](https://docs.staging.relayapp.im/error/codes/2xxx/2006.md): Resolve Relay error 2006.
- [Error 2007: Attachment not ready](https://docs.staging.relayapp.im/error/codes/2xxx/2007.md): Resolve Relay error 2007.
- [Error 2008: Rate limited](https://docs.staging.relayapp.im/error/codes/2xxx/2008.md): Resolve Relay error 2008.
- [Error 2015: Mentioned Handle left the Chat](https://docs.staging.relayapp.im/error/codes/2xxx/2015.md): Resolve Relay error 2015.
- [Error 2023: Mentions require a group Chat](https://docs.staging.relayapp.im/error/codes/2xxx/2023.md): Resolve Relay error 2023.
- [Error 2025: Blocked Handle not found](https://docs.staging.relayapp.im/error/codes/2xxx/2025.md): Resolve Relay error 2025.
- [Error 2026: Handle is blocked](https://docs.staging.relayapp.im/error/codes/2xxx/2026.md): Resolve Relay error 2026.
- [Error 3006: Unexpected server error](https://docs.staging.relayapp.im/error/codes/3xxx/3006.md): Resolve Relay error 3006.
- [API Reference](https://docs.staging.relayapp.im/api-reference/overview.md): Use the generated Relay v1 endpoint and schema reference.
- [List all chats](https://docs.staging.relayapp.im/api-reference/chats/list-all-chats.md): List Chats visible to the authenticated Contact.
- [Create a new chat](https://docs.staging.relayapp.im/api-reference/chats/create-a-new-chat.md): Create a direct or group Chat with its first Message.
- [Get a chat by ID](https://docs.staging.relayapp.im/api-reference/chats/get-a-chat-by-id.md): Retrieve one visible Chat.
- [Update a chat](https://docs.staging.relayapp.im/api-reference/chats/update-a-chat.md): Update a group Chat name or photo.
- [Add a participant to a chat](https://docs.staging.relayapp.im/api-reference/chats/add-a-participant-to-a-chat.md): Add a registered Contact to a group Chat.
- [Remove a participant from a chat](https://docs.staging.relayapp.im/api-reference/chats/remove-a-participant-from-a-chat.md): Remove a Contact from a group Chat.
- [Leave a group chat](https://docs.staging.relayapp.im/api-reference/chats/leave-a-group-chat.md): Leave a group Chat.
- [Start typing indicator](https://docs.staging.relayapp.im/api-reference/chats/start-typing-indicator.md): Start or refresh the authenticated Contact's typing indicator.
- [Stop typing indicator](https://docs.staging.relayapp.im/api-reference/chats/stop-typing-indicator.md): Stop the authenticated Contact's typing indicator.
- [Mark chat as read](https://docs.staging.relayapp.im/api-reference/chats/mark-chat-as-read.md): Mark visible Messages in a Chat as Read.
- [Share your contact card with a chat](https://docs.staging.relayapp.im/api-reference/chats/share-your-contact-card-with-a-chat.md): Share the authenticated agent's configured Contact Card into an existing Chat. Each successful call shares the card once.
- [Resolve a Chat and send a Message](https://docs.staging.relayapp.im/api-reference/messages/resolve-a-chat-and-send-a-message.md): Resolve or create a Chat, then send a Message.
- [Get messages from a chat](https://docs.staging.relayapp.im/api-reference/messages/get-messages-from-a-chat.md): List visible Messages and group-history events in a Chat.
- [Send a message to an existing chat](https://docs.staging.relayapp.im/api-reference/messages/send-a-message-to-an-existing-chat.md): Send a Message to an existing Chat.
- [Get all messages in a thread](https://docs.staging.relayapp.im/api-reference/messages/get-all-messages-in-a-thread.md): List a Message and its replies.
- [Send a voice memo to a chat](https://docs.staging.relayapp.im/api-reference/messages/send-a-voice-memo-to-a-chat.md): Send an uploaded audio Attachment as a voice memo.
- [Get a message by ID](https://docs.staging.relayapp.im/api-reference/messages/get-a-message-by-id.md): Retrieve one visible Message.
- [Add or remove a reaction to a message](https://docs.staging.relayapp.im/api-reference/messages/add-or-remove-a-reaction-to-a-message.md): Add or remove a reaction on one Message part.
- [Acknowledge message delivery](https://docs.staging.relayapp.im/api-reference/messages/acknowledge-message-delivery.md): A user client calls this after it durably applies this incoming Message and every earlier Message it received in the same Chat. The acknowledgement is cumulative through messageId for that user and Chat. Relay advances the sender-visible Delivered state only after every recipient has acknowledged. A…
- [Pre-upload a file](https://docs.staging.relayapp.im/api-reference/attachments/pre-upload-a-file.md): Create an Attachment upload allocation.
- [Get attachment metadata](https://docs.staging.relayapp.im/api-reference/attachments/get-attachment-metadata.md): Retrieve Attachment metadata and a download URL.
- [Delete an attachment](https://docs.staging.relayapp.im/api-reference/attachments/delete-an-attachment.md): Delete an unreferenced Attachment owned by the caller.
- [List blocked handles](https://docs.staging.relayapp.im/api-reference/blocked-handles/list-blocked-handles.md): List Handles blocked by the authenticated Contact.
- [Block a handle](https://docs.staging.relayapp.im/api-reference/blocked-handles/block-a-handle.md): Block direct traffic with a registered Handle.
- [Unblock a handle](https://docs.staging.relayapp.im/api-reference/blocked-handles/unblock-a-handle.md): Remove a Handle from the authenticated Contact's block list.
- [List available webhook event types](https://docs.staging.relayapp.im/api-reference/webhooks/list-available-webhook-event-types.md): List event names available to agent backends.
- [List all webhook subscriptions](https://docs.staging.relayapp.im/api-reference/webhooks/list-all-webhook-subscriptions.md): List webhook subscriptions for the authenticated agent.
- [Create a new webhook subscription](https://docs.staging.relayapp.im/api-reference/webhooks/create-a-new-webhook-subscription.md): Create a signed webhook subscription.
- [Get a webhook subscription by ID](https://docs.staging.relayapp.im/api-reference/webhooks/get-a-webhook-subscription-by-id.md): Retrieve one webhook subscription.
- [Update a webhook subscription](https://docs.staging.relayapp.im/api-reference/webhooks/update-a-webhook-subscription.md): Replace a webhook subscription's settings.
- [Delete a webhook subscription](https://docs.staging.relayapp.im/api-reference/webhooks/delete-a-webhook-subscription.md): Delete a webhook subscription.
- [Get contact cards](https://docs.staging.relayapp.im/api-reference/contact-card/get-contact-cards.md): Retrieve the authenticated agent's Contact Card.
- [Setup contact card](https://docs.staging.relayapp.im/api-reference/contact-card/setup-contact-card.md): Activate the authenticated agent's Contact Card.
- [Update contact card](https://docs.staging.relayapp.im/api-reference/contact-card/update-contact-card.md): Update the authenticated agent's Contact Card.
- [Connect an Agent WebSocket](https://docs.staging.relayapp.im/api-reference/websocket/connect-an-agent-websocket.md): Upgrade wss://api.relayapp.im/v1/websocket with Authorization: Bearer <Agent Token>. Relay does not use a query credential, cookie, or required subprotocol. If the Agent has any saved webhook subscription, Relay returns 409; delete the subscriptions to use the WebSocket.

## OpenAPI Specs

- [openapi.mint](/api-reference/openapi.mint.yaml)
- [openapi](/api-reference/openapi.yaml)