Skip to main content
Endpoint · POST /conversation/actions
Runs an AI employee. ai_employee is optional — without it, it uses the one assigned to the conversation. instructions is optional. Fields
  • ai_employee — { name } of the AI employee (optional; without it, uses the one assigned to the conversation).
  • instructions — free text (optional).
In a list, this object goes in the actions array of a POST /conversation/actions — see Assembling an action list.
With the 24h window closed, the employee still runs and the action doesn’t fail because of the window, so it doesn’t stop the list even if stop_on_error is true. If its instructions point to an action set with a template, that template reaches the contact; otherwise its free text isn’t delivered and the conversation moves to pending. An action set that only has a quick reply does fail, with AI_EXECUTION_FAILED, and stops the list. It only fails with WINDOW_CLOSED if running with the window closed isn’t available. Details in ai_assistance.
Employees on the new engine (v2). run_ai runs a v2 employee the same way as a classic one, with its powers. If the v2 engine is turned off, a run_ai that would run a v2 —the ai_employee you name or, without it, the assigned one— is rejected with AI_EMPLOYEE_V2_NOT_SUPPORTED (422). A v2 assigned one only matters when a classic employee —the one you name or one in its chain— runs the assigned one (run_assigned): then the group is rejected with the same 422, because a classic employee’s action sets don’t run a v2. Two cases fail per action, after the 202, without escalating: a run_ai without ai_employee preceded by an assign_ai_employee in the group, when the new assigned one is a v2 and the engine is turned off, and an action whose classic employee runs the assigned one (run_assigned) when, after an earlier assign_ai_employee or unassign_ai, the assigned one is a v2 (because that assign assigned it, or because it didn’t end up changing 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

A run_ai on a conversation identified by phone and channel. With ai_employee it runs an explicit employee; without it, it runs the AI employee assigned to the conversation. instructions is optional.

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.