> ## Documentation Index > Fetch the complete documentation index at: https://dev.docs.1to1ai.com/llms.txt > Use this file to discover all available pages before exploring further. # Visão geral > Execute até 10 ações sobre uma conversa em uma única requisição. **Endpoint** · `POST /conversation/actions` O endpoint `POST /conversation/actions` executa um **grupo de até 10 ações** sobre **uma única conversa**, na ordem em que você as envia. Em vez de fazer N requisições para etiquetar, deixar uma nota e executar o AI, você as encadeia em uma única requisição. É o caminho recomendado para modificar uma conversa a partir de um cliente externo. Cada elemento do array `actions` leva um campo `type`. `send_message` unifica os quatro modos de envio (texto, mídia, resposta rápida, template). `send_quick_reply_or_template` é a única cujo modo é decidido pelo servidor: envia a resposta rápida se a [janela de 24h](/pt/conversations) estiver aberta, ou o [template](/pt/templates) se estiver fechada. | Ação | O que faz | Dispara AI? | | -------------------------------------------------------------------------------- | ------------------------------------------------------------- | ------------------ | | [`send_message`](/pt/action-groups/send-message) | Envia uma mensagem: texto, mídia, resposta rápida ou template | Não | | [`send_quick_reply_or_template`](/pt/action-groups/send-quick-reply-or-template) | Resposta rápida ou template conforme a janela | Não | | [`assign_label`](/pt/action-groups/assign-label) | Atribui uma ou várias etiquetas | Não | | [`remove_label`](/pt/action-groups/remove-label) | Remove uma ou várias etiquetas | Não | | [`assign_mailbox`](/pt/action-groups/assign-mailbox) | Move a conversa para uma caixa de entrada ou categoria | Não | | [`context_note`](/pt/action-groups/context-note) | Deixa uma nota de contexto | Não | | [`mark_resolved`](/pt/action-groups/conversation-status) | Marca a conversa como resolvida | Não | | [`mark_pending`](/pt/action-groups/conversation-status) | Marca a conversa como pendente | Não | | [`run_ai`](/pt/action-groups/run-ai) | Executa o funcionário AI atribuído (ou um explícito) | Sim | | [`ai_assistance`](/pt/action-groups/ai-assistance) | Consulta outro funcionário AI para uma resposta sugerida | Sim | | [`assign_ai_employee`](/pt/action-groups/ai-employee) | Atribui um funcionário AI (com `run: true`, também executa) | Só com `run: true` | | [`unassign_ai`](/pt/action-groups/ai-employee) | Remove o funcionário AI (passa para humano) | Não | | [`cancel_schedule`](/pt/action-groups/cancel-scheduled-message) | Cancela o agendamento ativo: mensagem ou execução de AI | Não | Um grupo admite até **10 ações**, das quais no máximo **3** podem disparar o AI. Excedê-lo falha com `BATCH_LIMIT_EXCEEDED`. Cada ação tem sua própria página com seus campos e um exemplo — abra a que precisar pela tabela ou pelo nav. Para enviar mídia, primeiro envie o arquivo com o fluxo de [Enviar mídia](/pt/action-groups/upload-media). ## Identificar a conversa O grupo roda sobre **uma** conversa: você a identifica com o objeto `conversation`, que leva **exatamente um** de `uuid`, `whatsapp_user_id`, `username` ou `phone`, **mais `channel` (obrigatório)**. Chave estável de uma conversa que você já conhece. O caminho mais direto. BSUID do contato (identidade opaca do Meta). Resolve por igualdade exata; identificador recomendado daqui em diante. Username público de WhatsApp, com ou sem `@` e sem distinguir maiúsculas. Se vários contatos o compartilham, a API responde `409` (`USERNAME_AMBIGUOUS`). Telefone no formato E.164. Se estiver duplicado entre contatos, a API responde `409` (`PHONE_NUMBER_AMBIGUOUS`) em vez de adivinhar. Chave pública do canal — copie-a do dashboard em **Configurações → Canais** (campo **Chave do canal**), ou liste-as com `GET /channels`. **Obrigatório** em toda requisição: fixa o canal objetivo. Nas vias por contato (`phone`, `username`, `whatsapp_user_id`) restringe a resolução a esse canal; com `uuid` o motor o ignora, mas o contrato o exige mesmo assim. Uma chave que não existe → `404` (`CHANNEL_NOT_FOUND`). Referência completa (ordem de resolução, unificação de conversas e ambiguidades de contato) em [Identificar uma conversa](/pt/conversations). ## Como é executado A API valida a requisição. Se o preflight a rejeitar (ex. o AI não tem tokens), responde um `4xx` síncrono e **nenhuma** ação é executada. Se passar na validação, responde **`202`** imediatamente; o grupo roda em **background**. As ações são executadas uma por uma, na ordem enviada. O `202` confirma que o grupo foi **aceito**, não que cada ação teve sucesso. O resultado por ação **não viaja na resposta** — consulte-o no estado da conversa ou no activity log do negócio. ## Stop on error `stop_on_error` controla o que acontece quando uma ação falha durante a execução: | Valor | Comportamento | | --------------- | -------------------------------------------------------------------- | | `true` (padrão) | A primeira falha **interrompe** as ações seguintes. | | `false` | O grupo executa **todas** as ações, ignorando falhas intermediárias. | ## Escalonamento para pending `escalate_on_error` controla se uma falha do grupo escala a conversa para `inbox_status='pending'` para que um humano a revise: | Valor | Comportamento | | --------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `true` (padrão) | Se uma ação falha com um erro de **entrega, execução AI, escrita em DB ou race de atribuição AI** (`SEND_FAILED`, `PREPARE_FAILED`, `AI_EXECUTION_FAILED`, `ACTIONS_DEPTH_EXCEEDED`, `UPDATE_FAILED`, `NO_AI_EMPLOYEE_ASSIGNED`), a conversa é marcada como `pending` com `pending_reason='action_set_failed'`. Uma única escalada por grupo, mesmo que várias ações falhem. | | `false` | As falhas são reportadas no activity log mas a conversa fica intacta. | Os erros de input do integrador (`*_NOT_FOUND`, `*_AMBIGUOUS`, `WINDOW_CLOSED`, `TEMPLATE_NOT_APPROVED`, etc.), os guards de billing (`WALLET_BLOCKED`, `VISION_WALLET_BLOCKED`) e o guard de integridade do `mark_resolved` (`TRANSCRIPTION_REQUIRED_TO_RESOLVE`) **nunca escalam** — corrija e tente novamente sem intervenção humana. ## Montar uma lista de ações Cada ação é um objeto no array `actions`, identificada por seu `type`. Uma requisição agrupa várias ações sobre a **mesma** conversa, executadas na ordem enviada. O objeto `conversation` sempre inclui `channel`. Exemplo — etiquetar, deixar uma nota e executar o AI, sem interromper ante falhas: ```jsonc Requisição theme={null} { "conversation": { "phone": "+5215512345678", "channel": "ch_7A9K2M4Q" }, "stop_on_error": false, "actions": [ { "type": "assign_label", "tags": [{ "name": "VIP" }] }, { "type": "context_note", "note": "Cliente pediu orçamento." }, { "type": "run_ai", "ai_employee": { "name": "Agente Ventas" } } ] } ``` ```jsonc Resposta 202 theme={null} { "status": "processing", "actions_accepted": 3 } ``` ### Identificar por campos diferentes Mude apenas o identificador dentro de `conversation` (`channel` vai sempre); o resto da requisição não muda: ```jsonc Por telefone theme={null} { "conversation": { "phone": "+5215512345678", "channel": "ch_7A9K2M4Q" }, "actions": [{ "type": "mark_resolved" }] } ``` ```jsonc Por BSUID theme={null} { "conversation": { "whatsapp_user_id": "5f8d0a2b1c9e", "channel": "ch_7A9K2M4Q" }, "actions": [{ "type": "mark_resolved" }] } ``` ```jsonc Por username theme={null} { "conversation": { "username": "@mariana.lopez", "channel": "ch_7A9K2M4Q" }, "actions": [{ "type": "mark_resolved" }] } ``` ```jsonc Por uuid theme={null} { "conversation": { "uuid": "7b8a1c2d-3e4f-5a6b-7c8d-9e0f1a2b3c4d", "channel": "ch_7A9K2M4Q" }, "actions": [{ "type": "mark_resolved" }] } ``` **Passar para um humano** — uma única ação `unassign_ai`, sem campos. É idempotente: se a conversa já não tiver AI, é um no-op bem-sucedido. ```jsonc Requisição theme={null} { "conversation": { "phone": "+5215512345678", "channel": "ch_7A9K2M4Q" }, "actions": [{ "type": "unassign_ai" }] } ``` ```jsonc Resposta 202 theme={null} { "status": "processing", "actions_accepted": 1 } ``` Se o preflight rejeitar o grupo, a resposta é um `4xx` síncrono e nenhuma ação é executada. Ver [Erros](/pt/errors).