- Details: a few facts about your number, shared with Ringg so it can be registered.
- A WhatsApp service that does five jobs: forward messages, receive Ringg’s events, send them to Meta, report back, and pass on Meta’s statuses.
1. Details to share for setup
Share these for each WhatsApp number, separately for staging and production.2. 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: Ringg processes each message id once, so retries are safe.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. Ringg sends the next reply in a chat only after 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, or failed with Meta’s error. If expires_at has passed before you could send, don’t send: ack skipped.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. - Clocks. Keep your servers on NTP. A signature more than 300 seconds old is rejected.
3. 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.