Concepts

Pigeon has a small, predictable data model. Understanding these four ideas makes everything else click.

Threads

A thread is a single conversation. It’s a first-class Craft element, which is why it shows up in a filterable, searchable index in the control panel and supports the Trash. Each thread has a subject, a type, a status, and an optional assignee.

Participants

A participant is a party on a thread. There are two kinds:

Users — identified by their Craft user account.
Guests — identified by an email address and a private access token (no account required).

Each participant tracks its own read state, so unread counts are independent for every person — the admin, each user, and the guest all have their own “unread”.

Messages

A message is one entry in a thread. Most messages are normal replies, but a message can also be:

An internal note — visible to staff only, never shown to customers. See Attachments & notes.
A system event — an automatic entry recording something like a status change.

Messages can carry file attachments.

Thread types

Type	Who	Used for
`support`	Guest or user ↔ staff	“Ask customer service” inboxes
`direct`	User ↔ user	Private messages between Craft users

Statuses

Status	Meaning
`open`	Active conversation; last action was a staff reply (awaiting the customer).
`pending`	Awaiting a staff reply — the customer/guest wrote last. This is what the inbox badge counts.
`closed`	Resolved. A guest writing back automatically reopens the thread.

Pigeon flips a support thread’s status automatically as messages are posted, so “pending” always means “needs a human”.