Conversations & Messages

Conversation (Chat)

A Conversation (stored in the chats table) represents a threaded exchange between your organization and a contact on a specific channel. Each conversation is tied to one contact and one channel (WhatsApp, Facebook Messenger, Instagram, email, or internal).

Key fields

Field	Type	Description
id	UUID	Primary key
organization_id	UUID	Owning tenant
customer_id	UUID	Linked contact
channel	text	Channel identifier (whatsapp, facebook, instagram, email, internal)
status	text	Conversation state (open, closed, pending)
assigned_to	UUID	Agent handling this conversation
last_message_at	timestamptz	Timestamp of the most recent message
unread_count	integer	Number of unread inbound messages
metadata	jsonb	Channel-specific metadata

Lifecycle

1. Created — when a new inbound message arrives from an unknown thread, or an agent initiates an outbound conversation.
2. Open — actively being handled by an agent.
3. Pending — waiting for customer reply or internal action.
4. Closed — resolved; can be reopened if the customer sends a new message.

Message

A Message is a single communication unit within a conversation. Messages can be text, media (image, video, document, audio), template messages, or system events.

Key fields

Field	Type	Description
id	UUID	Primary key
chat_id	UUID	Parent conversation
sender_type	text	customer, agent, or system
sender_id	UUID	User or contact who sent the message
content	text	Message body (text)
media_url	text	URL of attached media
media_type	text	MIME type of media
message_type	text	text, image, video, document, audio, template, reaction
external_id	text	ID from the external platform (e.g., WhatsApp message ID)
status	text	Delivery status (sent, delivered, read, failed)
direction	text	inbound or outbound
created_at	timestamptz	When the message was sent/received

Channel-specific behavior

• WhatsApp: Messages flow through whatsapp-webhook (inbound) and whatsapp-send-message (outbound). Template messages use whatsapp-send-template.
• Facebook Messenger: Inbound via facebook-webhook, outbound via facebook-send-message.
• Instagram: Inbound via instagram-webhook, outbound via instagram-send-message.
• Internal: Used for internal team chat and ticket notes.

Thread

Conversations may contain sub-threads when a single contact has multiple open topics. In the current implementation, each channel-contact pair creates one conversation, with messages ordered chronologically.

Related tables

Table	Purpose
chats	Conversation records
messages	Individual messages
whatsapp_credentials	WhatsApp Business API credentials (per org)
message_templates	Reusable message templates