Skip to main content
Endpoint · POST /conversation/actions
ai_assistance runs the AI employee you choose on the conversation without assigning it. It’s a one-off run: the employee runs transiently and produces its assistance (context/suggestion) on the conversation, but it does not become the assigned employee — the conversation stays with whoever handles it (another AI employee or a human), and the assignment doesn’t change. How it differs from the other AI actions:
  • run_ai runs the assigned employee —the one handling it— and takes the turn.
  • assign_ai_employee changes which employee handles the conversation.
  • ai_assistance runs another employee without assigning it — its output doesn’t change who handles the conversation.
Fields
  • ai_employee — { name } of the AI employee to consult (required).
  • instructions — optional text with the query or focus for the employee (for example, “Does this customer qualify for the enterprise plan?”).
It consumes tokens from the consulted employee’s model and counts as an AI-triggering action (maximum 3 per group, send_json included). In a list, this object goes in the actions array of a POST /conversation/actions — see Assembling an action list.
This action doesn’t check the 24h window, and the employee can reply to the customer.With the window closed the run executes anyway and consumes tokens:
  • If the employee’s instructions point to an action set with a template and it runs it, that template reaches the contact.
  • Any free text it sends is rejected by Meta: it’s marked as failed in the chat and the conversation escalates to pending. It does not arrive as a WINDOW_CLOSED action error — the per-action result comes back green, because the turn did run fine; what failed was the delivery.
  • An action set that only has a quick reply fails: the action comes back with AI_EXECUTION_FAILED, stops the list with stop_on_error and leaves the conversation in pending.
run_ai, assign_ai_employee with run and /conversation/smart-actions also run with the window closed, but they return WINDOW_CLOSED without running the employee if running with the window closed isn’t available. This action never does.If you don’t want to spend the turn, call POST /conversation/status and, if window.status is closed, send a template first. When the customer replies, the window opens again.
Employees on the new engine (v2). The assistance runs a v2 employee the same way as a classic one. If the v2 engine is turned off and ai_employee is v2, the group is rejected with AI_EMPLOYEE_V2_NOT_SUPPORTED (422). A conversation whose assigned employee is v2 doesn’t block the assistance: it only matters when a classic employee runs the assigned one (run_assigned). Then the group is rejected with the same 422, unless an earlier assign_ai_employee or unassign_ai in the group may change the assigned one: in that case the action fails per action, after the 202 and without escalating, if the assigned one is a v2 at that point (also when that assign just assigned it). See How it runs.
The run may leave a scheduled message behind. If the employee’s instructions or the conversation lead it to schedule itself, the conversation may end up with an active AI scheduled message. In an action list that affects the actions that follow: in a later assign_ai_employee always send scheduled_message_action (otherwise it may fail with SCHEDULED_MESSAGE_ACTION_REQUIRED), and a later cancellation or unassign_ai cancels the follow-up the employee just promised the customer. The run may also cancel the pending scheduled message. If it cancels one your team scheduled, the conversation moves to pending so a person reschedules it; it also moves to pending if the employee decides to schedule in a conversation with no AI assigned and wrote to the customer in that run. This capability is being enabled gradually. A v2 employee (new engine) doesn’t decide to schedule or cancel in this run, but its powers can change the active scheduled message: handing off to a human cancels it if an AI employee was handling the conversation, and assigning to another employee cancels it or, if an AI employee was already handling the conversation and the business configured it that way, transfers it.

Executable example

An ai_assistance on a conversation identified by phone and channel: it runs the chosen AI employee as a one-off, without changing the conversation’s assignment.

Request

Response

202 Accepted — the group was accepted and runs in the background. The per-action result does not travel in the response (query it later — see How it runs).
string
Always processing: confirms the group was accepted and is running.
integer
How many actions in the array were admitted for execution — not how many succeeded.