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.

// 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"
}

`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.1to1.ai/api/v1/public/{slug}/conversation/actions" \
  -H "Authorization: Bearer sk_1to1_sua_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "conversation": {
      "phone": "+5215512345678",
      "channel": "ch_7A9K2M4Q"
    },
    "actions": [
      {
        "type": "assign_ai_employee",
        "ai_employee": { "name": "Agente Ventas" },
        "run": false,
        "scheduled_message_action": "cancel"
      }
    ]
  }'

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

curl -X POST "https://app.1to1.ai/api/v1/public/{slug}/conversation/actions" \
  -H "Authorization: Bearer sk_1to1_sua_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "conversation": {
      "phone": "+5215512345678",
      "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.1to1.ai/api/v1/public/{slug}/conversation/actions" \
  -H "Authorization: Bearer sk_1to1_sua_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "conversation": {
      "phone": "+5215512345678",
      "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

​assign_ai_employee

​unassign_ai

​Exemplo executável

​Request

​Resposta

`assign_ai_employee`

`unassign_ai`

Exemplo executável

Request

Resposta