Skip to content
Login
Core conceptsAPI v1

WhatsApp

Understand message delivery, the chat inbox, and the shared send limit for every tenant.

Understand how messages are sent

AV Bot stores outgoing messages and sends them using the tenant’s WhatsApp Business account. Different entry points share message tracking and the tenant rate limiter.

Entry pointSending pathWhen throttled
Public template APIDirect provider request during the HTTP call.Returns 429 with Retry-After. No SQS job is created.
Existing text-message APIDirect tracked provider request.Returns 429 with Retry-After.
CampaignCampaign execution → SQS → marketing consumer → provider.Job stays in SQS; its next attempt is delayed.
Chat inboxWebSocket command → tracked provider request.Caller receives a throttling error.
Automatic replyWebhook processing → tracked provider request.Reply remains pending for a later queue retry.

30 messages per tenant, per rolling second

30outbound send slots
per tenant / rolling 1,000 ms

The allowance is shared across API requests, campaigns, chat, automatic replies, and all sender numbers belonging to that tenant. Redis coordinates the counter across workers and server instances.

A practical example

Tenant A sends within one rolling secondSlots consumed
Campaign worker20
Public API8
Chat inbox2
Total30 / 30

The next public API send returns 429. The next campaign job stays in SQS to try later. Slots reopen as earlier sends leave the preceding 1,000 milliseconds. Tenant B has its own independent allowance of 30.

Rate-limit response
HTTP/1.1 429 Too Many Requests
Retry-After: 1
Content-Type: application/json

{"msg": "Tenant send limit reached"}

This is AV Bot’s application-level send limit. It does not guarantee provider acceptance or delivery. Provider rejections still appear as send failures. Listing templates and receiving messages do not consume outbound slots.

Track acceptance and delivery separately

A successful send response means Meta accepted the request. Store messageId to find the message in tenant history and providerMessageId to identify its provider record.

StateMeaning
QUEUEDA local outgoing message has been created; inspect its send state for the current outcome.
SENTThe provider accepted the send or a sent receipt was received.
DELIVEREDA delivery receipt was received.
READA read receipt was received; it may be unavailable for some recipients.
FAILEDThe provider rejected the send or reported a delivery failure.
REVIEW / unconfirmedThe provider outcome is uncertain. Check receipts before resending.

Receipts update persisted messages. Opening a conversation does not mark an outgoing message as read.

Work with the tenant chat inbox

Open the inbox from the tenant dashboard and choose a linked business number. History is scoped to that tenant, contact, and sender number. Campaign and API messages appear alongside normal chat messages.

The inbox enforces a 24-hour reply window after the customer’s latest incoming message to the selected number. Outside that window, send an approved template through the template API or a campaign. Blocked contacts cannot be messaged.

Inbox media sharing supports gallery JPG/PNG images up to 5 MB and supported PDFs. Inbound attachments use the tenant’s provider credentials on the backend.

Embed the inbox in another application

Receive incoming messages and status receipts

The shared Meta callback is https://avbot.server.avolvelabs.com/webhook/fb. The GET route verifies the callback using the configured verification token; POST validates the provider signature and publishes accepted events to the webhook queue.

The webhook consumer processes incoming messages, delivery receipts, and template status changes. Keep it running so sent messages and template approvals stay current in the dashboard.

Read the retry behavior
AV Bot · Developer documentationBuilt for better conversations.