Inboxes

An inbox represents one organization channel and determines where incoming messages go. It may hold a connection to an external provider, such as a WhatsApp number or Instagram account, or expose a SquadOS-owned channel, such as a public page, widget, or the API.

Open Agents → Inboxes in the admin panel. The route requires permission to view inboxes. Creating, editing, reconnecting, and configuring service hours require write permission; deletion has its own delete permission.

What the list shows

The table shows Inbox, Destination, Last message, Status, and Actions. You can:

search by inbox name, channel identity, or agent name;
filter by channel types already used in the organization;
filter by Human support or With agent.

The status vocabulary depends on the channel type:

external channels show Connected or Disconnected. When a known cause exists, it appears below the status; Reconnect appears only for recoverable cases;
Public page and Widget show Live or Paused;
API shows Own channel in the list.

Available channels

The picker contains 11 types in three groups:

WhatsApp: WhatsApp by QR Code, WhatsApp (Z-API), WhatsApp (UAZAPI), WhatsApp (Evolution), and WhatsApp Official;
Instagram: Instagram Direct and Instagram Comments;
Other channels: Telegram, Public page, Widget, and API.

Instagram Comments may remain hidden while the integration awaits Meta approval. In that state, a regular organization sees ten options.

To compare WhatsApp connection methods, see WhatsApp customer service. For browser channels, see Public page and Widget. To integrate your own system, see API and Webhooks.

Connecting an inbox

Click Connect inbox.
Choose the channel.
Follow one of the flows below.

External channels

For the five WhatsApp channels, Telegram, and the two Instagram channels, you first complete the provider connection. The method varies: QR Code, instance credentials, bot token, or Meta authorization. The Who handles this inbox? step then asks for the destination and name.

The same external identity cannot belong to two active inboxes. If the number, bot, or account is already connected, the error identifies the existing inbox so you can open it and resolve the duplicate.

A later failure does not necessarily undo a connection already accepted by the provider. Before repeating the operation, return to the list and check whether the inbox or identity is already present.

Own channels

API, Public page, and Widget do not require authentication with an external provider. You choose the destination and name first:

API: finishes after that step and creates the endpoint;
Public page: asks for the page address and lets you set a welcome message;
Widget: asks for allowed domains and the chat’s appearance and behavior options.

Public page and Widget may also allow attachments when the inbox has an agent as its destination.

Choosing who handles it

The Destination field accepts:

Human support: the conversation enters the Conversations queue for an operator to answer;
an agent: the agent replies automatically using its prompt, tools, and knowledge bases.

Choose only an active agent. The creation list can currently also show inactive agents, but the runtime rejects messages routed to them. On webhook channels, that rejection may only acknowledge receipt to the provider without producing a reply to the contact.

With an agent selected, the suggested name follows Channel · Agent; with human support, it uses the channel name. You can replace the suggestion.

Editing the inbox

Open Actions → Edit. You cannot change the channel type; connect a new inbox to use another type.

Available options depend on the channel:

every inbox lets you change its name;
external channels show a Connection block where you can review setup, disconnect, or reconnect as supported by the provider;
the API lets you activate or deactivate the endpoint;
Public page and Widget let you pause or publish the channel and review its settings. Changing the public page address breaks the old link; the Widget’s internal address is not changed;
WhatsApp Official adds Message templates to the actions menu;
Public page provides Open page and Copy link; Widget provides Copy install code.

Advanced options

Under Advanced, you can configure:

AI agents for transfer: restricts which active agents can receive a manual transfer from this inbox. With no restriction, all are allowed;
Auto-close: completes the service after 1 to 168 hours without a new customer message. A blank value uses 168 hours (seven days); a new message reopens the conversation;
Service quality review: on completion, uses the selected model to generate a report for each participant. You set a minimum of 1 to 10 customer messages and see the credit estimate. With your own key, the interface states a fixed cost of one credit per review.

Saving the general fields and the allowed transfer-agent list uses two operations. If an error appears after saving, reopen the inbox and verify both sections before retrying.

Service hours

Open Actions → Service hours. When you create an inbox from the main list, this dialog also opens as a second step; you can select Set up later.

The schedule uses the organization’s time zone and lets you:

enable or disable the schedule;
create multiple time windows on the same day, each assigned to Human support or an active agent;
choose the Outside schedule destination used when no window applies, on closed days, and on holidays;
create date exceptions with a closed day or special windows;
set the human first-response target. Its clock pauses outside human windows and is for tracking only: it neither replies nor changes the destination;
enable Let AI take over already open conversations when routing switches from human to AI.

Automatic takeover only works in the human → AI direction and happens when the customer writes again. The schedule never removes a conversation from an agent to return it to the human queue. With the schedule disabled, every new message follows the inbox’s default destination 24 hours a day.

Disconnecting, pausing, or deleting

These actions have different effects:

Disconnect applies to external channels; it preserves the inbox and history but stops the provider connection;
Deactivate applies to API; it keeps the inbox and makes the endpoint inactive;
Pause applies to Public page and Widget; it takes the page or bubble offline without deleting history;
Delete removes the inbox from the list and cannot be undone.

When deleting, SquadOS checks for associated conversations:

with no conversations, the inbox and its credential are deleted;
with conversations, the inbox leaves the list, its credential is removed, and history preserves the channel each lead came through. The inbox no longer appears in the inbox filter;
for external channels, those conversations can no longer reply through the removed credential;
for API, Public page, and Widget, the interface states that existing conversations can still be answered.

When conversations exist — or while the count is still loading — confirmation requires typing the exact inbox name. To stop only new entries, choose the action appropriate for the channel type instead of deleting it.

Shortcut inside an agent

The agent editor also has an Inboxes section. It lists the inboxes that use that agent and, when you have both agent and inbox write permissions, offers Connect inbox with the agent already selected. The credential still belongs to the organization’s inbox; the editor is simply another entry point to the same flow.

Without both permissions, the section is view-only. See also Triggers overview.