Omnichannel inbox error codes (mpbx-channels)
Raised by the inbox routes and the provider webhook (W10-OMNI-01, W10-OMNI-05). Messages never contain message text, contact names or credentials; they name ids and field names at most. An id of another company is answered exactly like one that does not exist. Guide: Omnichannel inbox.
| Code | Kind | Meaning | What to do |
|---|---|---|---|
MPBX-INBOX-CHANNEL-NOT-FOUND | not_found | No channel with this id in your company. | Check the id. |
MPBX-INBOX-CONVERSATION-NOT-FOUND | not_found | No conversation with this id in your company. | Check the id. |
MPBX-INBOX-KIND-UNSUPPORTED | invalid_argument | The install has no connector for this channel kind yet. | Use one of available_kinds of GET /inbox/channels. |
MPBX-INBOX-INVALID | invalid_argument | A field is empty, too long, has control characters, or a cursor or timestamp is malformed. | Fix the named field. A message holds up to 4096 characters, a channel name up to 80. |
MPBX-INBOX-CREDENTIALS-INVALID | invalid_argument | The credentials do not have the shape the channel needs (Telegram: {"bot_token": "<bot id>:<secret>"} and nothing else). | Paste the token exactly as @BotFather shows it. |
MPBX-INBOX-CREDENTIALS-REJECTED | invalid_argument | The provider refused the credentials (Telegram getMe answered 401/404, or the token is not a bot's). | Create a new token with @BotFather (/token). |
MPBX-INBOX-CREDENTIALS-UNREADABLE | config | The stored credentials cannot be opened (wrong master key or a damaged row). | Reconnect the channel with fresh credentials. |
MPBX-INBOX-CHANNEL-NAME-TAKEN | conflict | Another channel of your company has this name (case-insensitive). | Choose another name. |
MPBX-INBOX-CHANNEL-IN-USE | conflict | The channel still has conversations. | Switch it off instead. |
MPBX-INBOX-ROUTE-INVALID | invalid_argument | The route is malformed (a target without a kind or the reverse), a transfer has no target, or the target does not exist in your company. | Name an existing queue, ring group, extension or active user. |
MPBX-INBOX-ALREADY-TAKEN | conflict | Another agent has the conversation. | Ask them to transfer it, or have it assigned to you. |
MPBX-INBOX-CONVERSATION-ARCHIVED | conflict | The conversation is archived; nothing changes it any more. | The contact's next message opens a new conversation. |
MPBX-INBOX-USER-UNKNOWN | invalid_argument | The assignee is not an active user of your company. | Check the user id. |
MPBX-INBOX-NOT-A-USER | permission_denied | Taking a conversation and replying need a signed-in user; an API key has no inbox seat. | Sign in as a user. |
MPBX-INBOX-VERSION-MISMATCH | conflict | The conversation changed since you read it (If-Match). | Read it again and retry. |
MPBX-INBOX-WEBHOOK-NOT-FOUND | not_found | No enabled channel of this kind at this webhook address. | Copy webhook_path from the channel, or register the webhook again. |
MPBX-INBOX-WEBHOOK-UNAUTHORIZED | unauthenticated | The webhook call did not carry the channel's secret token. | Register the webhook again (POST /inbox/channels/{id}/webhook). |
MPBX-INBOX-WEBHOOK-PAYLOAD-INVALID | invalid_argument | The webhook body is not what the provider sends. | None; the provider retries valid updates. |
MPBX-INBOX-PROVIDER-FAILED | invalid_argument | The provider refused an outbound message or a webhook registration (for example, the contact blocked the bot). | See the message's error_code; the contact may have to write first. |
MPBX-INBOX-PROVIDER-UNAVAILABLE | unavailable | The provider could not be reached or rate-limited the call. | Retry later. |
MPBX-INBOX-PUBLIC-URL-MISSING | config | The install has no public https address ([setup] fqdn or http.base_domain), so providers cannot reach its webhooks. | Set the address and make it reachable over HTTPS from the internet. |
MPBX-INBOX-TEMPLATE-NOT-FOUND | not_found | No reply template or quick reply with this id in your company. | Check the id. |
MPBX-INBOX-TEMPLATE-SHORTCUT-TAKEN | conflict | Another template or quick reply of the same kind has this shortcut. | Pick another shortcut. |
MPBX-INBOX-WINDOW-CLOSED | conflict | Free text is not allowed now: the contact's last message is older than the channel's reply window (WhatsApp and Messenger 24 hours; Messenger up to 7 days with the human-agent tag). Nothing was stored or sent. | WhatsApp: send an approved template ({"template": {...}}). Otherwise wait for the contact to write. See meta-byok-setup.md. |
MPBX-INBOX-TEMPLATES-UNSUPPORTED | invalid_argument | The channel does not send template messages (only WhatsApp does). | Reply with text. |
MPBX-INBOX-WEBHOOK-MANUAL | conflict | The webhook of a WhatsApp or Messenger channel cannot be registered by MonoPbx because the credentials have no app_id. | Set the callback URL and verify token in the Meta app dashboard, or connect the channel again with app_id. |
MPBX-INBOX-WIDGET-INVALID | invalid_argument | A live chat widget setting or a visitor field is not acceptable (colour not #rrggbb, an origin that is not https://host[:port], an address that is not IPv4 or IPv6, an e-mail address that is not one, text too long, a body that is not JSON). | Fix the field named in the detail. |
MPBX-INBOX-WIDGET-FIELD-REQUIRED | invalid_argument | A pre-chat field the widget requires was left empty, or an offline message came without an e-mail address or phone number to answer. | Ask the visitor for the field. |
MPBX-INBOX-WIDGET-ORIGIN-NOT-ALLOWED | permission_denied (403) | The page that embeds the widget is not in the channel's allowed_origins (or sent no Origin). The answer carries no CORS headers, so browsers block it. | Add the site's origin (https://www.example.com) under Live chat > Allowed websites. |
MPBX-INBOX-WIDGET-BANNED | permission_denied (403) | The visitor's address is on the widget's banned list. | Remove the address from Live chat > Banned addresses if it was added by mistake. |
MPBX-INBOX-WIDGET-NOT-LIVE-CHAT | invalid_argument | The widget settings were asked for a channel that is not a live_chat channel. | Use the id of a live chat channel. |