> ## Documentation Index
> Fetch the complete documentation index at: https://docs.1to1ai.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Grupo de ações

> Execute até 10 ações sobre uma conversa em uma única requisição.

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.

## As 12 ações

Cada elemento do array `actions` leva um campo `type`. Quase todas espelham um
endpoint individual da API; `send_quick_reply_or_template` é a exceção:
envia a quick reply se a janela de 24h estiver aberta, ou o
[template](/pt/templates) se estiver fechada — o modo é decidido pelo servidor em
tempo de execução.

<AccordionGroup>
  <Accordion title="Mensagens" icon="paper-plane">
    * `send_message` — envia uma mensagem (texto, mídia, quick reply ou template).
    * `send_quick_reply_or_template` — quick reply ou template, conforme a janela.
  </Accordion>

  <Accordion title="Etiquetas" icon="tag">
    * `assign_label` — atribui uma etiqueta à conversa.
    * `remove_label` — remove uma etiqueta da conversa.
  </Accordion>

  <Accordion title="Caixa e notas" icon="inbox">
    * `assign_mailbox` — move a conversa para uma caixa de entrada.
    * `context_note` — deixa uma nota interna.
    * `mark_resolved` — marca a conversa como resolvida.
    * `mark_pending` — marca a conversa como pendente.
  </Accordion>

  <Accordion title="AI" icon="robot">
    * `run_ai` — executa o funcionário AI sobre a conversa.
    * `ai_assistance` — gera uma resposta sugerida com o AI.
    * `assign_ai_employee` — atribui um funcionário AI à conversa.
    * `unassign_ai` — remove o funcionário AI (passa a conversa para um humano). Sem campos; idempotente (no-op se a conversa já não tiver AI).
  </Accordion>
</AccordionGroup>

<Note>
  Um grupo admite até **10 ações**, das quais no máximo **3** podem
  disparar o AI. Excedê-lo falha com `BATCH_LIMIT_EXCEEDED`.
</Note>

## Como é executado

<Steps>
  <Step title="Validação síncrona">
    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.
  </Step>

  <Step title="202 Accepted">
    Se passar na validação, responde **`202`** imediatamente; o grupo roda em
    **background**.
  </Step>

  <Step title="Execução em ordem">
    As ações são executadas uma por uma, na ordem enviada.
  </Step>
</Steps>

<Warning>
  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.
</Warning>

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

## Escalada para pending

`escalate_on_error` controla se uma falha do grupo escala a conversa para `inbox_status='pending'` para revisão humana:

| 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 o estado da conversa fica intacto.                                                                                                                                                                                                                                                                                              |

<Note>
  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.
</Note>

## Exemplo

Etiquetar, deixar uma nota e executar o AI, sem interromper ante falhas:

<CodeGroup>
  ```jsonc Request theme={null}
  {
    "conversation": { "phone": "+5215512345678" },
    "stop_on_error": false,
    "actions": [
      { "type": "assign_label", "tags": [{ "name": "VIP" }] },
      { "type": "context_note", "note": "Cliente pediu uma cotação." },
      { "type": "run_ai", "ai_employee": { "name": "Agente de Vendas" } }
    ]
  }
  ```

  ```jsonc Resposta 202 theme={null}
  {
    "conversation": { "uuid": "..." },
    "status": "processing",
    "actions_accepted": 3
  }
  ```
</CodeGroup>

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

<CodeGroup>
  ```jsonc Request theme={null}
  {
    "conversation": { "phone": "+5215512345678" },
    "actions": [{ "type": "unassign_ai" }]
  }
  ```

  ```jsonc Resposta 202 theme={null}
  {
    "conversation": { "uuid": "..." },
    "status": "processing",
    "actions_accepted": 1
  }
  ```
</CodeGroup>

<Note>
  Só precisa passar para um humano e quer o resultado na hora? O endpoint síncrono
  `POST /conversation/unassign-ai`
  faz exatamente isto e responde `200` com o resultado real
  (`{ "ai_employee": null, "schedule_action": "cancelled" | "none" }`), sem o
  modelo assíncrono do grupo.
</Note>

<Tip>
  Se o preflight rejeitar o grupo, a resposta é um `4xx` síncrono e nenhuma
  ação é executada. Ver [Erros](/pt/errors).
</Tip>