Skip to main content
Endpoint · POST /conversation/actions
Two actions manage which AI employee handles the conversation: assign_ai_employee assigns it (optionally running it) and unassign_ai removes it (the conversation hands off to a human).

assign_ai_employee

Assigns an AI employee to the conversation. With run: true, it also runs it immediately (only then does it count as an AI-triggering action). Fields
  • ai_employee — { name } of the AI employee (required).
  • run — boolean (optional, default false). With true it runs the employee immediately after assigning it.
  • instructions — optional text with specific instructions for that run. Only applies with run: true.
  • scheduled_message_action — reassign | cancel. What to do with the conversation’s active scheduled message. Send cancel by default (see the warning).
Active schedule when reassigning. If the conversation is handled by an AI employee that left a pending scheduled message and you reassign it to another AI employee, the API requires you to decide what happens to that schedule: without scheduled_message_action the action fails with SCHEDULED_MESSAGE_ACTION_REQUIRED.
  • cancel — cancels the scheduled message; the new AI employee starts without it.
  • reassign — keeps the schedule and repoints it to the new AI employee.
Since the API doesn’t expose whether a conversation has an active schedule, the robust approach is to always send "scheduled_message_action": "cancel": it’s valid on any assignment and does nothing when there’s no schedule to cancel. Use reassign only when you reassign from one AI employee to another and want to keep the schedule — sending it in any other case fails with SCHEDULED_MESSAGE_ACTION_INVALID.
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. 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.
With run: true and 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). A v2 employee is assigned the same way as a classic one, and with scheduled_message_action: reassign the conversation’s scheduled message moves to it. With run, it runs: if the v2 engine is turned off, or if a classic employee in its chain runs it as the assigned one (run_assigned), the group is rejected with AI_EMPLOYEE_V2_NOT_SUPPORTED (422) and nothing is reassigned. Without run it’s always assigned. If the v2 engine is off, the conversation goes to pending when the customer writes, and if the scheduled message you moved to it with reassign fires while the engine is off, it’s cancelled without reaching the customer and the conversation goes to pending at that point. See How it runs.

unassign_ai

Removes the AI employee (the conversation hands off to a human). No fields; idempotent (a successful no-op if the conversation already has no AI). Cancels the AI’s active scheduled message, if any.
In a list, these objects go in the actions array of a POST /conversation/actions — see Assembling an action list.

Executable example

Two actions manage the AI employee of a conversation identified by phone and channel: assign_ai_employee assigns it (with run: true it also runs it) and unassign_ai removes it. Send scheduled_message_action: cancel by default; use reassign only when reassigning from one AI employee to another while keeping its scheduled message.

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.