RelayPlus API

Introduction

The RelayPlus API is a versioned REST API. Every request goes to the base URL below, carries an API key, and gets JSON back. Version 1 covers the order-notification loop: describe the templates Meta approved for your workspace, create or update a contact, send a template to a phone number or reply inside the 24-hour window, list and tag contacts, read its delivery status, act on conversations — assign, change status, leave a note — and receive webhooks when it is delivered, read, or answered.

Base URL:

• All timestamps are UTC, ISO-8601.
• Money is { amount, currency } with amount an integer in minor units (cents, fils). Never a float.
• Identifiers are opaque strings. Do not parse them.
• Requests and responses are application/json.

Authentication

Create an API key in the RelayPlus admin under Settings → API & webhooks. Give it a name and only the scopes it needs. The key is shown exactly once; we store a hash, so if you lose it, create another and revoke the old one.

Send it on every request as a bearer token:

• A missing or unknown key is 401 with code unauthorized or invalid_token.
• A key without the scope an endpoint needs is 403 with code scope_required, and fields.scope names the scope.
• Keys act only within their own workspace. Another workspace’s ids are 404, never 403.
• Revoking a key takes effect on its next request.

Quickstart: notify a customer that an order shipped

Three calls. First, create or update the contact so consent and attributes travel with the number. Second, send the template. Third, read the status — or, better, subscribe to webhooks and let us tell you.

1. Upsert the contact:

2. Send the template

Find the template first with GET /templates — it tells you the header mode, how many body values, and which buttons want a value. Then send:

• Response 202: { "id": "msg_…", "status": "queued", … }. Queued means Meta accepted it; sent, delivered and read arrive later.
• A request with wrong parameters is refused before anything is created — no contact, no conversation, no webhook.
• The contact and the conversation are created if they do not exist.
• channelId is required only when the workspace has more than one WhatsApp number.

3. Read the status

The same three calls in Node

Or in Node, with fetch:

Templates and parameters

A WhatsApp template has up to four parts: a header (text or one media item), a body with positional {{1}}, {{2}} placeholders, a footer, and up to ten buttons. Meta approves each language variant separately, and only approved variants can be sent.

GET /templates describes every approved variant so you never guess:

• Marketing templates are refused with marketing_opted_out for a contact whose marketing consent is revoked. Utility and authentication templates are not affected by marketing consent.
• Language is Meta’s code exactly as listed — en_US, ar — and must match an approved variant.

Endpoint reference

• The complete, generated OpenAPI 3 document — every schema and every response — is at https://go.relayplus.app/swagger/public/swagger.json. It is built from the same source as the API, so it cannot drift from what the server does.

POST /messages/template

Sends an approved template to a phone number, creating the contact and conversation if needed. Scope messages:write. Honours Idempotency-Key.

POST /messages/text

Sends a free-form text reply — no template, no approval — but only inside the 24-hour customer service window. Give conversationId to reply into a thread you already have, or "to" with a phone number when you have no thread id; one of the two is required. It is sent as the API key rather than any agent: it claims nobody and leaves the conversation’s unread count untouched. Scope messages:write. Honours Idempotency-Key.

• Response 202: { "id": "msg_…", "conversationId": "cv_…", "contentType": "text", "status": "queued", … }.
• Outside the window, this is 422 window_closed — send a template instead.
• Neither conversationId nor to is 422 conversation_required.
• A contact that has never had a conversation is 422 no_conversation.
• An unknown contact or conversation id is 404 not_found.

GET /messages/{id}

The same shape as the send response, with the current status: queued, sent, delivered, read or failed. sent means Meta said so — never merely that we accepted it. On failed, failureCode is Meta’s numeric code and failureMessage its sentence. Scope messages:read.

POST /contacts

Creates a contact by phone number, or updates the one that already has it. 201 when created, 200 when updated. Absent fields are left unchanged. Scope contacts:write. Honours Idempotency-Key.

GET /contacts

Lists contacts in this workspace, ordered by id, wrapped in the same { items, nextCursor, total } envelope as every other list. Scope contacts:read.

GET /contacts/{id}

The same shape. Scope contacts:read. This is deliberately not the CRM view — no spend, notes or history — because a key is not a bulk-export tool.

POST /contacts/{id}/tags · DELETE /contacts/{id}/tags/{tag}

Add or remove tags on one contact directly, alongside the tags field on POST /contacts. Scope contacts:write.

POST takes { "tags": [...] } and adds them to the contact’s existing tags — a case-insensitive union, up to 50 tags per contact, each up to 64 characters. Both calls return 200 with the contact. Removing a tag the contact does not have is still 200, unchanged. A tag containing / cannot be removed through the URL in v1.1.

• A workspace rule on Tag added fires once for each tag actually added — not for one already present.

GET /conversations · GET /conversations/{id}

Lists or reads conversations in this workspace. Scope conversations:read.

POST /conversations/{id}/assign · status · notes

Three actions on one conversation, each scope conversations:write.

• A note is authored "API · <key name>" so agents can tell it apart from their own. @mentions in a note’s body resolve and notify exactly as an agent’s note would.

GET /templates

Approved variants, one item per name and language, with the parameter description shown above. Scope templates:read.

Errors

Every error has one shape. Branch on code; message is for humans and may change; fields names the offending part when there is one.

Rate limits

Each key has a fixed window of 60 requests per minute. Every response carries the numbers to back off from:

• Over the limit is 429 with code rate_limited, fields.dimension = "token", and a Retry-After header in seconds.
• X-RateLimit-Reset is a Unix timestamp — the top of the next minute.
• Use a queue and honour Retry-After rather than retrying in a tight loop. Higher limits are available on request.

Idempotency

Network calls fail after the server has acted. To retry a POST safely, send an Idempotency-Key header — any string up to 255 characters that is unique per action, such as your order id plus the event.

The same key with the same body within 24 hours returns the original response with Idempotent-Replayed: true and sends nothing again. The same key with a different body is 409 idempotency_conflict. A refused request (4xx) is not stored, so you may retry it with the same key after fixing it.

Webhooks

Subscribe an https endpoint under Settings → API & webhooks and choose events. Each delivery is one POST with a JSON envelope, signed so you can verify it came from us.

A delivery that does not get a 2xx is retried on a fixed schedule — see Delivery, retries and replay below. Answer 2xx within 10 seconds and do the work afterwards; deduplicate on the X-Relay-Delivery header.

Envelope and payload

• All payload keys are camelCase, for every event type.
• id is stable per event — use it to ignore a duplicate you have already processed. Status events carry the event time in the id, so a send that is retried and fails again is a new event, not a duplicate. Retries of one delivery carry the same X-Relay-Delivery header — that is the finer key to deduplicate on.
• message.received data also carries channelType (whatsapp, instagram, messenger); on Instagram and Messenger, from is the platform-scoped id, not a phone number.
• By default, message events carry ids and status only. Turn on “Include message content” on the subscription to receive the customer’s text and phone number on message.received (as body and from) and the text on outbound events. Off is the default because a misconfigured URL must not leak customer data.
• Correlate a reply to your own records through contactId — the id you received when you upserted the contact.

Verifying the signature

Every delivery carries X-Relay-Event, X-Relay-Timestamp (Unix seconds) and X-Relay-Signature, which is the lowercase hex HMAC-SHA256, keyed with your signing secret, of the string "<timestamp>.<raw body>". Verify against the raw bytes, before parsing, and reject anything older than a few minutes.

The same check in Python

Delivery, retries and replay

Delivery is at least once. A delivery is recorded before the first attempt is made, and is retried until it gets a 2xx, is rejected, or runs out of attempts.

A recovered endpoint drains up to five queued deliveries per 15-second pass, so a short outage clears quickly.

The platform sets how many attempts every endpoint gets, the same number for every workspace — default three: the first attempt plus two retries, about two and a half minutes apart in total. The ceiling is eight attempts, about 24 hours end to end.

Ordering is not guaranteed once anything has been retried — a later event can arrive before an earlier one that needed a retry. Order on occurredAt, not on arrival.

Retry schedule

Whatever the attempt budget, the spacing between attempts is fixed:

When an endpoint keeps failing

An endpoint with ten consecutive failed attempts spanning at least 24 hours — the platform default — is paused: the workspace’s admins and developers are notified, and nothing more is sent until someone re-enables it under Settings → API & webhooks. Re-enabling sends nothing by itself.

Every attempt is logged for 30 days with the exact payload and the response we got back. From the same screen you can replay one delivery, or every failed delivery since a chosen moment, up to 1000 per run. A replay keeps its original delivery id.

Headers on every attempt

What a good receiver does

A few habits keep a receiver in good standing:

• Answer 2xx in under 10 seconds, then do the work.
• Make handling idempotent on X-Relay-Delivery.
• Return 4xx only for a request you will never accept (bad signature, unknown event) — a 5xx means try again later.
• Keep the endpoint up: a paused endpoint receives nothing until it is re-enabled.

Automation hooks: call in, call out

Two doors into the automation engine that need no code on our side. An inbound URL starts one rule or one flow when your system calls it — a lead form, an order system, a Zap, a Make scenario, an n8n workflow. A flow’s HTTP request node, a flow’s Webhook node and a rule’s Call-a-webhook action call out from inside a conversation.

Outbound calls are made once, time out after 10 seconds, follow no redirects and are never retried — unlike webhook subscriptions, which are (see Delivery, retries and replay). A flow step needs its answer now. Targets on private, loopback or link-local addresses are refused before any request is made. Header values containing line breaks are dropped.

Inbound URL

Open a rule or a flow whose trigger is Inbound webhook received and choose Generate URL. The URL is shown once — copy it then. It is the credential: anyone holding it can start that one automation against contacts your workspace already has. Regenerate or Remove it under the same card; the old URL stops working on the next delivery.

POST a JSON object of at most 64 KB. Name the contact with contactId, or with phone in E.164 (+ and digits) — a missing + is added for you. The contact must already exist — an inbound URL never creates one; create it first with POST /contacts under an API key. A flow receives every field of the body as variables: {{payload.orderId}}, {{payload.items.0.sku}}. A rule runs its conditions and actions for that contact and receives no fields.

• Every delivery to a valid URL counts on the automation’s card, even one that is then rejected, so you can see your system is reaching us.
• A rejected delivery is also a row in Automation → Activity, under the automation’s name.

What a Webhook node or a Call-a-webhook action sends

One POST, application/json, in the same envelope as webhook subscriptions. type is rule.webhook or flow.webhook. The phone is included — you configured this URL on this automation for this purpose. When you set a signing secret on the node or the action, the request carries X-Relay-Timestamp and X-Relay-Signature exactly as subscriptions do, so the verifier you already wrote serves both; X-Relay-Event carries the type.

• A rule’s envelope carries "rule": { id, name } and "trigger" in place of flow, node and variables.
• A Webhook node with a body of its own sends that body verbatim instead of the envelope. An HTTP request node always sends exactly what is typed and is never signed — put your credential in its headers.

The HTTP request node

Method, URL, headers (one per line, Name: value) and body, each with {{name}} references replaced from the run’s variables. Save the response as r and later messages can say {{r}} for the body, {{r.httpStatus}} for the status code, and {{r.field}} or {{r.items.0.sku}} for any field of a JSON body. A response that is not 2xx, times out or cannot be reached leaves by the node’s error exit with the same variables set; a node with no error exit connected stops the run and the activity log names it.

MCP: use RelayPlus from an AI agent

RelayPlus is also an MCP server. Point any MCP client at the endpoint below with your API key as a bearer header and it gets the same fourteen operations as tools, under the same scopes, rate limit and idempotency rules as the REST API. Claude Code, Cursor, Claude Desktop and custom agents all support this today.

Endpoint (streamable HTTP):

• Tool arguments are the REST fields in snake_case (to, template_name, language, header, body, buttons, channel_id, contact_name, idempotency_key, conversation_id, assignee_id, status, tags, tag, search, cursor, limit). Each tool describes its arguments, so the model can fill them from list_templates.
• A tool error carries the same { code, message, fields } object as the REST API, as the error text.
• Actions taken through MCP are audited as an AI agent acting through your named key, so you can tell them apart from your own scripts.
• Hosted connectors that require an OAuth login (rather than a header you control) are not supported yet; the endpoint is designed so that can be added without changing the tools.

Client configuration

Claude Code (.mcp.json in your project), Claude Desktop (claude_desktop_config.json) and Cursor (.cursor/mcp.json) all take the same shape:

• Use a key with only the scopes the agent needs — an agent that only reads status needs messages:read and nothing else.
• Revoke the key under Settings → API & webhooks to cut the agent off at once.

Versioning and deprecation

• The version is in the path: /api/public/v1. Behaviour is stable within a version; fields may be added, never removed or renamed.
• A breaking change is a new version. The previous version stays supported for at least 12 months.
• Deprecation is announced at least 6 months ahead, with Deprecation and Sunset headers on affected responses and a note in the changelog below.

Changelog

• Questions or a limit increase: [email protected].