Inbox troubleshooting

A reply is refused with `409 window_closed`

Symptom: the composer offers no free text, or a reply from the API, MCP or the CLI fails with window_closed.

WhatsApp and Messenger deliver free text only within 24 hours of the customer’s last message. Inbox refuses the reply before anything else happens, so the conversation is not taken over and the bot is not silenced by a message that was never going to arrive.

WhatsApp: send an approved template instead. It needs conversations.start as well as conversations.reply.
Messenger: there are no templates. Wait for the customer to write again.

window_open on the conversation tells you which side of the window you are on. Sending a template does not reopen it; the customer’s answer does.

Hand back is refused with `409 no_answering_bot`

The workspace has no answering app — either none is set up, or an admin chose people in Settings → Auto replies and hours. There is nobody to hand the conversation to, so Inbox refuses rather than leave it unanswered.

Messenger conversations always behave this way: no app answers them.

Commerce is not offered as the answering app

An app appears in the answerer choice only after it has been set up in this workspace. Set up Commerce’s sales agent and connect it to Inbox from Commerce’s settings; Inbox then lists it. If nobody had chosen an answerer, Commerce starts answering. Connecting it never overrides a people choice an admin already made in Inbox — pick Commerce there afterwards.

The bot answered after I started typing

It should not deliver after you send. Sending anything as a person takes the conversation over first, and a bot reply that was already on its way is refused. Until you send (or press Take over), the conversation is still automated and the bot is still answering. Take it over first if you need time to write.

A teammate cannot see a conversation

Check, in order:

Their connections. A member with connections listed under Settings → Team and access sees only conversations that arrived on those — even ones assigned to them. That is why assigning a conversation to them is refused with 422 assignee_out_of_scope.
Their queues. A member in at least one queue sees those queues’ conversations plus the ones assigned to them, and nothing else.
Their role. Without conversations.view they see no conversations at all.

Owners and admins see everything. An empty connection list means every connection, never none.

A link to a conversation answers `404`

Inbox answers 404 for a conversation that does not exist, one in another workspace, and one outside your queue and connection fences — deliberately the same answer, so the API never confirms that a conversation you cannot see exists. Switch workspace, or ask an admin about your queues and connections.

Moving a conversation to a queue is refused with `422 queue_out_of_scope`

Every member of that queue works other connections, so the conversation would be invisible to all of them. Add a member who works the conversation’s connection, or pick another queue. An empty queue is always accepted.

Write first fails

Answer	Cause
The Write first button is missing	You need both `conversations.reply` and `conversations.start`
`422 channel_cannot_start`	The channel has no templates. Only WhatsApp can start a conversation
`422 channel_required`	You work several connections; pick the one to write from
`422 unknown_channel`	That connection is not one you work, or not one Inbox has
`422 no_channel`	No WhatsApp connection is available to you. Connect a number in Connect and select it for Inbox
`422 peer_and_template_required`	The number or the template is missing
`404`	The person already has a conversation on that connection, outside what you can see

Contact details or the customer sheet are empty

Email, document, address and what a person bought come from the apps set up in the workspace; Inbox stores none of it. The panel is empty when:

you do not have contacts.details — the details are left out rather than refused;
no app is set up in the workspace, or none knows this person;
the conversation is on Messenger — no app is told about Messenger conversations.

The same person appears in two conversations

A customer who writes with a WhatsApp username arrives under an id rather than a phone number. File their number on the contact (Contacts, or dst inbox contacts phone <peer> <number>) and later messages from either address continue in the conversation they already have. Two conversations that already exist are not merged.

The same person writing to two of your numbers is always two conversations: a conversation belongs to one connection.

A required template shows `MISSING`

An app set up in the workspace sends a template that the WhatsApp Business account does not have, so those messages do not go out. An admin can press ensure on the Templates page (or run dst inbox templates ensure <app>) to create them again; Meta then reviews them, and they work once APPROVED.

Answer	Meaning
`409 whatsapp_not_connected`	No WhatsApp account is connected. Connect one in Connect
`422 account_not_selected`	That WhatsApp Business account is not behind any number Inbox receives
`422 unknown_app`	The app is not set up in this workspace
`502 template_rejected`	Meta refused the template; `detail` carries its reason
`PENDING` after creating	Normal. Meta reviews asynchronously

An attachment fails

Answer	Cause
`413 attachment_too_large`	Over 16 MB
`422 media_unsupported`	The channel carries no attachments (Messenger)
`422 unknown_drive_file`	The Drive id is not a file in this workspace’s Drive
`422 caption_too_long`	Caption over 1024 characters
`410 media_expired`	A received file was never copied to Drive and the provider has since dropped it
`503 attachments_disabled`	This deployment has no Drive configured

An image that arrives at the customer as a document is expected: only JPEG and PNG up to 5 MB go out as images.

A message shows `failed` or `unknown`

failed means the provider refused the message; failure_reason says why. unknown means the send may or may not have gone out — the transport timed out or answered ambiguously. Inbox never retries an unknown send by itself, because a retry could send the customer the same message twice. Check with the customer or wait: a later delivery receipt moves the message forward.

The away message or greeting did not go out

The greeting goes only to a brand-new conversation, never to a customer writing again.
The away message needs business hours. With none set, the business is always open and the away message never fires. It also goes out at most once every 12 hours per conversation.
Both are best effort. A failed auto message never blocks the customer’s message from arriving.

Settings shows nothing I can change

Every section of Settings shapes the workspace, so it is for owners and admins. Quick replies have their own page, open to anyone with quick_replies.manage.

The assistant is off, or refuses

Answer	Cause
`503 chat_disabled`	No AI model is selected for Inbox. A platform admin selects one in the admin console
`429 quota_exceeded`	The workspace is out of credits for this period
`permission_required` / `admin_required` inside a reply	The assistant acts with your permissions; you lack that one

Conversations, contacts and settings are unaffected when the assistant is off.

`401 unknown_bearer_scheme` from the CLI or a script

Inbox accepts an identity Personal Access Token (idn_pat_…) and nothing else. Mint one from your account’s tokens page and log in with it:

echo idn_pat_… | dst login --token-file -
dst workspace switch acme-co

dst inbox checks the prefix before calling, and says so rather than sending a request that will fail.