Realtime Inbox WebSocket API · WABPO Developer Documentation
Realtime Inbox WebSocket API
A technical guide to implementing a two-way WhatsApp inbox. This document outlines the server-to-server WebSocket relay pattern, event packet schemas for message streaming, and HTTP endpoints for conversational metadata, history retrieval, and free-text/media replies.
Realtime Inbox (Two-Way Messaging)
Use this specification when your CRM, POS, ERP, or customer portal requires a reactive, two-way WhatsApp inbox.
To maintain security, your server communicates directly with WABPO's WebSocket infrastructure using your secret API key. Your backend then relays these realtime messaging events down to your own client-side dashboard interface.
⚠️ Security Architecture Rule: Never expose your secret API key in frontend or browser code. The browser client must establish a connection with your backend server, not directly with WABPO.
1. Connection Architecture
Plaintext
Server-to-Server (API Key + Project ID)
WABPO WebSocket ──────────────────────────────────────► Your Backend Server
│
│ Your own session auth
▼
Your Dashboard Frontend
While realtime events stream over WebSockets, use standard HTTP requests to manage baseline data, pull historical archives, and send direct chat replies.
⚠️ Meta Policy Rule: Text replies only deliver if the customer sent a message within the last 24 hours. Outside this window, you must call the template messaging endpoint instead.
Form Fields:projectId: PROJECT_IDclientMessageId: crm-image-1001caption: Optional text captionfile: [Binary File Blob]
4. Implementation Rules for Developers
Persist Identifiers: Always store the returned projectId, conversationId, messageId, and clientMessageId within your app's local database.
Deduplication: Always pass a unique clientMessageId with every outbound reply. If network drops cause your server to retry the request, WABPO drops the duplicate instead of sending it to the user twice.
Media Expiration: The mediaUrl returned in inbound events contains a temporary, time-restricted access signature. Do not cache this URL long-term. If an image or voice note fails to load later in your UI, call the paginated chat history API to get a fresh download link.
Media Format Constraints: * Audio:audio/ogg, audio/mp4, audio/mpeg, audio/aac. Browser-native audio/webm files are automatically recoded by WABPO prior to Meta routing.Images: JPEG, PNG, WebP.Videos: MP4, 3GPP.
