Skip to main content
The POST /conversation/actions endpoint runs a group of up to 10 actions on a single conversation, in the order you send them. Instead of making N requests to label, leave a note and run the AI, you chain them in a single request.

​
The 12 actions

Each element of the actions array carries a type field. Almost all mirror an individual API endpoint; send_quick_reply_or_template is the exception: it sends the quick reply if the 24h window is open, or the template if it’s closed — the mode is decided by the server at runtime.
  • send_message — sends a message (text, media, quick reply, or template).
  • send_quick_reply_or_template — quick reply or template, depending on the window.
  • assign_label — assigns a label to the conversation.
  • remove_label — removes a label from the conversation.
  • assign_mailbox — moves the conversation to a mailbox.
  • context_note — leaves an internal note.
  • mark_resolved — marks the conversation as resolved.
  • mark_pending — marks the conversation as pending.
  • run_ai — runs the AI employee on the conversation.
  • ai_assistance — generates a suggested reply with the AI.
  • assign_ai_employee — assigns an AI employee to the conversation.
  • unassign_ai — removes the AI employee (hands the conversation off to a human). No fields; idempotent (no-op if the conversation already has no AI).
A group allows up to 10 actions, of which at most 3 can trigger the AI. Exceeding it fails with BATCH_LIMIT_EXCEEDED.

​
How it runs

1

Synchronous validation

The API validates the request. If the preflight rejects it (e.g. the AI has no tokens), it responds a synchronous 4xx and no action runs.
2

202 Accepted

If validation passes, it responds 202 immediately; the group runs in the background.
3

Execution in order

The actions run one by one, in the order sent.
The 202 confirms the group was accepted, not that every action succeeded. The per-action result does not travel in the response — query it in the conversation status or in the business’s activity log.

​
Stop on error

stop_on_error controls what happens when an action fails during execution:

​
Escalation to pending

escalate_on_error controls whether a group failure escalates the conversation to inbox_status='pending' for human review:
Integrator input errors (*_NOT_FOUND, *_AMBIGUOUS, WINDOW_CLOSED, TEMPLATE_NOT_APPROVED, etc.), billing guards (WALLET_BLOCKED, VISION_WALLET_BLOCKED), and the mark_resolved integrity guard (TRANSCRIPTION_REQUIRED_TO_RESOLVE) never escalate — fix and retry without human intervention.

​
Example

Label, leave a note and run the AI, without halting on failures:
Hand off to a human — a single unassign_ai action, no fields. It’s idempotent: if the conversation already has no AI, it’s a successful no-op.
Only need to hand off to a human and want the result right away? The synchronous POST /conversation/unassign-ai endpoint does exactly this and responds 200 with the real result ({ "ai_employee": null, "schedule_action": "cancelled" | "none" }), without the group’s async model.
If the preflight rejects the group, the response is a synchronous 4xx and no action runs. See Errors.