Saltar para o conteúdo principal
Endpoint · POST /conversation/actions
Executa um funcionário AI. ai_employee é opcional — sem ele usa o atribuído à conversa. instructions é opcional. Campos
  • ai_employee — objeto { name } do funcionário AI (opcional; sem ele usa o atribuído à conversa).
  • instructions — texto livre (opcional).
Em uma lista, este objeto vai no array actions de um POST /conversation/actions — veja Montar uma lista de ações.
Com a janela de 24h fechada, o funcionário executa mesmo assim e a ação não falha por causa da janela, então não interrompe a lista mesmo que stop_on_error seja true. Se as instruções dele indicam um action set com template, esse template chega ao contato; se não, o texto livre dele não é entregue e a conversa passa para pendente. Um action set que só tem uma resposta rápida falha, sim, com AI_EXECUTION_FAILED, e interrompe a lista. Só falha com WINDOW_CLOSED se a execução com a janela fechada não estiver disponível. O detalhe está em ai_assistance.
Funcionários no novo motor (v2). run_ai executa um funcionário v2 da mesma forma que um clássico, com seus poderes. Se o motor v2 estiver desligado, um run_ai que executaria um v2 —o ai_employee que você indica ou, sem ele, o atribuído— é rejeitado com AI_EMPLOYEE_V2_NOT_SUPPORTED (422). Um atribuído v2 só conta quando um funcionário clássico —o que você indica ou um da sua cadeia— executa o atribuído (run_assigned): aí o grupo é rejeitado com o mesmo 422, porque os action sets de um funcionário clássico não executam um v2. Dois casos falham por ação, depois do 202, sem escalonar: um run_ai sem ai_employee precedido por um assign_ai_employee do grupo, quando o novo atribuído é um v2 e o motor está desligado, e uma ação cujo funcionário clássico executa o atribuído (run_assigned) quando, depois de um assign_ai_employee ou um unassign_ai anterior, o atribuído é um v2 (porque esse assign o atribuiu, ou porque não chegou a mudá-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 run_ai em uma conversa identificada por telefone e canal. Com ai_employee executa um funcionário explícito; sem ele, executa o funcionário AI atribuído à conversa. instructions é opcional.

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.