Skip to main content
Ringg never holds your WhatsApp access token and never calls Meta for you: your WhatsApp service sits between Meta and Ringg, and the number stays in your own Meta account. Your human agents can work the same chats. When one of them steps away, you hand the conversation to the AI agent with the history so far, and it carries on from there.
If Ringg can hold your WhatsApp Business account instead, the standard WhatsApp setup is simpler: connect the account in the dashboard and Ringg talks to Meta directly. Relay is for businesses that need the account, the token and the Meta traffic to stay with them.

​
Before you start

A WhatsApp Business number you operate

In your own Meta account, with a WhatsApp service of yours that receives its Meta webhooks.

An API key

Your workspace key is sent as X-API-Key on every relay request.

​
How it works

  1. Forward: a customer messages your number. Meta notifies your service, and your service forwards the message to Ringg’s /inbound endpoint, signed with your keys.
  2. Reply: Ringg’s agent reads the whole conversation and writes a reply. Ringg posts it to your webhook as a message.outbound event, in a format you can send to Meta unchanged.
  3. Send and acknowledge: your service sends the reply to Meta, then reports the result to Ringg’s /ack endpoint. Ringg uses this to keep its record of the conversation true to what the customer actually saw.
Ringg can also open a conversation with an approved template, and close one with a final message. See Integration guide.

​
Key terms

​
Supported features

​
Messages from your customers

/inbound always answers 202 accepted once the message is safely recorded. Whether the agent replies is decided afterwards, so a 202 does not mean a reply is coming. See No reply for a message.

​
Messages Ringg asks you to send

​
Conversation features

​
Limits

​
Not supported yet

  • Media understanding: the agent cannot read images, voice notes or documents. This is planned.
  • Rich replies: the agent’s replies are plain text; Ringg never asks you to send media, interactive messages or WhatsApp Flows over the relay.
  • Template sends mid-conversation: templates are only used to start a conversation.

​
What you set up

​
Details to share for setup

Share these for each WhatsApp number, separately for staging and production.
Share the bearer token and receive the signing secret over a secure channel, never in a ticket or chat thread. Use different values for staging and production.

​
What your WhatsApp service must do

1

Forward customer messages to /inbound

For each message Meta sends to your webhook, POST Meta’s value object to Ringg’s /inbound, unchanged, with value.messages[0].id set to Meta’s message id. Retry on a timeout or a 5xx; each message id is processed once.
2

Sign every request

Send your workspace API key in X-API-Key, and an HMAC-SHA256 signature of the exact request body in X-Relay-Timestamp and X-Relay-Signature. See Authentication.
3

Receive Ringg's events on your webhook

Check the bearer token, store or queue the event, and answer 2xx within 10 seconds. Don’t wait for Meta before answering: the chat’s next reply waits for your 2xx.
4

Send each message.outbound to Meta, then ack it

POST delivery.message to Meta’s /{phone_number_id}/messages exactly as received, in delivery.sequence order per chat. Then call /ack with sent and Meta’s message id, failed with Meta’s error, or skipped if expires_at passed before you could send.
5

Forward Meta's delivery statuses (recommended)

POST the statuses array from Meta’s status webhooks to /status. Ringg uses them to diagnose delivery problems.

​
Also yours

  • The 24-hour window. Free-form replies only reach a customer within 24 hours of their last message. Ringg answers inside that window. Outside it, use an approved template through /outbound.
  • Media and interactive messages. The AI agent answers text only. Route images, voice notes, documents and interactive replies to your human agents. See What’s supported.
  • Handover. When a human agent hands a chat to the AI, send the conversation so far in prior_messages. When they take it back, stop forwarding that chat’s messages to Ringg. See Hand over from a human agent.
  • Custom variables. Send the customer details the agent’s prompt uses, such as a policy number, in custom_args on every /inbound. Ringg reads them only when a message starts a chat. See Custom variables.
  • Clocks. Keep your servers on NTP. A signature more than 300 seconds old is rejected.

​
Before you go live

1

Test on staging

Run your integration against Ringg’s staging base URL with your staging number. Cover a plain conversation, a handover with prior_messages, a failed ack and a /close.
2

Check delivery end to end

Confirm that every message.outbound you receive gets an ack, and that replies reach the customer in order.
3

Switch to production

Change the base URL, API key and signing secret to the production values Ringg gives you. Nothing else changes.

​
What Ringg provides

​
Credentials and endpoints

Ringg sends you these once your number is registered, separately for staging and production, along with the staging base URL. The production base URL is in the Integration guide.

​
Rotating the signing secret

Ringg can issue a new signing secret at any time while the old one keeps working. Switch your service to the new secret, confirm traffic is flowing, then ask Ringg to retire the old one. Requests signed with either secret are accepted in between, so there is no downtime.

​
The AI agent

Ringg sets up and maintains the AI agent attached to your number:
  • Prompt and tone: written for your use case, in the languages your customers use.
  • Knowledge: knowledge bases and tools, such as your product data, pricing APIs and document links.
  • Handover: the agent continues a conversation your human agent started, without greeting again or asking for what the customer already said.
  • Post-chat: analysis and chat events once a conversation closes.
Changes to the agent’s behaviour are made on Ringg’s side; your integration doesn’t change.

​
Delivery behaviour

Durable acceptance, once-only processing, ordered and retried replies, and what happens to replies the customer never saw: Delivery guarantees.

​
In the Ringg dashboard

  • Numbers: your relay numbers carry a Relay WhatsApp tag.
  • Logs → WhatsApp: every relay conversation, with its transcript and analysis. Where a human agent handed over, the transcript marks Handed over to AI agent and Handed over to human agent. The agent side is labelled Human agent or AI agent.

​
Support

What to send Ringg support is listed with the troubleshooting steps.

​
Delivery guarantees

What Ringg promises on every relay number; the request and response details are in the Integration guide.

​
FAQ

No. Ringg only receives the messages you forward and returns replies for you to send (how it works).
With the standard setup there is nothing to build; with Relay you run a service between Meta and Ringg. Choose Relay when the account must stay in your control, for example because your own CRM and human agents use the same number.
No. An account is either connected to Ringg directly or registered for Relay, never both. Ringg refuses a registration that would mix them.
Not yet: media messages are accepted but not answered, so route them to your human agents (what’s supported).
202 means the message is safely stored, not that a reply will follow. See No reply for a message.
Yes, on timeouts and 5xx: each message id is processed once, so a retry never causes a second reply.
When messages arrive close together, the agent answers them together, as a person would, instead of replying to each.
Ringg retries each reply for about two minutes, and later replies in the same chat wait behind it. If you receive a reply after its expires_at, ack it as skipped instead of sending it.
No. message.typing is optional. Sending it shows the customer that the message was read and a reply is coming, which makes the wait feel shorter.
You send the conversation so far in prior_messages when you hand over.
No. Ringg reads custom_args only from the message that starts a chat, so later messages can’t overwrite them. Send them with every message anyway: when a chat ends, the customer’s next message starts a new one, which reads them again. See Custom variables.
Yes, up to 200 messages; Ringg skips what it already has when each message carries Meta’s id.
Stop forwarding that chat’s messages and let your human agent answer (details).
That is set in the agent’s prompt, which Ringg agrees with you. By default, Ringg sets the agent up to write as your team, without a personal name, and not to volunteer that it is an AI. If a customer asks directly whether they are talking to a bot, it answers honestly and offers to have a person call them.
Only with an approved template, through /outbound, which follows WhatsApp’s 24-hour rule. You send the template; when the customer replies, the agent takes over.
Until one of the four closing conditions is met; the customer’s next message then starts a new chat.
Yes, in Logs → WhatsApp and through chat events on your own endpoint.
Ask Ringg for a new one; both work until the old one is retired (rotation).
Yes: different base URLs, API keys, signing secrets and number registrations (before you go live).

​
Next steps

Integration guide

The endpoints, events, signing and handover.

Troubleshooting

Rejected requests, missing replies and acks.