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

POST
/conversations-bulk-actions

The API key must belong to an owner or admin of the organization.

Body

NameTypeRequiredDescription
organization_idintegerYesYour organization ID. Only conversations of this organization are changed.
actionstringYesOne of assign, update_status, assign_ai_assistant, move, cut_ai_context.
action_paramsobjectYesParameters of the action (table below).
conversation_idsinteger[]One ofConversations to change.
filterobjectOne ofInstead 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

actionaction_paramsEffect
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

StatusWhen
403 ForbiddenThe API key's user is not an owner or admin of organization_id.
400 / 500Neither 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.