Execute um funcionário de IA a partir de uma instrução escrita com suas palavras
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:
{ "conversation": { "uuid": "9f3c1a4e-…", "channel": "ch_7A9K2M4Q" }, "ai_employee": { "name": "Agente de Vendas" }, "instructions": "Verifique se o orçamento ficou pendente; se sim, envie-o e marque o acompanhamento."}
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 os action sets que ele tem atribuídos, 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, 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.
Antes de integrar, peça ao negócio a lista de action sets 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.
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.
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}.
Verifique se o cliente perguntou sobre a entrega e ainda não respondemos.Se sim, responda com as informações de entrega e etiquete como "Acompanhamento".
Faça o que for necessário.
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.
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.
Se a janela de 24h estiver fechada, este endpoint responde
422 WINDOW_CLOSED e não executa o funcionário: nenhum token gasto, nenhuma mensagem enviada,
nenhuma mudança na conversa. O corte é síncrono e prévio, mas a chamada aconteceu: consome uma
requisição do seu rate limit e fica no Registro de Atividade do painel como uma
tentativa rejeitada, com seu código.Isso inclui os action sets cujo envio tem um template configurado, que com a janela fechada
sairiam por conta própria: no preflight não dá para saber o que o funcionário vai decidir, então o
guard bloqueia esses também. O Smart Actions não serve para reabrir uma janela fechada.É deliberado. O mais comum que este endpoint faz é enviar uma mensagem ao cliente, e com a janela
fechada a Meta rejeita. Sem essa verificação você receberia um 202, a mensagem ficaria marcada
como falha no chat e a conversa escalaria para pendente — tudo sem nenhum sinal chegar até você.Para reabrir uma janela fechada, envie primeiro um template com
/conversation/actions. Quando o cliente responder, a janela abre de
novo e o Smart Actions fica disponível.Para saber de antemão, consulte POST /conversation/status: devolve window.status (open ou
closed) e window.expires_at.
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.
