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.

API status in the list

An API disabled under Edit inbox still appears as Own channel in the table. Check the connection block in the edit dialog before concluding that the endpoint is active.

Available channels

The picker contains 12 types in four groups:

• WhatsApp: WhatsApp by QR Code, WhatsApp (Z-API), WhatsApp (UAZAPI), WhatsApp (Evolution), and WhatsApp Official;
• Instagram: Instagram Direct and Instagram Comments;
• Email: Email (an existing mailbox over IMAP and SMTP);
• 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 eleven 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

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

External channels

For the five WhatsApp channels, Telegram, the two Instagram channels, and Email, you first complete the provider connection. The method varies: QR Code, instance credentials, bot token, Meta authorization, or the mailbox’s IMAP and SMTP details (see Email). 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.

Changing the destination later

The destination you pick here can be changed at any time under Actions → Edit → Who answers. The change applies to conversations that arrive from then on; the ones already open stay with whoever answers them. On API inboxes, agents that already have another API inbox appear unavailable in the list, because each agent has at most one. With Service hours enabled, the schedule decides who is responsible in each period, and the inbox destination applies again once the schedule is turned off.

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 and its destination, under Who answers;
• 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:

• Who the agent answers: restricts which senders reach the agent. It appears only on WhatsApp inboxes; see the section below;
• 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, the allowed transfer-agent list and, on WhatsApp inboxes, the sender list uses separate operations. If an error appears after saving, reopen the inbox and verify the sections before retrying.

Who the agent answers

On the five WhatsApp inboxes, Advanced starts with Who the agent answers. When the switch is on, only the senders on the list reach the agent. Everyone else comes in as Human support: the message is stored, the conversation shows up in Conversations for an operator to answer, the agent is never invoked and no credits are spent.

Each row on the list is a sentence — Answer whoever followed by the verb you pick:

• has the phone number: enter the number with its country code, such as +1 415-555-2671. The field immediately rejects a number without +, with too few digits, with too many digits or already on the list, and shows Compared as +14155552671, the exact value the rule will use. A Brazilian mobile number matches with or without the ninth digit, so entering one of the two forms is enough;
• has the tag: pick an organization contact tag. Someone writing for the first time has no tag yet and comes in as human support.

Switching the verb does not erase what you already typed on that row. The list also cannot be left on and empty: that state would leave the agent answering no one, and both the screen and the server refuse to save it.

What the list does not change

• Service hours are independent. The list applies even with Service hours turned off, and it is evaluated before them: a sender outside the list goes to human support even inside a window assigned to an agent, and the automatic takeover does not hand them back to the AI;
• A conversation already with the agent stays with it. The list governs the entry point. While AI is on in an ongoing conversation, the next message from that contact still goes to the agent even if they are outside the list.

Because of the second rule, with the list already saved and on, reopen Actions → Edit → Advanced: if any active conversation with AI on fell outside, the block shows the count and offers Turn AI off in N conversations. The action hands those conversations back to the team and records who turned it off; it requires permission to write inboxes and to manage conversations.

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.

Generic guidance in the dialog

The deletion dialog always recommends “Edit and disconnect.” For Public page and Widget, the correct action under Edit is to pause the channel; those two types do not have a disconnect command.

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.