Saltar para o conteúdo principal
Endpoint · POST /conversation/actions
ai_assistance executa o funcionário AI que você escolher sobre a conversa sem atribuí-lo. É uma execução pontual: o funcionário roda de forma transitória e gera sua assistência (contexto/sugestão) sobre a conversa, mas não se torna o funcionário atribuído — a conversa continua com quem a atende (outro funcionário AI ou um humano) e a atribuição não muda. Como se diferencia das outras ações de AI:
  • run_ai executa o funcionário atribuído —o que atende— e assume o turno.
  • assign_ai_employee muda qual funcionário atende a conversa.
  • ai_assistance executa outro funcionário sem atribuí-lo — sua saída não muda quem atende.
Campos
  • ai_employee — { name } do funcionário AI a consultar (obrigatório).
  • instructions — texto opcional com a consulta ou o foco para o funcionário (por exemplo, “Este cliente se qualifica para o plano empresarial?”).
Consome tokens do modelo do funcionário consultado e conta como ação que dispara AI (máximo 3 por grupo, contando também os send_json). Em uma lista, este objeto vai no array actions de um POST /conversation/actions — veja Montar uma lista de ações.
Esta ação não verifica a janela de 24h, e o funcionário pode responder ao cliente.Com a janela fechada a execução acontece mesmo assim e consome tokens:
  • Se as instruções do funcionário indicam um action set com template e ele o executa, esse template chega ao contato.
  • O texto livre que ele enviar é rejeitado pela Meta: fica marcado como falha no chat e a conversa escala para pendente. Não chega como WINDOW_CLOSED da ação — o resultado por ação sai verde, porque o turno rodou bem; o que falhou foi a entrega.
  • Um action set que só tem uma resposta rápida falha: a ação sai com AI_EXECUTION_FAILED, interrompe a lista com stop_on_error e deixa a conversa em pendente.
run_ai, assign_ai_employee com run e /conversation/smart-actions também executam com a janela fechada, mas respondem WINDOW_CLOSED sem executar o funcionário se a execução com a janela fechada não estiver disponível. Esta ação nunca faz isso.Se você não quiser gastar o turno, consulte POST /conversation/status e, se window.status for closed, envie primeiro um template. Quando o cliente responder, a janela volta a abrir.
Funcionários no novo motor (v2). A assistência executa um funcionário v2 da mesma forma que um clássico. Se o motor v2 estiver desligado e ai_employee for v2, o grupo é rejeitado com AI_EMPLOYEE_V2_NOT_SUPPORTED (422). Uma conversa com um v2 atribuído não impede a assistência: só conta quando um funcionário clássico executa o atribuído (run_assigned). Nesse caso o grupo é rejeitado com o mesmo 422, a menos que um assign_ai_employee ou um unassign_ai anterior do grupo possa mudar o atribuído: então a ação falha por ação, depois do 202 e sem escalonar, se o atribuído for v2 nesse momento (também quando esse assign acabou de atribuí-lo). Veja Como é executado.
A execução pode deixar uma mensagem agendada. Se as instruções do funcionário ou a conversa o levarem a se autoprogramar, a conversa pode ficar com um agendamento de IA ativo. Em uma lista de ações isso afeta as que vêm depois: em um assign_ai_employee posterior envie sempre scheduled_message_action (caso contrário pode falhar com SCHEDULED_MESSAGE_ACTION_REQUIRED), e um cancelamento ou unassign_ai posterior cancela o acompanhamento que o funcionário acabou de prometer ao cliente. 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.

Exemplo executável

Um ai_assistance em uma conversa identificada por telefone e canal: executa de forma pontual o funcionário AI escolhido, sem mudar a atribuição da conversa.

Request

Resposta

202 Accepted — o grupo foi aceito e roda em background. O resultado por ação não viaja na resposta (consulte-o depois — veja Como é executado).
string
Sempre processing: confirma que o grupo foi aceito e está em execução.
integer
Quantas ações do array foram admitidas para execução — não quantas tiveram sucesso.