Visão geral

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). Se você passar um template junto a um primário (texto/mídia ou resposta rápida), o servidor decide pela janela de 24h: envia o primário se estiver aberta, ou o template se estiver fechada.

Ação	O que faz	Dispara AI?
`send_message`	Envia uma mensagem: texto, mídia, resposta rápida ou template	Não
`assign_label`	Atribui uma ou várias etiquetas	Não
`remove_label`	Remove uma ou várias etiquetas	Não
`assign_mailbox`	Move a conversa para uma caixa de entrada ou categoria	Não
`context_note`	Deixa uma nota de contexto	Não
`mark_resolved`	Marca a conversa como resolvida	Não
`mark_pending`	Marca a conversa como pendente	Não
`run_ai`	Executa o funcionário AI atribuído (ou um explícito)	Sim
`ai_assistance`	Consulta outro funcionário AI para uma resposta sugerida	Sim
`assign_ai_employee`	Atribui um funcionário AI (com `run: true`, também executa)	Só com `run: true`
`unassign_ai`	Remove o funcionário AI (passa para humano)	Não
`cancel_schedule`	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.

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

string

Chave estável de uma conversa que você já conhece. O caminho mais direto.

string

BSUID do contato (identidade opaca do Meta). Resolve por igualdade exata; identificador recomendado daqui em diante.

string

Username público de WhatsApp, com ou sem @ e sem distinguir maiúsculas. Se dois contatos distintos o compartilham no mesmo canal, a API responde 409 (USERNAME_AMBIGUOUS); o mesmo username em canais distintos não é ambíguo: channel o resolve.

string

Telefone no formato E.164. Se estiver duplicado entre dois contatos distintos do mesmo canal, a API responde 409 (PHONE_NUMBER_AMBIGUOUS) em vez de adivinhar; o mesmo número em canais distintos não é ambíguo: channel o resolve.

string

obrigatório

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.

Como é executado

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.

202 Accepted

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

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:

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`), ou se um marcador de pagamento não pôde ser resolvido por um motivo alheio ao seu payload — a conversa não tem esse dado de pagamento, ou a leitura ou a geração do perfil falhou (`PAYMENT_MARKER_DATA_UNAVAILABLE`, `PAYMENT_PROFILE_GENERATION_FAILED`), 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 marcadores de pagamento mal usados (PAYMENT_MARKER_UNKNOWN, PAYMENT_MARKER_UNSUPPORTED_FIELD, TEMPLATE_BODY_TOO_LONG — a correção está no texto que você enviou, não na conversa), 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:

{
  "conversation": {
    "phone": "+525512345678",
    "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" } }
  ]
}

{
  "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:

{
  "conversation": {
    "phone": "+525512345678",
    "channel": "ch_7A9K2M4Q"
  },
  "actions": [{ "type": "mark_resolved" }]
}

{
  "conversation": {
    "whatsapp_user_id": "5f8d0a2b1c9e",
    "channel": "ch_7A9K2M4Q"
  },
  "actions": [{ "type": "mark_resolved" }]
}

{
  "conversation": {
    "username": "@mariana.lopez",
    "channel": "ch_7A9K2M4Q"
  },
  "actions": [{ "type": "mark_resolved" }]
}

{
  "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.

{
  "conversation": {
    "phone": "+525512345678",
    "channel": "ch_7A9K2M4Q"
  },
  "actions": [{ "type": "unassign_ai" }]
}

{
  "status": "processing",
  "actions_accepted": 1
}

Se o preflight rejeitar o grupo, a resposta é um 4xx síncrono e nenhuma ação é executada. Ver Erros.

Introdução

Conceitos

Guias

Ações

Identificar a conversa

Como é executado

Stop on error

Escalonamento para pending

Montar uma lista de ações

Identificar por campos diferentes

​Identificar a conversa

​Como é executado

​Stop on error

​Escalonamento para pending

​Montar uma lista de ações

​Identificar por campos diferentes

Identificar a conversa

Como é executado

Stop on error

Escalonamento para pending

Montar uma lista de ações

Identificar por campos diferentes