SquidSupport
Product reference / AI

Handoff reasons

In the app: AI → Advanced → Handoff reasons

Needs the 'View AI Tools' permission.

When the AI hands a conversation to your team, it picks a reason from a fixed list. This page is that list: you decide which reasons exist, how each one is described to the AI, and which ones the AI may pick. The list belongs to the organization and is the same for every store.

Reason list

The list shows every reason in alphabetical order of its code. Each row shows:

  • the label, the name people see in reports;
  • the code, the short technical name that is stored with each hand-over;
  • a "Hidden from AI" badge on a reason the AI may not pick;
  • a "Needs an order" badge on a reason the AI may only pick once an order has been found in the conversation;
  • the description, when it has one.

The pencil opens a reason for editing and the bin deletes it. "Add reason" at the top opens an empty reason.

A new organization starts with 11 starter reasons, such as "Damaged or defective item", "Delivery problem" and "Other". When the list is empty, the page shows "No handoff reasons yet" with the button "Add the starter reasons", which adds those 11 again. The button only appears while the list is empty.

Seeing the list needs the 'View AI Tools' permission. Adding, editing, deleting and adding the starter reasons need the 'Edit AI Tools' permission; without it the buttons are greyed out and say which permission is missing.

Add or edit a reason

Needs the 'Edit AI Tools' permission.

"Add reason" opens "Add handoff reason"; the pencil opens "Edit handoff reason". Nothing is saved until you click "Save".

  • "Label": required, up to 255 characters. The AI reads it, and reports show it.
  • "Code": what is recorded with each hand-over. It is filled in from the label while you type a new reason, and you can change it before saving. It must be 2 to 64 characters: lowercase letters, digits and underscores, starting and ending with a letter or digit. Two reasons cannot have the same code. Once the reason is saved the code cannot be changed, because past hand-overs and reports use it.
  • "When to use it": optional. A sentence or two that tells the AI when this reason applies. The AI reads the label and this text to choose between reasons, so say what sets this reason apart from the others.
  • "Only with an order in the conversation": off by default. On, the AI can only use this reason after an order has been looked up in the conversation. If it tries earlier, it is told to look up the order first.
  • "Hide from the AI": off by default. On, the AI no longer sees the reason and cannot pick it. The reason stays in the list, and hand-overs that already carry it keep their label in reports.

A change applies to the AI's next reply, in every store. It is not part of a config set, so it does not wait for a release and cannot be rolled back with one.

Delete a reason

Needs the 'Edit AI Tools' permission.

The bin opens "Delete handoff reason". After you confirm, the reason is removed and the AI can no longer pick it. This cannot be undone.

Hand-overs that already used the reason keep its code, but reports can no longer show the label and show the code instead. To stop the AI from using a reason while keeping its label in reports, switch on "Hide from the AI" instead of deleting it.

How the AI uses the reasons

When the reason list can be read and at least one reason is visible to the AI, the AI must give one of the visible reasons every time it hands a conversation to a team. A hand-over without a reason, with a reason that does not exist, or with a hidden reason is refused, and the AI is told which reasons it can pick.

When the list is empty, or every reason is hidden, the AI hands conversations over without a reason. Those hand-overs show up in reports without a reason.

One store setting changes this: "Block uncategorized transfers to human team" under AI → Advanced settings. In a store where it is on, a hand-over without a reason, or with a catch-all reason such as "Other", is refused and the AI keeps the conversation. With an empty list, or with every reason hidden, this blocks the AI from handing over through its handoff tool. If Squid cannot read the reason list, it skips these reason checks. If it cannot read the store setting, it skips the store’s uncategorized-handoff block.

Some hand-overs are not the AI’s choice: a rule in Squid decides them, for example when a topic is set to "Human only" under AI → Coverage. Squid records its own built-in reason for that hand-over. Built-in reasons are not in this list and cannot be edited or picked by the AI.

When an offer flow is set to hand over after every offer was refused, it can use a reason configured for that offer flow from this list. If none is configured, or that reason is refused, Squid uses its built-in "Offers exhausted" reason instead.

The reasons appear in hand-over reporting, for example as "Top handoff reason" under AI → Coverage.

Some reasons carry extra rules that this page does not show and cannot change. The starter reason "Serious situation" is one: automatic reassessment does not give a conversation handed over with it back to the AI while that reason and its extra rule remain in the list.

This page does not decide when the AI hands over or which team gets the conversation. That follows from your AI's configuration under AI → Advanced settings.