Skip to content
Relay.chat

API for your bot

Each number has its own keys. A read-only key can see chats and messages. A read-and-send key can also write, within that number's limits. Limits are not split by key: two keys on the same WhatsApp share the same cap.

Put the key in the environment variable RELAY_WHATSAPP_API_KEY. The older name ENLACE_WHATSAPP_API_KEY still works. Do not write the key into instructions or a chat.

Base address: https://api.getrelay.chat

Spec: OpenAPI. Hosted MCP, with browser sign-in, is at https://api.getrelay.chat/mcp. A pasted key also works on that same path.

Authentication

Authorization: Bearer $RELAY_WHATSAPP_API_KEY

Hosted assistants can skip the key. They open the MCP URL, you sign in, and you pick the number. Disconnect them from My account.

Read chats

curl -s https://api.getrelay.chat/v1/chats \
  -H "Authorization: Bearer $RELAY_WHATSAPP_API_KEY"

Read messages

curl -s https://api.getrelay.chat/v1/chats/5215512345678@c.us/messages \
  -H "Authorization: Bearer $RELAY_WHATSAPP_API_KEY"

Send one text

Send permission only. One chat at a time. A list returns 400. The same text to 5 or more chats in 10 minutes returns 429. Opening more than 30 conversations in an hour also returns 429. A new conversation is a chat with no messages, or one whose last message is older than 24 hours.

curl -s https://api.getrelay.chat/v1/messages \
  -H "Authorization: Bearer $RELAY_WHATSAPP_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"chatId":"5215512345678@c.us","text":"Hello"}'

Responses that matter

  • 401: the key or assistant session is missing, wrong, revoked, or disconnected.
  • 403: this key can only read.
  • 409: WhatsApp is not linked. Scan another code.
  • 429: this number hit a limit. Wait. A notice is also emailed. conversation_start_limit is the cap of 30 conversations per hour. blast_not_allowed is the same text to too many chats.
  • 400 with code bulk_not_allowed: you tried to send to a list or broadcast. That cannot be turned off.

Webhooks

POST https://api.getrelay.chat/v1/webhooks with the URL and the events message or session.status. The secret is shown once. Each notice carries the signature X-Relay-Signature: sha256=… of the body, using HMAC SHA-256. Relay.chat does not store the message. It only forwards it.

Local MCP server

From the project folder: node apps/mcp/index.mjs. Set RELAY_API_URL and RELAY_WHATSAPP_API_KEY in the environment. ENLACE_API_URL and ENLACE_WHATSAPP_API_KEY still work as aliases. Tools: list_chats, read_messages, send_text, and get_account. send_text fails if the key is read-only.