Exportar historial

Recorré conversaciones y mensajes para construir una copia en tu sistema. Incluimos un script de Python que exporta conversaciones creadas en un período y su hilo completo a JSONL.

Descargar el ejemplo

Descargar export_history.py. Requiere Python 3.10 o posterior, sin paquetes adicionales, y las variables de entorno de la introducción.

Guardalo en tu máquina y ejecutá:

python3 export_history.py \
  --since 2026-06-01 \
  --until 2026-09-01 \
  --output crm-junio-agosto.jsonl

El intervalo es UTC: incluye el 1 de junio y excluye el 1 de septiembre. El script elige por fecha de creación de la conversación y exporta todo su hilo, incluso mensajes fuera de ese período. Para analizar mensajes enviados durante un período, también necesitás conversaciones creadas antes y filtrar cada mensaje por su fecha.

El script no sobrescribe archivos existentes ni reanuda un .partial. Elegí otro nombre al volver a ejecutarlo. Mantiene un ritmo conservador, reintenta errores temporales de lectura y conserva los mensajes por ID, incluyendo notas privadas y actividades.

1. Seleccionar conversaciones

POST .../conversations/filter?page=N devuelve hasta 25 conversaciones en payload; los contadores están en meta. Por ejemplo, para fechas posteriores al 31 de mayo y anteriores al 1 de septiembre:

curl --fail-with-body --request POST \
  "$CRM_BASE_URL/api/v1/accounts/$CRM_ACCOUNT_ID/conversations/filter?page=1" \
  --header "api_access_token: $CRM_API_TOKEN" \
  --header "Content-Type: application/json" \
  --data '{ "payload": [
    { "attribute_key": "created_at", "filter_operator": "is_greater_than",
      "values": ["2026-05-31"], "query_operator": "AND" },
    { "attribute_key": "created_at", "filter_operator": "is_less_than",
      "values": ["2026-09-01"], "query_operator": null }
  ] }'

Los filtros de fecha estándar comparan días, con > y < estrictos; no filtran por un instante con precisión de segundos. El script amplía el rango y luego aplica el intervalo UTC exacto a created_at.

Incrementá page hasta recibir payload: []. Si usás GET .../conversations?status=all&page=N, el array está en data.payload, no en payload.

2. Recorrer el hilo por ID

Para exportaciones, usá history_scan=true. Este modo ordena por ID, devuelve hasta 100 mensajes y mantiene coherencia con el cursor aunque haya mensajes importados con fechas antiguas:

curl --fail-with-body --get \
  "$CRM_BASE_URL/api/v1/accounts/$CRM_ACCOUNT_ID/conversations/4821/messages" \
  --header "api_access_token: $CRM_API_TOKEN" \
  --data-urlencode "history_scan=true"

La respuesta trae payload[]. Tomá el menor id del lote y pasalo como before en la siguiente consulta:

GET .../conversations/4821/messages?history_scan=true
GET .../conversations/4821/messages?history_scan=true&before=88190
GET .../conversations/4821/messages?history_scan=true&before=87950

Terminá cuando el array esté vacío, deduplicá por ID y ordená localmente por (created_at, id) si necesitás orden cronológico. Si un cursor no avanza, detené el proceso en lugar de repetir indefinidamente.

En modo normal, before solo devuelve hasta 20 mensajes con ID menor al cursor; after solo devuelve hasta 100 con ID mayor. Al combinar ambos, el intervalo es after <= id < before y el máximo es 1000 mensajes, ordenados por fecha ascendente. history_scan=true ignora after y conserva su límite de 100.

El modo normal devuelve 20 mensajes ordenados por fecha, pero su cursor filtra por ID. Combinar ambas cosas puede omitir mensajes importados o fechados hacia atrás. Usá history_scan=true para el recorrido completo en instalaciones que lo soportan; no asumas que una instalación anterior lo implementa solo porque acepta el parámetro.

3. Consistencia durante la exportación

La API paginada no ofrece una foto transaccional. El listado se ordena por actividad: si una conversación cambia entre páginas puede desplazarse, repetirse o quedar fuera del recorrido. Deduplicar resuelve repeticiones, pero no recupera automáticamente omisiones. Los mensajes también pueden cambiar durante la lectura.

Hacé la carga inicial en un período de baja actividad. Registrá eventos mediante webhooks antes de comenzar y reconciliá después los recursos afectados. Si necesitás una exportación exacta a un instante concreto, coordiná un procedimiento específico con el administrador.

history_revision, cuando esté disponible en la conversación, sirve para comparar si el historial cambió entre dos lecturas. No es un cursor de mensajes ni una garantía de instantánea. Si falta, volvé a leer el historial cuando necesites verificarlo.

4. Cuidar el ritmo y los datos

Los límites se comparten con el panel. El script espera al menos 1,2 segundos entre requests y no ejecuta consultas en paralelo; si la cuenta tiene mucho movimiento, reducí más el ritmo. No calcules la duración solo por cantidad de conversaciones: también depende de las páginas de mensajes y reintentos.

Los archivos incluyen contactos, notas privadas y enlaces a adjuntos. El script restringe los permisos locales del archivo a su usuario en sistemas compatibles. No publiques el export ni lo subas a un repositorio. El JSON conserva las URLs, pero no descarga los archivos adjuntos.

Otras opciones