Developers and the API
RelayOne has a REST API for building your own integrations, and outgoing webhooks for reacting to events in real time. Both live under Settings → API keys and Settings → Webhooks, admin and owner only.
API keys
An API key authenticates requests to RelayOne's public REST API. Create one from Settings → API keys → New API key: give it a name (name it after the integration that will use it) and pick only the scopes it needs.
Available scopes:
| Scope | Grants |
|---|---|
messages:send | Send messages |
messages:read | Read messages |
contacts:read | Read contacts |
contacts:write | Create and update contacts |
conversations:read | Read conversations |
broadcasts:send | Send campaigns |
orders:read | Read orders |
helpdesk:read | Read CSAT survey responses |
webhooks:manage | Create, update and delete webhook endpoints |
A key's scopes are all that gates what it can do — they're independent of the role of whoever created it. A key with no scopes at all can still call GET /api/v1/me to verify it works.
REST API basics
All public endpoints live under /api/v1 and require a bearer key:
Authorization: Bearer relay_live_xxxxxxxxxxxx
A few things that hold across every endpoint:
- Account-scoped. A key only ever sees and acts on the account it belongs to.
- Multi-number aware. If your account has more than one connected number, pass
?from=num_<uuid>to target a specific one; omitting it uses your default number. - Response envelope. Successful responses are wrapped as
{ "data": ... }; errors as{ "error": { "code": "...", "message": "..." } }. - Rate limited. 120 requests per minute per key. Going over returns
429 rate_limitedwith aRetry-Afterheader (andX-RateLimit-*headers on every response so you can see how close you are). GET /api/v1/meis the discovery endpoint — it tells you the account, the key's scopes, and the numbers available to it, which is the fastest way to sanity-check a new key.
Error codes worth knowing
| HTTP | Code | Meaning |
|---|---|---|
| 401 | unauthorized | Missing or invalid key |
| 402 | upgrade_required | The action isn't included in your plan |
| 402 | insufficient_balance | Your plan allows it, but the prepaid wallet doesn't have enough funds |
| 403 | forbidden | Key doesn't have the required scope |
| 429 | rate_limited | Over 120 requests/minute |
| 400 | bad_request | Malformed request |
| 404 | not_found | No such resource for this account |
| 500 | internal | Something went wrong on RelayOne's side |
upgrade_required and insufficient_balance are deliberately distinct 402s — one means "change your plan," the other means "top up the wallet" (see Usage and limits and Wallet).
Outgoing webhooks
No-code tools can use these too: see Zapier and Make.
Webhooks push events to your own HTTPS endpoint in real time, instead of you polling the API. Create one from Settings → Webhooks → New webhook: give it a URL (must be https://) and pick which events it should receive.
Available events:
| Event | Fires when |
|---|---|
message.received | An inbound WhatsApp message arrives |
message.status_updated | A sent message's delivery status changes (sent, delivered, read, failed) |
conversation.created | A new conversation is started |
order.created, order.paid, order.expired | A catalog order arrives, is paid, or its payment link expires |
contact.opted_out, contact.opted_in | A number opts out of marketing messages, or back in |
sla.breached, csat.responded | A conversation misses an SLA target, or a customer answers a CSAT survey |
contact.created, contact.updated | A contact is created, or its phone, name, email, company, avatar or owner changes |
tag.added, tag.removed | A tag is put on or taken off a contact |
conversation.assigned, conversation.closed | A conversation is assigned, reassigned or unassigned, or closed |
deal.stage_changed | A deal moves to another pipeline stage |
broadcast.completed | A campaign finishes sending |
The contact, tag, assignment, closing, deal and campaign events are sent within about a minute of the change, whoever made it — a teammate, an import, an automation or the API.
Delivery log
Every endpoint has a Deliveries button in Settings → Webhooks that shows its latest delivery attempts: the event, whether it was delivered, the HTTP status your endpoint answered, how long it took, and the attempt number. Filter by Succeeded or Failed, and open a row to see why it failed, what your endpoint answered, and the exact body RelayOne sent. Any member can view the log; it keeps 30 days.
Admins can Redeliver an attempt: RelayOne sends the same body again — same event id, so your receiver can deduplicate — with a fresh signature. Use it after fixing your endpoint to replay what it missed.
Verifying a delivery
Every delivery is signed. RelayOne sends a header:
X-RelayOne-Signature: t=<unix_seconds>,v1=<hex>
v1 is HMAC-SHA256(secret, "${t}.${rawBody}"), computed with the endpoint's signing secret. Verify it by recomputing the same HMAC over the timestamp and raw request body and comparing — reject anything that doesn't match, and reject stale timestamps to guard against replay.
A few operational notes:
- Endpoints are checked against SSRF risks (no pointing a webhook at your own internal network) before RelayOne will accept them.
- An endpoint that fails delivery repeatedly, past a threshold, is automatically disabled — a warning appears once it's most of the way there, so you have a chance to fix it first. A disabled endpoint has to be re-enabled manually once the underlying problem is fixed.
- Webhooks are a plan-gated feature and the number of endpoints you can create is capped by your plan (see Usage and limits).
The relay-mcp server
relay-mcp is a small Model Context Protocol server that wraps the public API, so an AI tool (Claude, or anything else that speaks MCP) can act on your RelayOne account directly. Point it at your account with two environment variables:
{
"mcpServers": {
"relay": {
"command": "npx",
"args": ["-y", "relay-mcp"],
"env": {
"RELAY_BASE_URL": "https://your-relay-domain.example.com",
"RELAY_API_KEY": "relay_live_xxxxxxxxxxxx"
}
}
}
}
By default it's read-only — tools like list_contacts, get_contact, list_conversations, list_messages and get_broadcast work out of the box, but nothing that writes or sends does. Opt in explicitly per capability:
RELAY_ENABLE_WRITES=true— unlockssend_message,create_contact,update_contact.RELAY_ENABLE_BROADCASTS=true— unlockssend_broadcast, which additionally requiresconfirm: trueon every call since it's marked destructive.
Who can manage this
API keys and webhooks are admin-and-owner gated, same as the rest of account-wide settings (see Members and roles).