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.

​
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.