Inbound
¶ Message creates context
When a WhatsApp message arrives, ReplyBox ties the conversation to a contact identity instead of treating each thread as isolated inbox data.
Product guide
ReplyBox keeps a shared contacts directory around WhatsApp identities, so inbox conversations, CRM boards, tags, notes, and broadcasts can all refer to the same customer record.
Inbound
When a WhatsApp message arrives, ReplyBox ties the conversation to a contact identity instead of treating each thread as isolated inbox data.
Directory
The directory keeps phone numbers, display names, channel context, tags, notes, and conversation history together for scanning and handover.
CRM
Contact records become the bridge between live chat, pipeline stages, team ownership, and later broadcast audience filters.
Identity rules
Contacts represent reachable people or customer identities. Their history can span multiple conversations and operational surfaces.
Group chats are intentionally absent from the contacts dashboard because the group itself is not the same thing as a customer person.
A username-based LID is not equivalent to a phone number. Merge and backfill carefully when identities become clearer later.
Cloud API cannot address @lid or @g.us; send routing belongs through services/transport.py.
Directory surface
The contacts page should support repeated lookup work: search by name or phone, open a customer, review recent history, and jump back to the inbox without losing the team's place.
Maintenance
backfill-contact-phones
Recover phone fields where old identities or imports left contacts incomplete.
merge-username-contacts
Join username/LID-derived records into the clearer customer contact when the mapping is known.
resync-avatars
Re-probe contacts recorded as having no profile picture. Report-only by default; --apply enqueues the probes.
reconcile-tags
Repair tag rollups so inbox tags, directory tags, and broadcast audience filters agree.
Avatar recovery
resync-avatars is boundedScope
Targets rows where avatar_fetched_at IS NOT NULL AND avatar_object_key IS NULL. Contacts with a stored photo are left alone, and never-probed contacts stay covered by the existing catch-up lane on first message.
--limit 500 --active-days 30
Default limits that bound the enqueue volume. Use --organization-id and --channel-id to restrict the scope further.
AVATAR_REPROBE_PER_MINUTE
Rate limit for the reprobe lane, default 20 per minute per channel. Set it to 0 to disable the lane entirely.
Operational rule
Contacts are used by inbox assignment, CRM context, tags, and broadcasts. Merge records only when the identity is clear, and prefer idempotent repair commands over manual database edits.