Run a bulk action on conversations
Apply the same change to many conversations in one request: assign an owner, change status, assign an AI assistant, move them in a pipeline, or cut the AI context. The action runs during the request and the response is the bulk action record with its result counts.
Bulk actions write directly to the database: they do not trigger automations, webhooks or realtime events that the same change would fire when made on a single conversation.
Endpoint
The API key must belong to an owner or admin of the organization.
Body
| Name | Type | Required | Description |
|---|---|---|---|
organization_id | integer | Yes | Your organization ID. Only conversations of this organization are changed. |
action | string | Yes | One of assign, update_status, assign_ai_assistant, move, cut_ai_context. |
action_params | object | Yes | Parameters of the action (table below). |
conversation_ids | integer[] | One of | Conversations to change. |
filter | object | One of | Instead of IDs, change every conversation matching the filter. Needs at least one of pipeline_id, pipeline_stage_id (null = Incoming column), status (open/closed), channel, assigned_user_id, assigned_ai_assistant_id. |
Send conversation_ids or filter. The schema also has a view_id field, but saved views are not resolved: a request with only view_id is rejected.
action_params per action
action | action_params | Effect |
|---|---|---|
assign | { "user_id": 12 } or { "user_id": null } | Sets or clears the human owner. |
update_status | { "status": "open" } or { "status": "closed" } | Opens or closes the conversations. |
assign_ai_assistant | { "ai_assistant_id": 3 } or { "ai_assistant_id": null } | Sets or clears the AI assistant. |
move | { "pipeline_id": 10, "pipeline_stage_id": 55 } | Moves to a conversation pipeline. pipeline_stage_id null or omitted = the pipeline's Incoming column. The stage must belong to the pipeline. |
cut_ai_context | {} | Sets ai_context_cut to now, so the AI assistant ignores every earlier message, and clears conversation_summary and handoff_reason. Adds a "✂️ AI Context Cut" system message to each conversation. No message is deleted. |
Request
Close every open WhatsApp conversation of one stage:
Response
The bulk action record. With a filter, conversation_ids contains the IDs it resolved to.
json
status is failed (with error_message) when the action could not run, for example a missing action_params value or a pipeline that does not exist. Bulk changes do not send assignment notifications or start automations.
Errors
| Status | When |
|---|---|
403 Forbidden | The API key's user is not an owner or admin of organization_id. |
400 / 500 | Neither conversation_ids nor a usable filter was sent, the filter has no restrictive field, or it matches no conversation. |
Report an issue with this documentation
Please log in to report issues with our documentation.