curl --request POST \
  --url https://app.1to1.ai/api/v1/public/{slug}/conversation/scheduled-message \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "executor_kind": "ai_employee",
  "conversation": {
    "phone": "+52 55 1234 5678"
  },
  "schedule_at": {
    "date": "2026-06-15",
    "time": "14:30"
  },
  "reason": "Seguimiento del cliente tras la propuesta"
}
'

{
  "data": {
    "uuid": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
    "schedule_at": "2023-11-07T05:31:56Z",
    "status": "pending"
  }
}

{
  "code": "INVALID_API_TOKEN",
  "message": "The provided API token is invalid or has been revoked. Generate a new one in Settings → API Token."
}

{
  "code": "INVALID_API_TOKEN",
  "message": "The provided API token is invalid or has been revoked. Generate a new one in Settings → API Token."
}

{
  "code": "INVALID_API_TOKEN",
  "message": "The provided API token is invalid or has been revoked. Generate a new one in Settings → API Token."
}

{
  "code": "INVALID_API_TOKEN",
  "message": "The provided API token is invalid or has been revoked. Generate a new one in Settings → API Token."
}

{
  "code": "INVALID_API_TOKEN",
  "message": "The provided API token is invalid or has been revoked. Generate a new one in Settings → API Token."
}

{
  "code": "INVALID_API_TOKEN",
  "message": "The provided API token is invalid or has been revoked. Generate a new one in Settings → API Token."
}

{
  "code": "INVALID_API_TOKEN",
  "message": "The provided API token is invalid or has been revoked. Generate a new one in Settings → API Token."
}

{
  "code": "INVALID_API_TOKEN",
  "message": "The provided API token is invalid or has been revoked. Generate a new one in Settings → API Token."
}

Schedules

Programar mensaje en una conversación

Programa un mensaje (AI o humano) en una conversación.

Ramas:

executor_kind: 'ai_employee' — al firing, el AI procesará la conversación con el LLM y enviará la respuesta. El fallback template es opcional (si la ventana 24h está cerrada al firing, el firing usa el default del canal o el que pasaste).
executor_kind: 'human_user' — al firing, el sistema envía el payload literal que armaste (texto/media/QR/template). El template_uuid es obligatorio porque la ventana 24h puede cerrar antes del firing y la API pública no puede asumir un default.

Replace: si la conversación ya tiene un schedule pending, este POST lo cancela y crea uno nuevo (atómico). Solo se permite 1 pending por conversación.

Archivos: para media (mensaje principal o header de template), envía file_uuid de un archivo previamente subido vía /files/request-upload + /files/confirm con module=api_messages. El servidor genera signed URLs y las re-firma al disparar.

Audit: la API key queda persistida en scheduled_messages.api_key_id. El author_snapshot reporta type='api_token' con el UUID público del token.

POST

{slug}

conversation

scheduled-message

curl --request POST \
  --url https://app.1to1.ai/api/v1/public/{slug}/conversation/scheduled-message \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "executor_kind": "ai_employee",
  "conversation": {
    "phone": "+52 55 1234 5678"
  },
  "schedule_at": {
    "date": "2026-06-15",
    "time": "14:30"
  },
  "reason": "Seguimiento del cliente tras la propuesta"
}
'

{
  "data": {
    "uuid": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
    "schedule_at": "2023-11-07T05:31:56Z",
    "status": "pending"
  }
}

{
  "code": "INVALID_API_TOKEN",
  "message": "The provided API token is invalid or has been revoked. Generate a new one in Settings → API Token."
}

{
  "code": "INVALID_API_TOKEN",
  "message": "The provided API token is invalid or has been revoked. Generate a new one in Settings → API Token."
}

{
  "code": "INVALID_API_TOKEN",
  "message": "The provided API token is invalid or has been revoked. Generate a new one in Settings → API Token."
}

{
  "code": "INVALID_API_TOKEN",
  "message": "The provided API token is invalid or has been revoked. Generate a new one in Settings → API Token."
}

{
  "code": "INVALID_API_TOKEN",
  "message": "The provided API token is invalid or has been revoked. Generate a new one in Settings → API Token."
}

{
  "code": "INVALID_API_TOKEN",
  "message": "The provided API token is invalid or has been revoked. Generate a new one in Settings → API Token."
}

{
  "code": "INVALID_API_TOKEN",
  "message": "The provided API token is invalid or has been revoked. Generate a new one in Settings → API Token."
}

{
  "code": "INVALID_API_TOKEN",
  "message": "The provided API token is invalid or has been revoked. Generate a new one in Settings → API Token."
}

Autorizaciones

Authorization

string

header

requerido

API token emitido desde Settings → API Token del dashboard 1TO1 AI. Enviar en header Authorization: Bearer sk_1to1_...

Parámetros de ruta

slug

string

requerido

Slug del business, case-insensitive. Debe coincidir con el business del token.

Ejemplo:

"acme"

Cuerpo

application/json

Option 1
Option 2

executor_kind

enum<string>

requerido

Opciones disponibles:

ai_employee

conversation

object

requerido

Identificador de la conversación — exactamente UNO de los cuatro campos debe venir. Orden de resolución: uuid > whatsapp_user_id > username > phone. El lookup filtra por el business del token (defense in depth cross-tenant). Resolver por phone o username puede devolver 409 (PHONE_NUMBER_AMBIGUOUS / USERNAME_AMBIGUOUS) cuando varios contactos comparten el identificador — aplica a cualquier endpoint que acepte esta referencia.

Show child attributes

schedule_at

object

requerido

Fecha + hora interpretadas en la zona horaria del negocio (businesses.timezone, configurada al onboarding — típicamente America/Mexico_City). El servidor combina ambos campos contra esa zona para construir el instante UTC. La response normaliza a ISO Z (UTC).

Show child attributes

reason

string

requerido

Motivo del programado. Se inyecta como context_note en la conversación al firing.

Required string length: 1 - 500

scheduled_uuid

string<uuid>

UUID pre-generado client-side (opcional). Reservado para uso futuro — el flow de pre-subir archivos referenciando el UUID antes del POST todavía no está disponible en API pública (sí en dashboard). Si lo omites, el servidor genera el UUID automáticamente; si lo envías, se respeta vía COALESCE en el RPC.

ai_employee_uuid

string<uuid> | null

UUID del AI employee. Si null/omitido, usa el AI asignado a la conversación. Si la conv no tiene AI asignado y no lo pasas, falla con NO_AI_EMPLOYEE_ASSIGNED.

template_uuid

string<uuid> | null

Template fallback. Si omitido, el firing usa el default scheduled template del canal (auto-creado al configurar WhatsApp).

Respuesta

Schedule creado.

data

object

requerido

Show child attributes

Leer schedule pending de una conversación Cancelar schedule pending

Introducción

Conceptos

Guías

Referencia de API

Programar mensaje en una conversación

Autorizaciones

Parámetros de ruta

Cuerpo

Respuesta