Saltar para o conteúdo principal
Endpoint · POST /conversation/smart-actions
Descreva o que você quer que aconteça com suas palavras e deixe o funcionário de IA decidir como. Em vez de montar um array de ações tipadas, você envia uma conversa, um funcionário e uma instrução:
O funcionário lê o histórico da conversa, interpreta sua instrução e executa os action sets que ele tem atribuídos.

Quando usar este endpoint e quando usar o grupo de ações

Use /conversation/actions

Quando você já sabe exatamente o que deve acontecer. É mais barato, mais rápido e mais previsível: executa as ações que você nomeia, na ordem em que as nomeia.

Use Smart Actions

Quando você quer descrever a intenção e deixar o funcionário avaliar o caso — sobretudo se a decisão depender do que diz o histórico da conversa.
A instrução é obrigatória e admite até 4000 caracteres: espaço para regras de negócio de verdade, não para um comando.

O mais importante: a instrução direciona, não amplia

O funcionário executa o que ele tem configurado —os action sets de um funcionário clássico, os poderes de um funcionário v2—, e nada mais. Sua instrução escolhe entre o que ele já sabe fazer; não lhe acrescenta capacidades.Se você pedir algo para o qual não existe um action set ou um poder, a execução responde e não executa nada, sem devolver erro. Você não verá um 4xx: verá uma conversa onde não aconteceu o que você esperava.
A execução pode deixar uma mensagem agendada. Se a sua instrução ou as do funcionário o levarem a se autoprogramar, a conversa pode ficar com um agendamento de IA ativo. Se depois você atribuir outro funcionário a essa conversa pelo grupo de ações, envie sempre scheduled_message_action no assign_ai_employee. A execução também pode cancelar o agendamento pendente. Se cancelar um que a sua equipe programou, a conversa passa para pendente para que uma pessoa o reagende; também passa para pendente se o funcionário decidir programar em uma conversa sem IA atribuída e escreveu ao cliente nessa execução. Essa capacidade está sendo habilitada de forma gradual. Um funcionário v2 (motor novo) não decide agendar nem cancelar nesta execução, mas seus poderes podem mudar o agendamento ativo: passar para humano o cancela se um funcionário de IA atendia a conversa, e atribuir a outro funcionário o cancela ou, se um funcionário de IA já atendia a conversa e o negócio configurou assim, o transfere.
Antes de integrar, peça ao negócio a lista de action sets ou poderes que o funcionário tem atribuídos — o que ele sabe fazer vem dali e do prompt dele, não da sua instrução. Se você precisa que algo concreto aconteça de forma garantida — aplicar uma etiqueta, mover de caixa, mudar o status — use /conversation/actions, que executa exatamente o que você pede.

Somente funcionários operative

Um funcionário json devolve AI_EMPLOYEE_NOT_FOUND (404). Descubra os disponíveis com GET /ai-employees, que informa o type de cada um. Para executar um funcionário json, use /conversation/actions com a ação run_ai ou ai_assistance.

Como escrever a instrução

O funcionário não consegue adivinhar os nomes das suas etiquetas, caixas ou modelos: nomeie-os explicitamente. Descubra-os com GET /tags, GET /mailbox-categories, GET /quick-replies e GET /templates/{name}/{language}.
O limite de 4000 é medido em unidades UTF-16. Se você cortar o texto para respeitá-lo, não o corte no meio de um emoji: um caractere partido devolve 400 INVALID_REQUEST.

A resposta

O 202 confirma aceitação, não resultado. Uma execução com raciocínio pode levar minutos, por isso roda em segundo plano.O detalhe do que aconteceu ainda não é notificado — chegará por webhook (funcionalidade futura), assim como em /conversation/actions. Enquanto isso, o que foi executado aparece no Registro de Atividade do painel do negócio.

Com a janela de 24h fechada, o funcionário executa mesmo assim

Se a janela de 24h estiver fechada, o funcionário executa mesmo assim e decide o que enviar, e a resposta é o mesmo 202. Com a janela fechada o WhatsApp só entrega templates:
  • Se as instruções dele indicam um action set com template e ele o executa, esse template chega ao contato.
  • Se ele responde com texto livre, a mensagem não é entregue: fica marcada como falha no chat e a conversa passa para pendente para que uma pessoa a atenda. O 202 não avisa você.
  • Se ele executa um action set que só tem uma resposta rápida, a execução falha: nada é enviado e a conversa passa para pendente.
  • Se ele decide não enviar nada, nenhuma mensagem sai.
Em todos os casos o turno consome tokens.Se a execução com a janela fechada não estiver disponível, o endpoint responde 422 WINDOW_CLOSED e não executa o funcionário: nenhum token gasto, nenhuma mensagem enviada, nenhuma mudança na conversa. A chamada consome uma requisição do seu rate limit e fica no Registro de Atividade do painel como uma tentativa rejeitada, com seu código.Se você não quiser gastar o turno, consulte POST /conversation/status e, se window.status for closed, envie um template com /conversation/actions. Quando o cliente responder, a janela volta a abrir.

Uma chamada duplicada é executada duas vezes

Este endpoint não deduplica. Não aceita Idempotency-Key, e o 202 não é promessa de execução única.
  • Mantenha uma única requisição em andamento por conversa.
  • Não repita às cegas um 5xx deste endpoint, ao contrário do que sugere a tabela geral de erros: a nova tentativa executa de novo e pode enviar outra mensagem ao cliente.
  • A execução pode se sobrepor à resposta automática disparada por uma mensagem recebida do cliente.

Erros

O catálogo completo está em erros.