Asignar y desasignar empleado AI

Endpoint · POST /conversation/actions

Dos acciones gestionan qué empleado AI atiende la conversación: assign_ai_employee lo asigna (opcionalmente lo ejecuta) y unassign_ai lo retira (la conversación pasa a un humano).

`assign_ai_employee`

Asigna un empleado AI a la conversación. Con run: true, además lo ejecuta de inmediato (solo entonces cuenta como acción que dispara AI). Campos

ai_employee — { name } del empleado AI (obligatorio).
run — booleano (opcional, default false). Con true ejecuta el empleado de inmediato tras asignarlo.
instructions — texto opcional con instrucciones puntuales para esa ejecución. Solo aplica con run: true.
scheduled_message_action — reassign | cancel. Qué hacer con el mensaje programado activo de la conversación. Manda cancel por defecto (ver el aviso).

Programación activa al reasignar. Si la conversación la atiende un empleado AI que dejó un mensaje programado pendiente y la reasignas a otro empleado AI, la API exige que decidas qué pasa con esa programación: sin scheduled_message_action la acción falla con SCHEDULED_MESSAGE_ACTION_REQUIRED.

cancel — cancela el mensaje programado; el empleado AI nuevo empieza sin él.
reassign — conserva la programación y la reapunta al empleado AI nuevo.

Como la API no expone si una conversación tiene una programación activa, lo más robusto es mandar siempre "scheduled_message_action": "cancel": es válido en cualquier asignación y no hace nada si no hay programación que cancelar. Usa reassign solo cuando reasignas de un empleado AI a otro y quieres conservar la programación — enviarlo en cualquier otro caso falla con SCHEDULED_MESSAGE_ACTION_INVALID.

// Asignar — `cancel` es el valor seguro para cualquier asignación
{
  "type": "assign_ai_employee",
  "ai_employee": { "name": "Agente Ventas" },
  "run": false,
  "scheduled_message_action": "cancel"
}

// Reasignar de un empleado AI a OTRO conservando su mensaje programado
{
  "type": "assign_ai_employee",
  "ai_employee": { "name": "Agente Soporte" },
  "scheduled_message_action": "reassign"
}

// Asignar y ejecutar de inmediato
{
  "type": "assign_ai_employee",
  "ai_employee": { "name": "Agente Ventas" },
  "run": true,
  "instructions": "Saluda y confirma el horario de entrega.",
  "scheduled_message_action": "cancel"
}

`unassign_ai`

Retira el empleado AI (la conversación pasa a un humano). Sin campos; idempotente (no-op exitoso si la conversación ya no tiene AI). Cancela el mensaje programado activo del AI, si lo hay.

{
  "type": "unassign_ai"
}

En una lista, estos objetos van en el array actions de un POST /conversation/actions — ver Armar una lista de acciones.

Ejemplo ejecutable

Dos acciones gestionan el empleado AI de una conversación identificada por teléfono y canal: assign_ai_employee lo asigna (con run: true además lo ejecuta) y unassign_ai lo retira. Manda scheduled_message_action: cancel por defecto; usa reassign solo al reasignar de un empleado AI a otro conservando su mensaje programado.

Request

curl -X POST "https://app.1to1.ai/api/v1/public/{slug}/conversation/actions" \
  -H "Authorization: Bearer sk_1to1_tu_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_tu_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_tu_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": "Saluda y confirma el horario de entrega.",
        "scheduled_message_action": "cancel"
      }
    ]
  }'

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

Respuesta

202 Accepted — el grupo se aceptó y corre en background. El resultado real por acción no viaja en la respuesta (se consulta después — ver Cómo se ejecuta).

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

string

Siempre processing: confirma que el grupo fue aceptado y está en ejecución.

integer

Cuántas acciones del array se admitieron para ejecución — no cuántas tuvieron éxito.

Introducción

Conceptos

Guías

Acciones

Asignar y desasignar empleado AI

`assign_ai_employee`

`unassign_ai`

Ejemplo ejecutable

Request

Respuesta

​assign_ai_employee

​unassign_ai

​Ejemplo ejecutable

​Request

​Respuesta

`assign_ai_employee`

`unassign_ai`

Ejemplo ejecutable

Request

Respuesta