Saltar para o conteúdo principal
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 se estiver fechada — o modo é decidido pelo servidor em tempo de execução.
  • send_message — envia uma mensagem (texto, mídia, quick reply ou template).
  • send_quick_reply_or_template — quick reply ou template, conforme a janela.
  • assign_label — atribui uma etiqueta à conversa.
  • remove_label — remove uma etiqueta da conversa.
  • 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.
  • 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).
Um grupo admite até 10 ações, das quais no máximo 3 podem disparar o AI. Excedê-lo falha com BATCH_LIMIT_EXCEEDED.

​
Como é executado

1

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

202 Accepted

Se passar na validação, responde 202 imediatamente; o grupo roda em background.
3

Execução em ordem

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:

​
Escalada para pending

escalate_on_error controla se uma falha do grupo escala a conversa para inbox_status='pending' para revisão humana:
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.

​
Exemplo

Etiquetar, deixar uma nota e executar o AI, sem interromper ante falhas:
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.
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.
Se o preflight rejeitar o grupo, a resposta é um 4xx síncrono e nenhuma ação é executada. Ver Erros.