curl --request POST \
  --url https://app.1to1.ai/api/v1/public/{slug}/conversation/mailbox \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "conversation": {
    "phone": "+525512345678"
  },
  "mailbox": {
    "uuid": "550e8400-e29b-41d4-a716-446655440000"
  }
}
'

{
  "conversation": {
    "uuid": "3c90c3cc-0d44-4b50-8888-8dd25736052a"
  },
  "mailbox": {
    "uuid": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
    "name": "Ventas · Turno matutino"
  }
}

{
  "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."
}

Conversations

Cambiar buzón de conversación

Cambia el buzón al que está asignada la conversación. Dos modos:

mailbox: asigna al buzón específico. Identificación por uuid o por name (único por business case-insensitive con TRIM, vía idx_mailboxes_unique_name_per_business). El mismo name resuelve mailboxes regulares y defaults — no requiere identificar la categoría.
category: delega a load balancing — el servidor elige el buzón con menos chats pendientes dentro de la categoría indicada (uuid o name).

Idempotente por buzón específico: si la conversación ya está en ese buzón, responde 409 MAILBOX_ALREADY_ASSIGNED. Por categoría el load balancer puede reelegir el mismo buzón; no se considera error.

El evento queda registrado en el timeline con autor api_token; el audit fino vive en Activity Log.

POST

{slug}

conversation

mailbox

curl --request POST \
  --url https://app.1to1.ai/api/v1/public/{slug}/conversation/mailbox \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "conversation": {
    "phone": "+525512345678"
  },
  "mailbox": {
    "uuid": "550e8400-e29b-41d4-a716-446655440000"
  }
}
'

{
  "conversation": {
    "uuid": "3c90c3cc-0d44-4b50-8888-8dd25736052a"
  },
  "mailbox": {
    "uuid": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
    "name": "Ventas · Turno matutino"
  }
}

{
  "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

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

mailbox

object

requerido

Option 1
Option 2

Show child attributes

Respuesta

Buzón asignado correctamente.

conversation

object

requerido

Show child attributes

mailbox

object

requerido

Show child attributes

Listar mensajes de una conversación Agregar nota de contexto

Introducción

Conceptos

Guías

Referencia de API

Cambiar buzón de conversación

Autorizaciones

Parámetros de ruta

Cuerpo

Respuesta