Atribuir e desatribuir funcionário AI

Endpoint · POST /conversation/actions

Duas ações gerenciam qual funcionário AI atende a conversa: assign_ai_employee o atribui (opcionalmente o executa) e unassign_ai o remove (a conversa passa para um humano).

`assign_ai_employee`

Atribui um funcionário AI à conversa. Com run: true, além disso o executa de imediato (só então conta como ação que dispara AI). Campos

ai_employee — { name } do funcionário AI (obrigatório).
run — booleano (opcional, padrão false). Com true executa o funcionário de imediato após atribuí-lo.
instructions — texto opcional com instruções pontuais para essa execução. Só se aplica com run: true.
scheduled_message_action — reassign | cancel. O que fazer com a mensagem agendada ativa da conversa. Envie cancel por padrão (veja o aviso).

Agendamento ativo ao reatribuir. Se a conversa é atendida por um funcionário AI que deixou uma mensagem agendada pendente e você a reatribui para outro funcionário AI, a API exige que você decida o que acontece com esse agendamento: sem scheduled_message_action a ação falha com SCHEDULED_MESSAGE_ACTION_REQUIRED.

cancel — cancela a mensagem agendada; o novo funcionário AI começa sem ela.
reassign — mantém o agendamento e o reaponta para o novo funcionário AI.

Como a API não expõe se uma conversa tem um agendamento ativo, o mais robusto é enviar sempre "scheduled_message_action": "cancel": é válido em qualquer atribuição e não faz nada quando não há agendamento para cancelar. Use reassign apenas quando reatribui de um funcionário AI para outro e quer manter o agendamento — enviá-lo em qualquer outro caso falha com SCHEDULED_MESSAGE_ACTION_INVALID.

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

// Atribuir — `cancel` é o valor seguro para qualquer atribuição
{
  "type": "assign_ai_employee",
  "ai_employee": { "name": "Agente Ventas" },
  "run": false,
  "scheduled_message_action": "cancel"
}

// Reatribuir de um funcionário AI para OUTRO mantendo sua mensagem agendada
{
  "type": "assign_ai_employee",
  "ai_employee": { "name": "Agente Soporte" },
  "scheduled_message_action": "reassign"
}

// Atribuir e executar de imediato
{
  "type": "assign_ai_employee",
  "ai_employee": { "name": "Agente Ventas" },
  "run": true,
  "instructions": "Cumprimente e confirme o horário de entrega.",
  "scheduled_message_action": "cancel"
}

Com run: true e 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). Um funcionário v2 é atribuído da mesma forma que um clássico, e com scheduled_message_action: reassign a mensagem programada da conversa passa para ele. Com run, ele é executado: se o motor v2 estiver desligado, ou se um funcionário clássico da sua cadeia o executar como atribuído (run_assigned), o grupo é rejeitado com AI_EMPLOYEE_V2_NOT_SUPPORTED (422) e nada é reatribuído. Sem run é sempre atribuído. Se o motor v2 estiver desligado, a conversa passa a pendente quando o cliente escrever, e se a mensagem programada que você passou com reassign disparar com o motor desligado, ela é cancelada sem chegar ao cliente e a conversa passa a pendente nesse momento. Veja Como é executado.

`unassign_ai`

Remove o funcionário AI (a conversa passa para um humano). Sem campos; idempotente (no-op bem-sucedido se a conversa já não tiver AI). Cancela a mensagem agendada ativa do AI, se houver.

{
  "type": "unassign_ai"
}

Em uma lista, estes objetos vão no array actions de um POST /conversation/actions — veja Montar uma lista de ações.

Exemplo executável

Duas ações gerenciam o funcionário AI de uma conversa identificada por telefone e canal: assign_ai_employee o atribui (com run: true também o executa) e unassign_ai o remove. Envie scheduled_message_action: cancel por padrão; use reassign apenas ao reatribuir de um funcionário AI para outro mantendo sua mensagem agendada.

Request

curl -X POST "https://app.1to1ai.com/api/v1/public/{slug}/conversation/actions" \
  -H "Authorization: Bearer sk_1to1_sua_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "conversation": {
      "phone": "+525512345678",
      "channel": "ch_7A9K2M4Q"
    },
    "actions": [
      {
        "type": "assign_ai_employee",
        "ai_employee": { "name": "Agente Ventas" },
        "run": false,
        "scheduled_message_action": "cancel"
      }
    ]
  }'

curl -X POST "https://app.1to1ai.com/api/v1/public/{slug}/conversation/actions" \
  -H "Authorization: Bearer sk_1to1_sua_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "conversation": {
      "phone": "+525512345678",
      "channel": "ch_7A9K2M4Q"
    },
    "actions": [
      {
        "type": "assign_ai_employee",
        "ai_employee": { "name": "Agente Soporte" },
        "scheduled_message_action": "reassign"
      }
    ]
  }'

curl -X POST "https://app.1to1ai.com/api/v1/public/{slug}/conversation/actions" \
  -H "Authorization: Bearer sk_1to1_sua_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "conversation": {
      "phone": "+525512345678",
      "channel": "ch_7A9K2M4Q"
    },
    "actions": [
      {
        "type": "assign_ai_employee",
        "ai_employee": { "name": "Agente Ventas" },
        "run": true,
        "instructions": "Cumprimente e confirme o horário de entrega.",
        "scheduled_message_action": "cancel"
      }
    ]
  }'

curl -X POST "https://app.1to1ai.com/api/v1/public/{slug}/conversation/actions" \
  -H "Authorization: Bearer sk_1to1_sua_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "conversation": {
      "phone": "+525512345678",
      "channel": "ch_7A9K2M4Q"
    },
    "actions": [
      {
        "type": "unassign_ai"
      }
    ]
  }'

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

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

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.

Introdução

Conceitos

Guias

Ações

Atribuir e desatribuir funcionário AI

`assign_ai_employee`

`unassign_ai`

Exemplo executável

Request

Resposta