Inbox concepts

Inbox is the one place a customer conversation is recorded. Three products meet in it, and each one owns a different part:

Owner	What it owns
Connect	The transport: connected WhatsApp numbers and Facebook Pages, their credentials, the raw sends, and the WhatsApp template actions.
Inbox	The conversations and their transcripts, who is answering each one, assignment, queues, tags, quick replies and the auto messages.
A connected app (Commerce today)	Answering automated conversations, and what it knows about a customer: who they are and what they bought.

Inbox is sold on its own. A workspace with no other product set up still has a complete inbox — every conversation is answered by a person.

Channels

Inbox carries two channels, and they do not allow the same things. The rule lives in one table in the api, and every conversation reports its own answer in the window_open, templates and media fields, so a client never offers a control the channel would refuse.

	WhatsApp	Messenger
Customer address (peer_address)	Their phone number, or a WhatsApp username id	A Page-scoped id, never a phone
24-hour window for free text	Yes	Yes
Approved templates	Yes	No
Attachments	Yes	No
Write first	Yes	No
A bot can answer it	Yes	No
Connected apps see it	Yes	No

A Messenger conversation is always answered by a person, and no connected app is ever told about it — no order context, no contact details, no suggestions. Commerce matches customers to orders by phone number, and a Page-scoped id is not one, so letting an app see the conversation could attach it to a stranger.

Numbers and Pages are connected in Connect. Inbox then chooses which of the connected ones it receives on (Settings → Channels, workspace admins). Taking one out of Inbox does not disconnect it.

Conversations

A conversation is one person on one connection: the same customer writing to two of your numbers is two conversations, and writing again to the same number continues the one they already have. A person’s WhatsApp number and their WhatsApp username id count as the same person once an operator files the number on their contact, so they do not split into two threads.

A conversation is open or closed. Closing it takes it off the open lists; a new message from the customer reopens it, and so does sending a message on it. Conversations that arrive through a history import start closed and are dated by their messages, so an import does not flood the open list with old chats.

The conversation list has four views:

View	Shows
Mine	Open conversations assigned to you
Queue	Open conversations that sit in a queue (one queue, when you pick it)
All	Every open conversation you can see
Closed	Closed conversations

Filters combine with the view: a search over the name, number and last message, a tag, one or more connections, and waiting — open conversations where the customer spoke last and a person, not a bot, owes the answer. The unread counters beside each view count conversations with unread messages, per person.

Who answers: automated and human

Every conversation has a mode:

• automated — the workspace’s answering app replies.
• human — a person has taken it over and the app stays quiet.

Which app answers is a workspace setting, and there may be none. An app appears as an option only after it has been set up in this workspace — Commerce announces itself to Inbox when you configure its sales agent. A workspace that never chose an answerer adopts the first app set up; one where an admin chose people keeps that choice. With no app, and whenever people is chosen, every conversation is a person’s: answerer on the conversation is empty, the mode bar is hidden, and hand back is refused with 409 no_answering_bot, because there is nobody to hand to.

A reply is a takeover. Sending anything as a person — a reply, a template, an attachment — switches the conversation to human first, and assigns it to you if nobody had it. It never takes a conversation away from a teammate who already holds it. Take over does the same without writing yet; hand back returns it to the app.

Each takeover and hand-back moves the conversation’s automation_epoch. An app’s reply that was already on its way when you took over carries the old epoch and is refused with 409 human_takeover, so a bot message can never land after yours. Changing the answering app moves the epoch of every automated conversation for the same reason.

Note

A connected app can also escalate a conversation to a person on its own — for example when its agent cannot help. The conversation switches to human and an internal note records the reason.

The 24-hour window

WhatsApp and Messenger deliver free text only within 24 hours of the customer’s last message. window_open on each conversation says whether you are inside it. Inbox refuses a reply or an attachment outside the window (409 window_closed) before taking the conversation over, so a failed send never silences the bot on the way.

Outside the window:

• WhatsApp delivers only an approved template. The composer offers them, and sending one needs conversations.start as well as conversations.reply.
• Messenger has no templates. A conversation whose window closed waits for the customer to write again.

Sending a template does not open the window. It opens when the customer answers.

Templates

WhatsApp templates belong to the WhatsApp Business account behind your numbers, and Meta reviews each one. Inbox reads them through Connect and stores none:

• The Templates page lists every template with Meta’s status (APPROVED, PENDING, REJECTED and so on), for every member who can read the inbox.
• A workspace admin can submit a new one. Category is UTILITY or MARKETING; the name is lowercase letters, digits and underscores; the body is up to 1024 characters with {{1}}-style variables, each needing an example; header and footer up to 60 characters; up to three quick-reply buttons of 25 characters. Inbox checks these limits before submitting, because Meta’s rejection arrives hours later.
• Each app set up in the workspace lists the templates it sends. Inbox shows them as required with their live status, or MISSING when the account has no template by that name — the app’s messages that use it do not go out. An admin can retry creating them (ensure).

With more than one WhatsApp Business account behind Inbox’s numbers, every template call names the account; without one it uses the first.

Write first

Someone who has never written to you can only be reached with an approved template, so Write first is one step: give the number, pick a template, send. Sending it opens the conversation and files the person as a contact.

• It needs conversations.reply and conversations.start.
• It is WhatsApp only; Messenger cannot start a conversation.
• The conversation starts human, assigned to you, and is not handed to the answering app — nobody asked a bot to start it.
• Writing to someone who already has a conversation on that connection opens that conversation instead of a second one. If it is outside what you can see, the answer is 404.
• With several connections you pick which one it goes from, and only from the connections you work. With one, it is chosen for you.

There is no stored contact without a conversation. Inbox learns about a person by writing to them or being written to.

The transcript

Every message records who wrote it (author):

Author	Who
customer	The person on the other side
agent	The answering app’s bot
human	A teammate, from Inbox or one of its agent surfaces
merchant_device	The business phone itself, from a history sync
system	Inbox or an app, such as an auto message or a transactional notice

Messages you send carry a delivery_state that only moves forward: pending → sent → delivered → read, or failed. A send whose outcome could not be confirmed is unknown; it is never retried automatically, because retrying could send the customer the same message twice. Internal notes are internal.

The customer’s emoji reaction is shown on the message it reacts to, and a message that quotes an earlier one carries that quote.

Internal notes are messages of kind note. They are never sent, never take the conversation over, and need only conversations.note — so someone in the back office can leave context without being able to message customers.

Attachments

A message carries at most one attachment: an image, video, audio, document or sticker. The bytes live only in Drive, in the workspace’s Inbox attachments folder:

• Received files are copied into Drive as soon as they arrive, while the provider still holds them. A file that could not be copied then and has since expired at the provider answers 410 media_expired.
• Sent files are up to 16 MB. JPEG and PNG images up to 5 MB go out as images, MP4 and 3GPP as video, AAC, AMR, MP3, M4A and OGG as audio, and everything else — an image over 5 MB included — as a document. Captions are up to 1024 characters.

The web uploads the file itself. The assistant, MCP and the CLI send a file that is already in the workspace’s Drive, by its id.

Contacts

The contact list is one row per person, however many conversations they have, derived from the conversations themselves. Inbox stores only two things about a person, both typed by an operator:

• A name. Every incoming message overwrites the channel’s profile name; the one you type outlives it. Clearing it shows the profile name again.
• A phone number, for someone who wrote with a WhatsApp username and no number. You ask for it in the chat and file it. It is shown and searchable, and it joins their conversations under one person; replies still go to the address they wrote from.

Both need conversations.reply, and only for a person you can already see.

Who a person is beyond that — email, document, address, city — and what they bought come from the apps set up in the workspace, asked on every read and never stored in Inbox. Those details are shown only to members with contacts.details; without it they are simply left out, and the conversation still reads normally.

Connected apps beside a conversation

Every app set up in the workspace — answering or not — is told about WhatsApp conversations and contributes what it knows:

• Order context on the conversation list, such as the order status and number.
• Contact details and the customer sheet in the contact panel (with contacts.details).
• Suggestions: cards or buttons the app proposes beside a conversation. Opening one takes you to the app’s page; dismissing one needs conversations.reply.
• Internal notes an app writes, such as an order being created.

Replies your team sends are copied to each app’s history of that conversation, so an app that is not answering still sees both halves of it.

In the other direction, Commerce’s order page shows the buyer’s conversation from Inbox with a link to open it here. Order confirmations are Commerce’s: Inbox carries and records those messages, but confirming or correcting an order happens in Commerce.

Queues, assignment and tags

Queues are named, coloured groups of people, set up by a workspace admin. A conversation sits in at most one queue and has at most one assignee. New conversations land in the workspace’s default queue, when one is set. Deleting a queue leaves its conversations in place, in no queue.

• Assigning a conversation to yourself needs only conversations.reply.
• Assigning it to someone else, or moving it to a queue, needs conversations.assign.

Tags are labels with an optional colour, created by a workspace admin (names up to 40 characters, unique per workspace). A conversation carries up to 10; anyone with conversations.reply sets them. Deleting a tag removes it from every conversation.

Quick replies are saved texts called by a shortcut: type / in the composer. They belong to the workspace, and editing them needs quick_replies.manage. Commerce reads the same quick replies for its own order conversation, so an edit here is the edit everywhere.

Who sees what

On top of the permissions below, two workspace settings narrow what a member who is not an owner or admin can see. Owners and admins always see every conversation.

• Queues. A member in at least one queue sees those queues’ conversations plus the ones assigned to them. A member in no queue is not narrowed.
• Connections. A member with one or more connections listed sees only conversations that arrived on those. A member with none listed is not narrowed — an empty list means every connection, never none.

The two combine with AND. Being assigned a conversation does not get round the connection fence, which is why Inbox refuses to assign a conversation to someone who does not work its connection (422 assignee_out_of_scope), and to move it to a queue whose members all work other connections (422 queue_out_of_scope). Taking a connection away from someone releases their conversations on it back to the team.

A conversation outside what you can see answers 404, the same as one that does not exist, so the api never confirms it is there.

Roles and permissions

Inbox declares seven permissions that a workspace combines into its own roles under People (see Roles and permissions). A member with no Inbox role has them all; owners and admins are never limited.

Permission	Allows
conversations.view	Read conversations, messages, contacts, templates and the connection list
conversations.reply	Reply, send attachments, take over, hand back, close, reopen, assign to yourself, set tags, dismiss suggestions, and file a contact’s name or phone
conversations.start	Write first and send templates (on top of conversations.reply)
conversations.note	Add internal notes, without being able to reply
contacts.details	See what connected apps know about a person: email, document, address, and the customer sheet
conversations.assign	Assign to others and move conversations between queues
quick_replies.manage	Create, edit and delete quick replies

Configuration is workspace-admin only, whatever the role: queues and their members, settings, which channels Inbox receives, who works which connection, tags, and creating or re-provisioning templates.

Auto messages

An admin can set two automatic texts, sent by Inbox itself (author system):

• Greeting — sent once, to a conversation the moment it is first created.
• Away message — sent when a customer writes outside business hours, at most once every 12 hours per conversation.

Business hours are ranges per weekday in a time zone, and a range may cross midnight. With no hours set the business is always open, so the away message never goes out. Auto messages are best effort: one that fails to send never fails the incoming message. Commerce’s order flow settings edit the same greeting and away message, so the words stay in one place.

The three surfaces

Every Inbox verb reaches you three ways, all thin adapters over the same HTTP routes, so every permission and fence above applies to each:

• The assistant in the Inbox web app (POST /v1/chat).
• MCP tools named inbox_*.
• dst inbox in a terminal.

The assistant does not stop for an approval before acting. It is instructed to read a conversation before acting on it, never to send a customer message you did not ask for, and to show the exact text first when you only described it. Its turns draw on the workspace’s credits.