Exporta las conversaciones de tu equipo, misión por misión
Esta guía te lleva de principio a fin para sacar de Cody las conversaciones de tu equipo con sus agentes y llevarlas a tu herramienta de reportes, tu data warehouse o una hoja de cálculo: crear la credencial, conseguir el token, encontrar los IDs, filtrar por misión, fechas, personas o agente, descargar todas las páginas y convertir el resultado a CSV. Todos los ejemplos usan datos simulados con el mismo formato que entrega la Public API.
Lectura estimada: 16 minutos · Para equipos de TI, analistas de datos e integradores · Necesitas poder hacer solicitudes HTTP desde un servidor o un script.
¿Prefieres tenerla a la mano?
Descarga esta guía en Markdown para consultarla sin conexión, compartirla con tu equipo o dársela a tu asistente de IA para que te acompañe paso a paso.
1 · Descripción
Qué vas a lograr
Llevarte las conversaciones que ocurrieron en Cody, con el detalle que necesitas y sin pedirlas a nadie.
Cada vez que alguien de tu equipo platica con un agente de Cody queda una conversación (en la API se llama «thread»): sus mensajes, las respuestas del agente, cuánto tardó en responder, la liga de la foto que la persona haya enviado y, si la conversación nació de una misión de gamificación, a qué misión pertenece. La Public API te deja exportar todo eso con tres consultas, según el nivel de detalle que necesites:
Conversaciones completas
GET /data/threads: cada conversación con su persona, su agente, su misión y todos sus mensajes con la respuesta del agente.
Mensaje por mensaje
GET /data/messages: un renglón plano por cada mensaje de las personas, listo para una tabla. Incluye el correo de quien escribió.
Exportación sin correos
GET /data/messages/export: los mismos renglones sin el correo, para compartir con quien no debe ver datos personales.
Fotos de la conversación
Cuando una persona envía una foto, las tres consultas traen su liga pública en media_url (o MediaUrl). Detalle en Las fotos que envía tu equipo.
Filtro por misión
Las tres aceptan challenge_id: el identificador de una misión. Es la forma más directa de medir una campaña o una temporada.
- Solicitud
- Respuesta
- Ocurre en segundo plano
Todos los datos de esta guía son simulados
La empresa «Grupo Aurora», sus personas, misiones e IDs no existen. Lo que sí es real es la forma: los nombres de los campos, sus tipos, el orden y el sobre de paginación son exactamente los que entrega la Public API.
2 · Antes de empezar
Lo que necesitas
Revisa esta lista antes de escribir la primera línea: si falta una pieza, la exportación regresa vacía o con error.
Una credencial de servicio
Un administrador la crea en el AMS, en Infraestructura → Integraciones API. El paso a paso está en la guía Credenciales para la Public API.
Que actúe como administrador
La credencial ve lo que ve la persona que eligieron al crearla. Para exportar las conversaciones de toda tu organización, pide que actúe como un administrador.
Un lugar seguro para correr
Un servidor, un proceso programado o una herramienta de automatización. Nunca desde una página web ni una app: las credenciales son secretas.
La URL base
Todas las rutas de esta guía se escriben después de https://api.public.cody-tech.com.
Lo que exportas incluye datos personales
/data/threads y /data/messages traen el nombre y el correo de las personas. Guárdalos con el mismo cuidado que cualquier dato personal y, si el archivo va a circular fuera de tu equipo, usa /data/messages/export, que no incluye correos (las ligas de las fotos sí viajan, ver Las fotos que envía tu equipo).
3 · Credencial y token
Consigue tu access token
La credencial se crea una vez; el token se renueva cada hora sin intervención de nadie.
Pide la credencial a un administrador
En el AMS, un administrador abre Infraestructura → Integraciones API, hace clic en Nueva credencial, le pone un nombre como «Exportación de datos BI», elige en nombre de qué persona actuará y copia los cuatro valores que aparecen. El recorrido completo, con capturas, está en Credenciales para la Public API.

Los cuatro valores aparecen una sola vez, al crear la credencial. Datos de ejemplo.
Guárdala en variables de entorno
Guarda los valores en el gestor de secretos de tu equipo o en variables de entorno del servidor que va a correr la exportación. Nunca en el código ni en un repositorio.
# URL base de la Public API de Cody.
CODY_API_URL="https://api.public.cody-tech.com"
# Valores entregados al crear la credencial de servicio en Cody AMS.
# Guárdalos en tu gestor de secretos; nunca en el código fuente.
CODY_CLIENT_ID="<client-id>"
CODY_CLIENT_SECRET="<client-secret>"
CODY_REFRESH_TOKEN="<refresh-token>"
CODY_ACCESS_TOKEN="<access-token>" # vigente por 1 horaRenueva el access token
El access token vence a la hora. Al empezar cada exportación, pide uno nuevo con tu Client ID, tu Client Secret y tu Refresh Token. El refresh token no cambia: consérvalo.
curl -X POST "$CODY_API_URL/auth/oauth/v2/refresh" \
-H "Content-Type: application/json" \
-d '{
"client_id": "'"$CODY_CLIENT_ID"'",
"client_secret": "'"$CODY_CLIENT_SECRET"'",
"refresh_token": "'"$CODY_REFRESH_TOKEN"'"
}'{
"access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
"token_type": "Bearer",
"expires_in": 3600
}Cada consulta de esta guía lleva ese token en el encabezado Authorization:
Authorization: Bearer <access_token>
Content-Type: application/jsonSi una consulta responde 401
El token venció a media descarga. Renueva y reintenta esa misma página una sola vez; no empieces la exportación desde cero.
4 · IDs
Encuentra los IDs para filtrar
Los filtros trabajan con identificadores, no con nombres. Así obtienes cada uno.
Misiones: el challenge_id
Cada misión de gamificación tiene un id: ese es el challenge_id que usarás para filtrar. Lista las misiones de tu organización y quédate con el id de la que te interesa. Puedes acotar con status (active, locked o completed) o con season_id para ver solo las de una temporada.
curl "$CODY_API_URL/gamification-challenge/list?status=active&limit=100" \
-H "Authorization: Bearer $CODY_ACCESS_TOKEN"[
{
"id": "6710f3a2c4b5d6e7f8091a2b",
"season_id": "6710e1b0a1b2c3d4e5f60718",
"name": "Venta cruzada del día",
"goal": "5",
"description": "Ofrece un complemento en cada venta y registra cuántos clientes lo aceptaron.",
"agent_id": "66b7c8d9e0f1a2b3c4d5e6f7",
"agent_context_action": "Pregunta cuántas ventas cruzadas hizo la persona y regístralas.",
"difficulty": "medium",
"status": "active",
"stored_status": "active",
"effective_status": "active",
"schedule_open": true,
"schedule": {
"type": "daily",
"timezone": "America/Mexico_City",
"start_time": "09:00",
"end_time": "21:00",
"start_date": "2026-10-01",
"end_date": "2026-12-31",
"days_of_week": [],
"day_of_month": null,
"day_of_month_range_start": null,
"day_of_month_range_end": null
},
"display_order": 0,
"orgchart_element_ids": [
"66c0d1e2f3a4b5c6d7e8f901"
]
},
{
"id": "6710f3a2c4b5d6e7f8091a2c",
"season_id": "6710e1b0a1b2c3d4e5f60718",
"name": "Recomienda el producto del mes",
"goal": "10",
"description": "Recomienda el producto del mes en cada venta y registra cuántas veces lo ofreciste.",
"agent_id": "66b7c8d9e0f1a2b3c4d5e6f7",
"agent_context_action": "",
"difficulty": "easy",
"status": "active",
"stored_status": "active",
"effective_status": "active",
"schedule_open": true,
"schedule": null,
"display_order": 1,
"orgchart_element_ids": []
}
]| Campo | Qué contiene |
|---|---|
id | El identificador de la misión. Es el valor de challenge_id en los filtros. |
name / description | Nombre y descripción vigentes de la misión. |
season_id | La temporada a la que pertenece. |
agent_id | El agente que acompaña la misión, si tiene uno. Sirve como filtro agent_id. |
status | active, locked o completed, ya considerando su horario. |
schedule | Cuándo está abierta la misión (tipo, zona horaria, horas y fechas), o null si no tiene horario. |
La respuesta es una lista directa
A diferencia de las consultas de datos, /gamification-challenge/list responde un arreglo, sin total. Pide de 100 en 100 (hasta 1,000) con skip y limit hasta que llegue una lista vacía.
Personas: los user_ids
Para exportar solo a ciertas personas, necesitas su ID de usuario en Cody. Lista los usuarios y arma una tabla de equivalencias con el correo, que es lo que normalmente tienes en tus sistemas.
curl "$CODY_API_URL/user/list?skip=0&limit=1000" \
-H "Authorization: Bearer $CODY_ACCESS_TOKEN"[
{
"id": "664f5f3c2f4f5e3b1c2a9d10",
"name": "Ana",
"lastname": "Torres Vega",
"username": "ana.torres",
"email": "ana.torres@ejemplo.com"
},
{
"id": "664f5f3c2f4f5e3b1c2a9d11",
"name": "Diego",
"lastname": "Ramírez Peña",
"username": "diego.ramirez",
"email": "diego.ramirez@ejemplo.com"
},
{
"id": "664f5f3c2f4f5e3b1c2a9d12",
"name": "Fernanda",
"lastname": "Castillo Ruiz",
"username": "fernanda.castillo",
"email": "fernanda.castillo@ejemplo.com"
}
]Agentes y conversaciones: agent_id y thread_id
- `agent_id`: viene en cada misión (
agent_id) y en cada conversación exportada (agent.agent_id). También lo ves en el AMS: al abrir un agente en Mis Agentes → Todos los Agentes, es la última parte de la dirección de la página (/assistants/<agent_id>). - `thread_id`: viene en cada conversación (
thread_id) y en cada renglón de mensajes (ThreadId). Úsalo para volver a pedir una conversación completa.
5 · Qué exportar
Elige la consulta adecuada
Las tres comparten autenticación, paginación y el filtro por misión; cambian en el detalle que entregan.
| Consulta | Un elemento es… | Trae la respuesta del agente | Trae el correo | Ideal para |
|---|---|---|---|---|
GET /data/threads | Una conversación con todos sus mensajes | Sí (answer) | Sí (user.email) | Análisis de calidad, auditoría y reportes por misión. |
GET /data/messages | Un mensaje de una persona | No, solo el tiempo de respuesta | Sí (UserEmail) | Tablas de actividad y conteos por día o por persona. |
GET /data/messages/export | Un mensaje de una persona | No, solo el tiempo de respuesta | No | Archivos que se comparten fuera del equipo. |
| Campo | Tipo | Qué contiene |
|---|---|---|
thread_id | texto | ID de la conversación. |
challenge_id | texto o null | La misión de la que nació la conversación, si tiene una. |
challenge | objeto o null | challenge_id, name y description vigentes de la misión; null si no tiene o ya no existe. |
topic | texto o null | El nombre de la misión si tiene una; si no, el título de la conversación. |
thread_title / thread_summary | texto o null | Título y resumen que Cody genera de la conversación. |
test_mode | sí / no | true si fue una conversación de prueba (solo aparecen si las pides). |
created_at / updated_at | fecha y hora | Inicio y última actividad, en hora UTC. |
custom_metadata | objeto o null | Datos adicionales de la conversación, como su challenge_id. |
user | objeto | user_id, name, lastname y email de la persona. |
agent | objeto o null | agent_id y name del agente. |
message_count | número | Cuántos mensajes tiene, aunque no pidas su contenido. |
messages | lista | Cada mensaje: message_id, message (lo que escribió la persona), answer (la respuesta del agente), answer_time (segundos), created_at, custom_metadata y media_url (la liga de la foto que envió la persona, o null). |
| Campo | Qué contiene |
|---|---|
MessageDate / MessageTime | Fecha (AAAA-MM-DD) y hora (HH:MM:SS) del mensaje, en UTC. |
MessageID | ID del mensaje. |
ResponseTime | Segundos que tardó el agente en responder, o null. |
UserID | ID de la persona que escribió. |
UserEmail | Su correo. No viene en `/data/messages/export`. |
ThreadId | ID de la conversación a la que pertenece. |
Message | Lo que escribió la persona. |
MediaUrl | La liga pública de la foto que envió la persona en ese mensaje, o null si no envió ninguna. |
Topic | El nombre de la misión si la conversación tiene una; si no, el título de la conversación. |
ChallengeId | El challenge_id de la conversación, o null. |
Solo ves los datos de tu organización
La credencial queda fijada a tu organización: aunque envíes otro tenant_id, la Public API lo ignora y solo te entrega tus propias conversaciones.
6 · Fotos
Las fotos que envía tu equipo
Cuando alguien comparte una foto con un agente, su liga viaja en la exportación, junto al mensaje en que la envió.
Una persona puede enviarle una foto al agente, por ejemplo en un paso Pregunta con foto de un flujo de Workflow Studio (consulta Automatiza procesos con Workflow Studio). Cody guarda la imagen y la deja ligada al mensaje en que se envió. Al exportar, ese mensaje trae la liga pública de la foto: no tienes que pedirla aparte.
| Consulta | Campo | Dónde |
|---|---|---|
GET /data/threads | media_url | Dentro de cada elemento de messages. |
GET /data/messages | MediaUrl | En el renglón del mensaje. |
GET /data/messages/export | MediaUrl | En el renglón del mensaje. Quitar el correo no quita la liga de la foto. |
El mensaje con foto trae la liga; los demás traen el mismo campo en null:
{
"message_id": "6719b8e4a1c2d3e4f5a6b7c9",
"message": "Así quedó la exhibición de pantallas, ¿qué opinas?",
"answer": "Se ve ordenada y las pantallas de 55 y 65 pulgadas quedan a la altura de los ojos. Pon el letrero de la barra de sonido junto a los soportes para que se vea el complemento.",
"answer_time": 4.37,
"created_at": "2026-10-21T19:12:40.115000",
"custom_metadata": null,
"media_url": "https://storage.googleapis.com/cody-media-aurora/media/6719b8e1a1c2d3e4f5a6b7c8/exhibicion-pantallas.jpg"
}- El campo siempre está presente. Un mensaje sin foto trae
null, así que tu proceso no necesita tratar el campo como opcional. - Mensajes anteriores a esta función no traen liga, aunque en su momento hayan llevado una foto.
- No hay un filtro para pedir solo los mensajes con foto. Descarga con los filtros de siempre y quédate con los renglones cuya liga no sea
null. - La liga abre la imagen directamente, sin el token de la Public API.
Quien tenga la liga puede ver la foto
La liga es pública: se abre sin iniciar sesión. Las fotos pueden mostrar personas, tiendas o documentos, así que trátala con el mismo cuidado que un dato personal y no la publiques. Si compartes un archivo exportado fuera de tu equipo, recuerda que /data/messages/export quita los correos pero conserva las ligas de las fotos.
Si necesitas guardar las fotos en tu propio almacenamiento, recorre los renglones y descarga cada liga:
# La liga de la imagen es pública: no necesita el token de la Public API
curl -L -o exhibicion-pantallas.jpg "https://storage.googleapis.com/cody-media-aurora/media/6719b8e1a1c2d3e4f5a6b7c8/exhibicion-pantallas.jpg"¿Prefieres verlas sin código?
En el AMS, al abrir una conversación en la pestaña Observabilidad de un agente, la foto aparece en el mensaje de quien la envió, y la descarga de conversaciones, en CSV o en JSON, incluye la liga en media_url. El recorrido está en la guía Ajusta y supervisa a tus agentes.
7 · Filtros
Todos los filtros, de un vistazo
Combínalos como necesites: cada filtro que agregas acota el resultado.
| Filtro | Formato | Qué hace |
|---|---|---|
challenge_id | ID de misión | Solo conversaciones de esa misión. Sin él, entran todas, tengan misión o no. |
date_from / date_to | AAAA-MM-DD | Por día de inicio de la conversación, ambos días incluidos. |
created_from / created_to | Fecha y hora ISO, ej. 2026-10-21T14:00:00Z | Por momento exacto de inicio, ambos incluidos. Si los envías, mandan sobre date_from / date_to. |
user_ids | IDs separados por comas | Solo conversaciones de esas personas. Máximo 100 por consulta. |
agent_id | ID de agente | Solo conversaciones con ese agente. |
thread_id | ID de conversación | Solo esa conversación. |
search | Texto (hasta 100 caracteres) | Busca en el título y el resumen de la conversación, sin distinguir mayúsculas. |
include_messages | true / false | true (por omisión) trae los mensajes; false trae solo la conversación y message_count. |
include_test_mode | true / false | false (por omisión) deja fuera las conversaciones de prueba. |
skip / limit | Números | Paginación: limit va de 1 a 500 (100 por omisión). |
| Filtro | Formato | Qué hace |
|---|---|---|
challenge_id | ID de misión | Solo mensajes de conversaciones de esa misión. |
start / end | Fecha y hora ISO, ej. 2026-10-01T00:00:00Z | Por momento del mensaje. start debe ser anterior a end. |
include_test_mode | true / false | false (por omisión) deja fuera los mensajes de conversaciones de prueba. |
skip / limit | Números | Paginación: limit va de 1 a 500 (100 por omisión). |
Ojo con el periodo por omisión: 30 días
/data/messages y /data/messages/export siempre se limitan a los últimos 30 días si no envías start, aunque filtres por misión. /data/threads solo lo hace cuando no envías ni challenge_id, ni thread_id, ni date_from, ni created_from: con challenge_id te entrega todo el historial de la misión.
Todas las fechas son UTC
Las fechas que envías y las que recibes están en hora UTC. En el centro de México son 6 horas más que la hora local: las 9:00 de la mañana en Ciudad de México son las 15:00:00Z.
8 · Por misión
Ejemplo: todas las conversaciones de una misión
El caso más común: medir una misión de principio a fin.
Con solo el challenge_id recibes todas las conversaciones de la misión, de la más reciente a la más antigua, cada una con sus mensajes en orden de llegada.
curl -G "$CODY_API_URL/data/threads" \
-H "Authorization: Bearer $CODY_ACCESS_TOKEN" \
--data-urlencode "challenge_id=6710f3a2c4b5d6e7f8091a2b" \
--data-urlencode "limit=100"{
"items": [
{
"thread_id": "6719a0c1b2d3e4f5a6b7c8d9",
"tenant_id": "66a1b2c3d4e5f60718293a4b",
"challenge_id": "6710f3a2c4b5d6e7f8091a2b",
"challenge": {
"challenge_id": "6710f3a2c4b5d6e7f8091a2b",
"name": "Venta cruzada del día",
"description": "Ofrece un complemento en cada venta y registra cuántos clientes lo aceptaron."
},
"thread_title": "Complementos para pantallas",
"topic": "Venta cruzada del día",
"thread_summary": "Ana pidió ideas de complementos para clientes que compran pantallas y reportó 4 ventas cruzadas al cierre del turno.",
"test_mode": false,
"created_at": "2026-10-21T15:04:12.318000",
"updated_at": "2026-10-21T22:41:07.902000",
"custom_metadata": {
"challenge_id": "6710f3a2c4b5d6e7f8091a2b"
},
"user": {
"user_id": "664f5f3c2f4f5e3b1c2a9d10",
"name": "Ana",
"lastname": "Torres Vega",
"email": "ana.torres@ejemplo.com"
},
"agent": {
"agent_id": "66b7c8d9e0f1a2b3c4d5e6f7",
"name": "Coach Comercial"
},
"message_count": 3,
"messages": [
{
"message_id": "6719a0c5e1f2a3b4c5d6e7f8",
"message": "¿Qué le ofrezco a alguien que se lleva una pantalla de 55 pulgadas?",
"answer": "Tres opciones que suelen funcionar: un soporte de pared, una barra de sonido y la garantía extendida. Empieza por el soporte: casi todos lo necesitan y lo aceptan más fácil.",
"answer_time": 2.84,
"created_at": "2026-10-21T15:04:12.318000",
"custom_metadata": null,
"media_url": null
},
{
"message_id": "6719b8e4a1c2d3e4f5a6b7c9",
"message": "Así quedó la exhibición de pantallas, ¿qué opinas?",
"answer": "Se ve ordenada y las pantallas de 55 y 65 pulgadas quedan a la altura de los ojos. Pon el letrero de la barra de sonido junto a los soportes para que se vea el complemento.",
"answer_time": 4.37,
"created_at": "2026-10-21T19:12:40.115000",
"custom_metadata": null,
"media_url": "https://storage.googleapis.com/cody-media-aurora/media/6719b8e1a1c2d3e4f5a6b7c8/exhibicion-pantallas.jpg"
},
{
"message_id": "6719d2f0a9b8c7d6e5f4a3b2",
"message": "Cerré el turno con 4 ventas cruzadas, 3 de soporte y 1 de barra de sonido.",
"answer": "¡Excelente cierre, Ana! Ya registré tus 4 ventas cruzadas en la misión de hoy. Mañana prueba ofrecer la barra de sonido primero a quien compre pantallas de 65 pulgadas.",
"answer_time": 3.12,
"created_at": "2026-10-21T22:41:07.902000",
"custom_metadata": null,
"media_url": null
}
]
},
{
"thread_id": "6719a0c1b2d3e4f5a6b7c8da",
"tenant_id": "66a1b2c3d4e5f60718293a4b",
"challenge_id": "6710f3a2c4b5d6e7f8091a2b",
"challenge": {
"challenge_id": "6710f3a2c4b5d6e7f8091a2b",
"name": "Venta cruzada del día",
"description": "Ofrece un complemento en cada venta y registra cuántos clientes lo aceptaron."
},
"thread_title": "Complementos para celulares",
"topic": "Venta cruzada del día",
"thread_summary": "Diego preguntó qué ofrecer con un celular de gama media y registró 2 ventas de fundas con mica.",
"test_mode": false,
"created_at": "2026-10-20T17:22:45.051000",
"updated_at": "2026-10-20T17:30:18.664000",
"custom_metadata": {
"challenge_id": "6710f3a2c4b5d6e7f8091a2b"
},
"user": {
"user_id": "664f5f3c2f4f5e3b1c2a9d11",
"name": "Diego",
"lastname": "Ramírez Peña",
"email": "diego.ramirez@ejemplo.com"
},
"agent": {
"agent_id": "66b7c8d9e0f1a2b3c4d5e6f7",
"name": "Coach Comercial"
},
"message_count": 2,
"messages": [
{
"message_id": "6718f1b5c4d3e2f1a0b9c8d7",
"message": "Un cliente se lleva un celular de gama media, ¿qué le ofrezco?",
"answer": "Funda con mica incluida: protege la compra y es el complemento que más se acepta en esa gama.",
"answer_time": 1.97,
"created_at": "2026-10-20T17:22:45.051000",
"custom_metadata": null,
"media_url": null
},
{
"message_id": "6718f3a2b1c0d9e8f7a6b5c4",
"message": "Listo, vendí 2 fundas con mica.",
"answer": "¡Bien hecho, Diego! Registré 2 ventas cruzadas en tu misión de hoy.",
"answer_time": 1.45,
"created_at": "2026-10-20T17:30:18.664000",
"custom_metadata": null,
"media_url": null
}
]
}
],
"total": 2,
"skip": 0,
"limit": 100
}totales el número de conversaciones que cumplen el filtro, no el tamaño de esta página. Te dice cuántas páginas faltan.topicychallenge.namemuestran el nombre actual de la misión, aunque haya cambiado después de la conversación.- Dentro de cada conversación,
messagees lo que escribió la persona yanswer, lo que respondió el agente.
9 · Por fechas
Ejemplo: una misión en un periodo
Por días completos o con hora exacta.
Por días completos: date_from y date_to
Úsalos para cortes de mes, de semana o de temporada. date_to incluye todo ese día.
# Conversaciones de la misión creadas entre el 1 y el 31 de octubre (ambos días incluidos)
curl -G "$CODY_API_URL/data/threads" \
-H "Authorization: Bearer $CODY_ACCESS_TOKEN" \
--data-urlencode "challenge_id=6710f3a2c4b5d6e7f8091a2b" \
--data-urlencode "date_from=2026-10-01" \
--data-urlencode "date_to=2026-10-31"Con hora exacta: created_from y created_to
Úsalos para turnos o para exportaciones incrementales (por ejemplo, «todo lo nuevo desde la última vez que corrí el proceso»). Ambos extremos están incluidos.
# Solo el turno de la tarde del 21 de octubre, en hora UTC
curl -G "$CODY_API_URL/data/threads" \
-H "Authorization: Bearer $CODY_ACCESS_TOKEN" \
--data-urlencode "challenge_id=6710f3a2c4b5d6e7f8091a2b" \
--data-urlencode "created_from=2026-10-21T14:00:00Z" \
--data-urlencode "created_to=2026-10-21T23:59:59Z"Exportación incremental sin huecos
Guarda el created_at más reciente que recibiste y úsalo como created_from en la siguiente ejecución. Como el extremo está incluido, puede repetirse una conversación: descártala por su thread_id.
10 · Personas y agente
Ejemplo: personas, agente, texto y una conversación
Para enfocar la exportación en un equipo, un agente o un tema.
Solo ciertas personas: user_ids
Envía los IDs en un solo parámetro separado por comas. Si repites user_ids=…&user_ids=…, solo se toma en cuenta el último. Para más de 100 personas, divide la lista y haz varias consultas.
# Varias personas: un solo parámetro con los IDs separados por comas (máximo 100)
curl -G "$CODY_API_URL/data/threads" \
-H "Authorization: Bearer $CODY_ACCESS_TOKEN" \
--data-urlencode "challenge_id=6710f3a2c4b5d6e7f8091a2b" \
--data-urlencode "user_ids=664f5f3c2f4f5e3b1c2a9d10,664f5f3c2f4f5e3b1c2a9d11"Un agente y un tema: agent_id y search
# Conversaciones del agente Coach Comercial que mencionan "pantalla" en su título o resumen
curl -G "$CODY_API_URL/data/threads" \
-H "Authorization: Bearer $CODY_ACCESS_TOKEN" \
--data-urlencode "agent_id=66b7c8d9e0f1a2b3c4d5e6f7" \
--data-urlencode "search=pantalla" \
--data-urlencode "date_from=2026-10-01"Solo el resumen: include_messages=false
Cuando solo necesitas contar conversaciones o armar un tablero, pide la conversación sin el contenido de sus mensajes: la respuesta es mucho más ligera y message_count conserva el número real de mensajes.
# Solo el resumen de cada conversación: más ligero, ideal para contar o hacer un tablero
curl -G "$CODY_API_URL/data/threads" \
-H "Authorization: Bearer $CODY_ACCESS_TOKEN" \
--data-urlencode "challenge_id=6710f3a2c4b5d6e7f8091a2b" \
--data-urlencode "include_messages=false"{
"items": [
{
"thread_id": "6719a0c1b2d3e4f5a6b7c8d9",
"tenant_id": "66a1b2c3d4e5f60718293a4b",
"challenge_id": "6710f3a2c4b5d6e7f8091a2b",
"challenge": {
"challenge_id": "6710f3a2c4b5d6e7f8091a2b",
"name": "Venta cruzada del día",
"description": "Ofrece un complemento en cada venta y registra cuántos clientes lo aceptaron."
},
"thread_title": "Complementos para pantallas",
"topic": "Venta cruzada del día",
"thread_summary": "Ana pidió ideas de complementos para clientes que compran pantallas y reportó 4 ventas cruzadas al cierre del turno.",
"test_mode": false,
"created_at": "2026-10-21T15:04:12.318000",
"updated_at": "2026-10-21T22:41:07.902000",
"custom_metadata": {
"challenge_id": "6710f3a2c4b5d6e7f8091a2b"
},
"user": {
"user_id": "664f5f3c2f4f5e3b1c2a9d10",
"name": "Ana",
"lastname": "Torres Vega",
"email": "ana.torres@ejemplo.com"
},
"agent": {
"agent_id": "66b7c8d9e0f1a2b3c4d5e6f7",
"name": "Coach Comercial"
},
"message_count": 3,
"messages": []
},
{
"thread_id": "6719a0c1b2d3e4f5a6b7c8da",
"tenant_id": "66a1b2c3d4e5f60718293a4b",
"challenge_id": "6710f3a2c4b5d6e7f8091a2b",
"challenge": {
"challenge_id": "6710f3a2c4b5d6e7f8091a2b",
"name": "Venta cruzada del día",
"description": "Ofrece un complemento en cada venta y registra cuántos clientes lo aceptaron."
},
"thread_title": "Complementos para celulares",
"topic": "Venta cruzada del día",
"thread_summary": "Diego preguntó qué ofrecer con un celular de gama media y registró 2 ventas de fundas con mica.",
"test_mode": false,
"created_at": "2026-10-20T17:22:45.051000",
"updated_at": "2026-10-20T17:30:18.664000",
"custom_metadata": {
"challenge_id": "6710f3a2c4b5d6e7f8091a2b"
},
"user": {
"user_id": "664f5f3c2f4f5e3b1c2a9d11",
"name": "Diego",
"lastname": "Ramírez Peña",
"email": "diego.ramirez@ejemplo.com"
},
"agent": {
"agent_id": "66b7c8d9e0f1a2b3c4d5e6f7",
"name": "Coach Comercial"
},
"message_count": 2,
"messages": []
}
],
"total": 2,
"skip": 0,
"limit": 100
}Una sola conversación: thread_id
# Una sola conversación, con todos sus mensajes
curl -G "$CODY_API_URL/data/threads" \
-H "Authorization: Bearer $CODY_ACCESS_TOKEN" \
--data-urlencode "thread_id=6719a0c1b2d3e4f5a6b7c8d9"11 · Mensajes
Ejemplo: renglones de mensajes de una misión
Cuando quieres una tabla plana, sin armar nada.
Con correo: /data/messages
Cada renglón es un mensaje que escribió una persona, del más reciente al más antiguo. Recuerda enviar start: sin él, solo recibes los últimos 30 días.
# Un renglón por mensaje de las personas en la misión, durante octubre (hora UTC)
curl -G "$CODY_API_URL/data/messages" \
-H "Authorization: Bearer $CODY_ACCESS_TOKEN" \
--data-urlencode "challenge_id=6710f3a2c4b5d6e7f8091a2b" \
--data-urlencode "start=2026-10-01T00:00:00Z" \
--data-urlencode "end=2026-10-31T23:59:59Z" \
--data-urlencode "limit=500"{
"conversations": [
{
"MessageDate": "2026-10-21",
"MessageTime": "22:41:07",
"MessageID": "6719d2f0a9b8c7d6e5f4a3b2",
"ResponseTime": 3.12,
"UserID": "664f5f3c2f4f5e3b1c2a9d10",
"UserEmail": "ana.torres@ejemplo.com",
"ThreadId": "6719a0c1b2d3e4f5a6b7c8d9",
"Message": "Cerré el turno con 4 ventas cruzadas, 3 de soporte y 1 de barra de sonido.",
"MediaUrl": null,
"Topic": "Venta cruzada del día",
"ChallengeId": "6710f3a2c4b5d6e7f8091a2b"
},
{
"MessageDate": "2026-10-21",
"MessageTime": "19:12:40",
"MessageID": "6719b8e4a1c2d3e4f5a6b7c9",
"ResponseTime": 4.37,
"UserID": "664f5f3c2f4f5e3b1c2a9d10",
"UserEmail": "ana.torres@ejemplo.com",
"ThreadId": "6719a0c1b2d3e4f5a6b7c8d9",
"Message": "Así quedó la exhibición de pantallas, ¿qué opinas?",
"MediaUrl": "https://storage.googleapis.com/cody-media-aurora/media/6719b8e1a1c2d3e4f5a6b7c8/exhibicion-pantallas.jpg",
"Topic": "Venta cruzada del día",
"ChallengeId": "6710f3a2c4b5d6e7f8091a2b"
},
{
"MessageDate": "2026-10-21",
"MessageTime": "15:04:12",
"MessageID": "6719a0c5e1f2a3b4c5d6e7f8",
"ResponseTime": 2.84,
"UserID": "664f5f3c2f4f5e3b1c2a9d10",
"UserEmail": "ana.torres@ejemplo.com",
"ThreadId": "6719a0c1b2d3e4f5a6b7c8d9",
"Message": "¿Qué le ofrezco a alguien que se lleva una pantalla de 55 pulgadas?",
"MediaUrl": null,
"Topic": "Venta cruzada del día",
"ChallengeId": "6710f3a2c4b5d6e7f8091a2b"
},
{
"MessageDate": "2026-10-20",
"MessageTime": "17:30:18",
"MessageID": "6718f3a2b1c0d9e8f7a6b5c4",
"ResponseTime": 1.45,
"UserID": "664f5f3c2f4f5e3b1c2a9d11",
"UserEmail": "diego.ramirez@ejemplo.com",
"ThreadId": "6719a0c1b2d3e4f5a6b7c8da",
"Message": "Listo, vendí 2 fundas con mica.",
"MediaUrl": null,
"Topic": "Venta cruzada del día",
"ChallengeId": "6710f3a2c4b5d6e7f8091a2b"
}
],
"total": 4,
"skip": 0,
"limit": 500
}Sin correo: /data/messages/export
Los mismos filtros y los mismos renglones, sin UserEmail. Es la opción para archivos que van a circular fuera de tu equipo.
# Mismos filtros que /data/messages, sin el correo de las personas
curl -G "$CODY_API_URL/data/messages/export" \
-H "Authorization: Bearer $CODY_ACCESS_TOKEN" \
--data-urlencode "challenge_id=6710f3a2c4b5d6e7f8091a2b" \
--data-urlencode "start=2026-10-01T00:00:00Z" \
--data-urlencode "end=2026-10-31T23:59:59Z" \
--data-urlencode "limit=500"{
"conversations": [
{
"MessageDate": "2026-10-21",
"MessageTime": "22:41:07",
"MessageID": "6719d2f0a9b8c7d6e5f4a3b2",
"ResponseTime": 3.12,
"UserID": "664f5f3c2f4f5e3b1c2a9d10",
"ThreadId": "6719a0c1b2d3e4f5a6b7c8d9",
"Message": "Cerré el turno con 4 ventas cruzadas, 3 de soporte y 1 de barra de sonido.",
"MediaUrl": null,
"Topic": "Venta cruzada del día",
"ChallengeId": "6710f3a2c4b5d6e7f8091a2b"
},
{
"MessageDate": "2026-10-21",
"MessageTime": "19:12:40",
"MessageID": "6719b8e4a1c2d3e4f5a6b7c9",
"ResponseTime": 4.37,
"UserID": "664f5f3c2f4f5e3b1c2a9d10",
"ThreadId": "6719a0c1b2d3e4f5a6b7c8d9",
"Message": "Así quedó la exhibición de pantallas, ¿qué opinas?",
"MediaUrl": "https://storage.googleapis.com/cody-media-aurora/media/6719b8e1a1c2d3e4f5a6b7c8/exhibicion-pantallas.jpg",
"Topic": "Venta cruzada del día",
"ChallengeId": "6710f3a2c4b5d6e7f8091a2b"
},
{
"MessageDate": "2026-10-21",
"MessageTime": "15:04:12",
"MessageID": "6719a0c5e1f2a3b4c5d6e7f8",
"ResponseTime": 2.84,
"UserID": "664f5f3c2f4f5e3b1c2a9d10",
"ThreadId": "6719a0c1b2d3e4f5a6b7c8d9",
"Message": "¿Qué le ofrezco a alguien que se lleva una pantalla de 55 pulgadas?",
"MediaUrl": null,
"Topic": "Venta cruzada del día",
"ChallengeId": "6710f3a2c4b5d6e7f8091a2b"
},
{
"MessageDate": "2026-10-20",
"MessageTime": "17:30:18",
"MessageID": "6718f3a2b1c0d9e8f7a6b5c4",
"ResponseTime": 1.45,
"UserID": "664f5f3c2f4f5e3b1c2a9d11",
"ThreadId": "6719a0c1b2d3e4f5a6b7c8da",
"Message": "Listo, vendí 2 fundas con mica.",
"MediaUrl": null,
"Topic": "Venta cruzada del día",
"ChallengeId": "6710f3a2c4b5d6e7f8091a2b"
}
],
"total": 4,
"skip": 0,
"limit": 500
}12 · Descarga completa
Descarga todo y conviértelo a CSV
Las consultas entregan páginas de hasta 500 elementos. Pide página tras página hasta reunir el total.
- Pide la primera página con
skip=0ylimit=500. - Lee
total: es cuántos elementos cumplen el filtro. - Suma 500 a
skipy pide la siguiente página. - Detente cuando
skipalcancetotalo cuando una página llegue vacía.
Este script hace todo el recorrido para una misión: renueva el token, descarga todas las páginas de /data/threads y escribe un CSV con un renglón por mensaje, los datos de su conversación al lado y, cuando el mensaje tiene foto, su liga en url_imagen.
"""Descarga todas las conversaciones de una misión y las guarda en un CSV.
Uso: python exportar_mision.py 6710f3a2c4b5d6e7f8091a2b
Requiere: pip install requests
"""
import csv
import os
import sys
import requests
CODY_API_URL = os.environ["CODY_API_URL"]
PAGE_SIZE = 500 # el máximo que acepta la Public API
def get_access_token() -> str:
"""Renueva el access token con la credencial de servicio."""
response = requests.post(
f"{CODY_API_URL}/auth/oauth/v2/refresh",
json={
"client_id": os.environ["CODY_CLIENT_ID"],
"client_secret": os.environ["CODY_CLIENT_SECRET"],
"refresh_token": os.environ["CODY_REFRESH_TOKEN"],
},
timeout=30,
)
response.raise_for_status()
return response.json()["access_token"]
def fetch_all_threads(token: str, filters: dict) -> list[dict]:
"""Pide páginas de 500 hasta reunir el total que reporta la API."""
threads, skip = [], 0
while True:
response = requests.get(
f"{CODY_API_URL}/data/threads",
params={**filters, "skip": skip, "limit": PAGE_SIZE},
headers={"Authorization": f"Bearer {token}"},
timeout=120,
)
response.raise_for_status()
page = response.json()
threads.extend(page["items"])
skip += PAGE_SIZE
if not page["items"] or skip >= page["total"]:
return threads
def to_rows(threads: list[dict]) -> list[dict]:
"""Un renglón por mensaje, con los datos de su conversación al lado."""
rows = []
for thread in threads:
user = thread["user"] or {}
agent = thread["agent"] or {}
for message in thread["messages"]:
rows.append({
"fecha_utc": message["created_at"],
"mision": thread["topic"],
"challenge_id": thread["challenge_id"],
"persona": f"{user.get('name') or ''} {user.get('lastname') or ''}".strip(),
"correo": user.get("email"),
"agente": agent.get("name"),
"conversacion": thread["thread_id"],
"pregunta": message["message"],
"respuesta": message["answer"],
"segundos_respuesta": message["answer_time"],
"url_imagen": message.get("media_url"), # vacío si el mensaje no tiene foto
})
return rows
if __name__ == "__main__":
challenge_id = sys.argv[1]
token = get_access_token()
threads = fetch_all_threads(token, {"challenge_id": challenge_id})
rows = to_rows(threads)
# utf-8-sig: Excel abre acentos y eñes sin configurar nada
with open(f"mision_{challenge_id}.csv", "w", newline="", encoding="utf-8-sig") as file:
writer = csv.DictWriter(file, fieldnames=list(rows[0]) if rows else ["fecha_utc"])
writer.writeheader()
writer.writerows(rows)
print(f"{len(threads)} conversaciones, {len(rows)} mensajes exportados")fecha_utc,mision,challenge_id,persona,correo,agente,conversacion,pregunta,respuesta,segundos_respuesta,url_imagen
2026-10-21T15:04:12.318000,Venta cruzada del día,6710f3a2c4b5d6e7f8091a2b,Ana Torres Vega,ana.torres@ejemplo.com,Coach Comercial,6719a0c1b2d3e4f5a6b7c8d9,¿Qué le ofrezco a alguien que se lleva una pantalla de 55 pulgadas?,"Tres opciones que suelen funcionar: un soporte de pared, una barra de sonido y la garantía extendida. …",2.84,
2026-10-21T19:12:40.115000,Venta cruzada del día,6710f3a2c4b5d6e7f8091a2b,Ana Torres Vega,ana.torres@ejemplo.com,Coach Comercial,6719a0c1b2d3e4f5a6b7c8d9,"Así quedó la exhibición de pantallas, ¿qué opinas?","Se ve ordenada y las pantallas de 55 y 65 pulgadas quedan a la altura de los ojos. …",4.37,https://storage.googleapis.com/cody-media-aurora/media/6719b8e1a1c2d3e4f5a6b7c8/exhibicion-pantallas.jpg
2026-10-21T22:41:07.902000,Venta cruzada del día,6710f3a2c4b5d6e7f8091a2b,Ana Torres Vega,ana.torres@ejemplo.com,Coach Comercial,6719a0c1b2d3e4f5a6b7c8d9,"Cerré el turno con 4 ventas cruzadas, 3 de soporte y 1 de barra de sonido.","¡Excelente cierre, Ana! …",3.12,
2026-10-20T17:22:45.051000,Venta cruzada del día,6710f3a2c4b5d6e7f8091a2b,Diego Ramírez Peña,diego.ramirez@ejemplo.com,Coach Comercial,6719a0c1b2d3e4f5a6b7c8da,"Un cliente se lleva un celular de gama media, ¿qué le ofrezco?",Funda con mica incluida: …,1.97,
2026-10-20T17:30:18.664000,Venta cruzada del día,6710f3a2c4b5d6e7f8091a2b,Diego Ramírez Peña,diego.ramirez@ejemplo.com,Coach Comercial,6719a0c1b2d3e4f5a6b7c8da,"Listo, vendí 2 fundas con mica.","¡Bien hecho, Diego! …",1.45,Si te basta con la tabla plana de mensajes, el bucle es igual con /data/messages/export; los renglones ya vienen listos para escribirse:
def fetch_all_messages(token: str, filters: dict) -> list[dict]:
"""/data/messages pagina igual: pide hasta reunir 'total'."""
rows, skip = [], 0
while True:
response = requests.get(
f"{CODY_API_URL}/data/messages/export",
params={**filters, "skip": skip, "limit": 500},
headers={"Authorization": f"Bearer {token}"},
timeout=120,
)
response.raise_for_status()
page = response.json()
rows.extend(page["conversations"])
skip += 500
if not page["conversations"] or skip >= page["total"]:
return rows
# Los renglones ya vienen planos: se escriben directo al CSV
rows = fetch_all_messages(token, {
"challenge_id": "6710f3a2c4b5d6e7f8091a2b",
"start": "2026-10-01T00:00:00Z",
"end": "2026-10-31T23:59:59Z",
})Para abrirlo en Excel sin problemas de acentos
Escribe el CSV en UTF-8 con BOM (utf-8-sig en Python o \uFEFF al inicio en JavaScript), como en el ejemplo. Excel lo abre con acentos y eñes correctos con un doble clic.
¿Sin código?
En Power Automate, Make, Zapier o n8n usa el módulo de solicitud HTTP con los mismos datos de los ejemplos cURL, un ciclo que aumente skip de 500 en 500 y el conector de Excel o Google Sheets para escribir los renglones. Guarda la credencial en el almacén de secretos de la herramienta.
13 · Probar
Pruébalo antes en la documentación interactiva
Antes de automatizar, prueba tus filtros desde el navegador y mira la respuesta real.
Autorízate con tu access token
Abre api.public.cody-tech.com/api/docs y haz clic en Authorize. En Value pega el access token (sin la palabra «Bearer»), haz clic en Authorize y cierra con Close.

El token de la captura es de ejemplo.
Abre la consulta y escribe tus filtros
En el grupo data, abre GET /data/threads y haz clic en Try it out. Escribe tu challenge_id y cualquier otro filtro que quieras probar; deja vacíos los demás.

- 1. challenge_id: el
idde la misión que obtuviste de/gamification-challenge/list. - 2. date_from / date_to: días completos en formato
AAAA-MM-DD. - 3. user_ids: IDs separados por comas, máximo 100.
Ejecuta y revisa la respuesta
Ajusta limit (para probar, 10 basta) y haz clic en Execute. Abajo verás la respuesta con el mismo formato que los ejemplos de esta guía, y el comando cURL equivalente para llevarlo a tu script.

14 · Si algo falla
Errores comunes y cómo resolverlos
La respuesta siempre explica el problema en el campo `detail`.
| Código | Cuándo pasa | Qué hacer |
|---|---|---|
400 | Fechas invertidas (date_from después de date_to, start después de end), fecha con formato inválido, más de 100 user_ids o un ID mal escrito. | Lee detail: dice exactamente qué filtro corregir. |
401 | Token ausente, inválido o vencido (Token expired). | Renueva el access token y reintenta una vez. |
403 | La credencial no tiene permiso para consultar datos. | Pide al administrador que revise el rol de la persona en cuyo nombre actúa. |
422 | Un filtro con tipo incorrecto, por ejemplo limit=1000 o date_from=21/10/2026. | Respeta los formatos de la tabla de filtros. |
200 con lista vacía | Ningún elemento cumple el filtro. | Revisa el challenge_id, amplía las fechas o recuerda el periodo por omisión de 30 días. |
{
"detail": "date_from must be before date_to"
}15 · Lista de verificación
Antes de automatizar la exportación
Revisa estos puntos con quien construyó el proceso.
- La credencial tiene su propio nombre, actúa como un administrador y vive en un gestor de secretos, no en el código.
- El proceso renueva el access token al empezar y, ante un
401, renueva y reintenta una sola vez. - Las consultas por periodo envían siempre sus fechas (
start/endodate_from/date_to) y no dependen del periodo por omisión. user_idsviaja en un solo parámetro separado por comas, con 100 IDs como máximo.- El bucle de paginación usa
limit=500y se detiene al reunirtotalo con una página vacía. - Las conversaciones se descartan por
thread_idsi se repiten entre ejecuciones. - Las fechas se tratan como UTC al guardarlas o mostrarlas.
- Los archivos con correos se guardan con acceso restringido; los que se comparten usan
/data/messages/export.
16 · Preguntas frecuentes
Dudas comunes
Lo que más nos preguntan al exportar datos.
- ¿Puedo exportar las conversaciones de todas las misiones a la vez?
- Sí. Llama a
/data/threadssinchallenge_idy con un periodo (date_from/date_to): recibes todas las conversaciones, tengan misión o no. Cada una trae suchallenge_id(onull) para que la agrupes después. - ¿Por qué `/data/messages` no trae la respuesta del agente?
- Porque está pensada como tabla de actividad: un renglón por mensaje de las personas, con el tiempo de respuesta. Si necesitas el texto de las respuestas, usa
/data/threads, donde cada mensaje trae suanswer. - Cambié el nombre de una misión. ¿Qué nombre aparece en la exportación?
- El actual.
topic,Topicychallenge.namesiempre muestran el nombre vigente de la misión, aunque la conversación haya ocurrido antes del cambio. - ¿Aparecen las conversaciones de prueba?
- No. Las conversaciones marcadas como de prueba (
test_mode: true) quedan fuera, a menos que envíesinclude_test_mode=true. - ¿Cada cuánto puedo correr la exportación?
- Las veces que necesites, pero una exportación incremental diaria (con
created_from) suele bastar y es mucho más ligera que descargar todo el historial cada vez.
¿Necesitas ayuda?
Si una exportación responde algo distinto a lo que describe esta guía, escríbenos con la consulta que hiciste (sin el token), la hora aproximada y el `detail` de la respuesta.
El equipo de Cody