Identity
¶ WhatsApp number
Each channel represents one customer-facing WhatsApp identity, including the provider, pairing state, and routing context.
Product guide
Channels are the connected WhatsApp identities that ReplyBox uses to receive, route, and send customer conversations. A workspace can run Baileys WhatsApp Web channels, Meta WhatsApp Cloud API channels, or both during migration.
Identity
Each channel represents one customer-facing WhatsApp identity, including the provider, pairing state, and routing context.
Connector
Baileys channels keep a live socket in the connector process. Cloud API channels can coexist so a number can move across providers without breaking the docs model.
Workspace
Connected channels feed messages into the inbox, where assignment, tagging, ownership, notes, and replies happen.
Lifecycle
The channel exists but should not open a socket or send messages.
The connector starts the session and prepares a pairing attempt.
Admins pair by QR only. The QR event is pushed back to the app for the pairing modal.
The channel is usable for inbound messages, assignments, and outbound sends.
A connection attempt failed and needs a deliberate retry from the admin surface.
The WhatsApp session has ended and should not be auto-reconnected without user action.
Admin surface
Create a channel record for a WhatsApp identity before starting the pairing flow.
Open the QR pairing modal, watch the status change, and confirm the channel reaches connected.
Respect admin intent. A manually disconnected channel should stay disconnected until someone connects it again.
Remove stale identities carefully, especially when a number is moving between Baileys and Cloud API.
Queue channel work when message history or media needs to be reconciled after reconnecting.
Surface provider status clearly so inbox users know when replies are blocked by channel state.
Storage
Baileys auth state is encrypted and stored as one object at channels/{id}/auth.bin. Postgres keeps channel metadata; the session blob lives in object storage.
State reference
disconnected Admin stopped or not started.
connecting Connector is opening the session.
awaiting_qr Pairing requires a QR scan.
connected Inbox and sending can proceed.
failed Retry needs deliberate action.
logged_out Re-pair before use.
Pairing import queue
WhatsApp offers full history only when a companion is first linked, so to avoid connector memory and CPU spikes, first-time pairings may be queued before a QR code is requested. Queue and slot state live on the channel: pairing_queued_at, pairing_lease_at, import_slot_at, and import_seen_at, where NULL means not queued and no slot.
The channel card shows a “Queued for pairing — number N in line” panel in place of the disconnected prompt, and the pairing modal shows a “Waiting for a free slot” step instead of a QR frame. No QR is shown, and the usual “couldn't get a QR code” timeout is paused while queued.
The pairing screen renews a short-lived lease while it waits. A lapsed lease drops the queued pairing, so abandoned screens cannot block others. Closing the modal while queued gives up the place in line (the client sends DELETE pairing-queue), letting the next number proceed immediately.
Anyone who can view the channel sees its queued panel and 1-based position. When a slot frees, the QR appears automatically on the same pairing screen without pressing Connect again.
An admitted channel holds its import slot until the history import actually finishes, at a quiet period or a hard ceiling. Relevant API config: PAIRING_QUEUE_ENABLED, PAIRING_LEASE_SECONDS, PAIRING_SLOT_MAX_SECONDS, PAIRING_SCAN_WINDOW_SECONDS, and PAIRING_IMPORT_IDLE_RELEASE_SECONDS.