Saltar al contenido
API de TotemDocumentación
ENEnglishESEspañol
Crear clave API
Beta

Referencia Conversaciones

Crear clave API

Conversaciones

Lista y obtén las conversaciones de un equipo en todos los canales, con su estado, la persona asignada, si una persona ha tomado el control y cuándo llegaron y salieron los últimos mensajes. Nunca el contenido de los mensajes.

Resumen

Una conversación es un hilo con un lead en un canal y una cuenta de empresa: WhatsApp, correo electrónico, el chat web (chatbot), Facebook, Instagram, SMS o TikTok. Un lead puede tener varias conversaciones en el mismo canal y cuenta de empresa, una por cada dirección de contacto (teléfono, correo electrónico o usuario) que haya usado, así que usa el id de la conversación como clave de tu copia. Recibes los metadatos de la conversación, nunca sus mensajes:

  • channel_type: el canal, o null para un canal que esta versión de la API no conoce.
  • status: active o archived en la bandeja de entrada del equipo.
  • assignee: el miembro del equipo al que está asignada la conversación, o null.
  • reply_mode: human mientras una persona ha tomado el control de la conversación, incluido un chat de WhatsApp que se atiende desde la app WhatsApp Business, y ai en los demás casos. ai significa que no hay una toma de control activa; no significa que haya un asistente configurado o respondiendo en ese canal. Una toma de control con límite de tiempo vuelve a ai cuando termina, y en ese momento la conversación recibe una versión nueva.
  • last_inbound_at y last_outbound_at: cuándo llegó el último mensaje del cliente y cuándo salió hacia él el último mensaje que no falló. Los mensajes suprimidos, el historial de WhatsApp importado y los mensajes de los visitantes del chat web no cuentan como entrantes, así que una conversación chatbot lo trae como null. El historial de WhatsApp importado sí cuenta como saliente.

El nombre, el teléfono o el usuario del contacto viajan en el lead vinculado, no en la conversación. Para ver el conjunto de todos los canales de un lead, lee la faceta response del lead con GET /v1/leads/{id}.

Usa GET /v1/conversations y GET /v1/conversations/{id} para consultar conversaciones; GET /v1/conversations?lead= lista las conversaciones de un lead. Para mantener una copia, sigue el feed de cambios: lo explica Sincroniza una copia.

Lista las conversaciones

GET /v1/conversations

Devuelve una página de conversaciones del equipo, una por canal, cuenta de empresa y dirección de contacto: canal, estado en la bandeja de entrada, responsable y la hora de los últimos mensajes recibidos y enviados. Envía lead para obtener las conversaciones de un lead. El contenido de los mensajes nunca se exporta.

Permisos
messages:read
Límite de frecuencia
Sincronización

Parámetros de consulta

  • limit integer Rango 1–100 Por defecto 25

    Elementos por página, de 1 a 100. Por defecto, 25.

  • cursor string 1–512 caracteres

    El next_cursor de la página anterior. Omítelo en la primera página.

  • lead string Prefijo del id lead_…

    Solo las conversaciones vinculadas a este lead: el lead de cada elemento es este identificador. Un lead de otro equipo, o que no existe, no coincide con nada.

Cabeceras

  • Totem-Team string Condicional Prefijo del id team_…

    El equipo que se lee, como identificador team_…. Omítelo si la clave lee un solo equipo; es obligatorio si lee varios (400 team_required). Si lo envías, debe indicar un equipo que la clave lee: un identificador mal formado recibe 400 invalid_request, y un equipo fuera de la clave, 404 team_not_accessible, igual que una petición sin la cabecera cuando la clave ya no lee ningún equipo.

Respuesta

Devuelve una lista de objetos Conversation.

  • object string

    Siempre list.

  • data Array<Conversation>

    Los elementos de esta página.

  • has_more boolean

    true si hay otra página: pídela con next_cursor, aunque esta traiga menos elementos que limit.

  • next_cursor string Puede ser null

    Cursor opaco de la página siguiente, o null en la última. No lo interpretes.

Errores

+ 12 errores comunes

GET /v1/conversations
curl 'https://api.totemstudio.ai/v1/conversations?limit=25' \
  -H "Authorization: Bearer $TOTEM_API_KEY" \
  -H "Totem-Team: $TOTEM_TEAM_ID"
Respuesta · 200JSON
{
  "object": "list",
  "data": [
    {
      "id": "conv_m3GhGjRHmFbww1g10oqOp7j3gWqPJ",
      "object": "conversation",
      "livemode": false,
      "team": "team_r9uYrIW4gSFJJ6hZQ9ip1UIpPaAD1CF7NR",
      "lead": "lead_r72EfbRNUzuqORFJR0O8HxAwEXd93jGUTYMaMMXKSF0QbLS8CiUKJpEP34LFQG",
      "channel_type": "whatsapp",
      "status": "active",
      "assignee": "mem_h548E7UiYhutHhucVrQCzkM0eaea0",
      "reply_mode": "ai",
      "created_at": "2026-09-28T10:16:00.000Z",
      "last_inbound_at": "2026-10-01T08:58:00.000Z",
      "last_outbound_at": "2026-10-01T08:59:30.000Z",
      "version": 12,
      "updated_at": "2026-10-01T08:59:31.040Z"
    }
  ],
  "has_more": false,
  "next_cursor": null
}

Obtén una conversación

GET /v1/conversations/{id}

Devuelve una conversación por su identificador, sin el contenido de los mensajes. Una conversación que esta clave no puede leer, o que se eliminó, responde 404 resource_missing.

Permisos
messages:read
Límite de frecuencia
Lectura

Parámetros de ruta

  • id string Obligatorio Prefijo del id conv_…

    El identificador público de la conversación.

Respuesta

Devuelve un objeto Conversation.

Errores

+ 12 errores comunes

GET /v1/conversations/{id}
curl 'https://api.totemstudio.ai/v1/conversations/conv_m3GhGjRHmFbww1g10oqOp7j3gWqPJ' \
  -H "Authorization: Bearer $TOTEM_API_KEY"
Respuesta · 200JSON
{
  "id": "conv_m3GhGjRHmFbww1g10oqOp7j3gWqPJ",
  "object": "conversation",
  "livemode": false,
  "team": "team_r9uYrIW4gSFJJ6hZQ9ip1UIpPaAD1CF7NR",
  "lead": "lead_r72EfbRNUzuqORFJR0O8HxAwEXd93jGUTYMaMMXKSF0QbLS8CiUKJpEP34LFQG",
  "channel_type": "whatsapp",
  "status": "active",
  "assignee": "mem_h548E7UiYhutHhucVrQCzkM0eaea0",
  "reply_mode": "ai",
  "created_at": "2026-09-28T10:16:00.000Z",
  "last_inbound_at": "2026-10-01T08:58:00.000Z",
  "last_outbound_at": "2026-10-01T08:59:30.000Z",
  "version": 12,
  "updated_at": "2026-10-01T08:59:31.040Z"
}

El objeto Conversation

Una conversación en un canal: su estado, su responsable y la hora de los últimos mensajes, nunca su contenido.

Atributos

  • id string Prefijo del id conv_…

    Identificador público del registro.

  • object string

    Siempre conversation.

  • livemode boolean

    true en datos reales; false en los datos de ejemplo.

  • team string Prefijo del id team_…

    El equipo al que pertenece este registro.

  • lead string Puede ser null Prefijo del id lead_…

    El lead al que está vinculada la conversación, o null si no está vinculada o el lead ya no existe. El nombre, el teléfono y el usuario solo aparecen en el lead.

  • channel_type string Puede ser null

    El canal: whatsapp, email, chatbot (el chat web), facebook, instagram, sms o tiktok; null si es un valor que esta versión no conoce. Un lead puede tener varias conversaciones en el mismo canal y cuenta de empresa, una por cada dirección de contacto (teléfono, correo electrónico o usuario) que haya usado, así que usa el id como clave de tu copia.

    Valores posibles
    • sms
    • whatsapp
    • facebook
    • instagram
    • tiktok
    • chatbot
    • email
  • status string Puede ser null

    active o archived en la bandeja del equipo; null si es un valor que esta versión no conoce.

    Valores posibles
    • active
    • archived
  • assignee string Puede ser null Prefijo del id mem_…

    El miembro del equipo asignado a la conversación (ver /members), o null.

  • reply_mode string

    human mientras una persona ha tomado la conversación, incluido un chat de WhatsApp que se atiende desde la app WhatsApp Business; ai en otro caso. ai significa que no hay una toma activa, no que haya un asistente configurado o respondiendo en este canal. Una toma temporal vuelve a ai cuando caduca, y la versión del registro cambia entonces.

    Valores posibles
    • ai
    • human
  • created_at string Puede ser null Formato date-time

    Cuándo se creó la conversación (UTC).

  • last_inbound_at string Puede ser null Formato date-time

    El último mensaje del cliente (UTC). No cuentan: mensajes borrados, historial de WhatsApp importado ni los turnos del visitante del chat web, así que una conversación chatbot da null. Los contenidos compartidos de Instagram no se distinguen y sí cuentan.

  • last_outbound_at string Puede ser null Formato date-time

    El último mensaje enviado al cliente que no falló (UTC), lo enviara quien lo enviara. El historial de WhatsApp importado sí cuenta.

  • version integer Rango ≥ 1

    Aumenta cada vez que cambia alguno de los campos exportados del registro. Aplica un cambio solo si su versión es mayor que la que guardas.

  • updated_at string Formato date-time

    Cuándo registró Totem esta versión (UTC). No es la hora en que ocurrió el hecho.

Conversation · ejemploJSON
{
  "id": "conv_m3GhGjRHmFbww1g10oqOp7j3gWqPJ",
  "object": "conversation",
  "livemode": false,
  "team": "team_r9uYrIW4gSFJJ6hZQ9ip1UIpPaAD1CF7NR",
  "lead": "lead_r72EfbRNUzuqORFJR0O8HxAwEXd93jGUTYMaMMXKSF0QbLS8CiUKJpEP34LFQG",
  "channel_type": "whatsapp",
  "status": "active",
  "assignee": "mem_h548E7UiYhutHhucVrQCzkM0eaea0",
  "reply_mode": "ai",
  "created_at": "2026-09-28T10:16:00.000Z",
  "last_inbound_at": "2026-10-01T08:58:00.000Z",
  "last_outbound_at": "2026-10-01T08:59:30.000Z",
  "version": 12,
  "updated_at": "2026-10-01T08:59:31.040Z"
}

Versión de la API 1.0a