Inicio API e integraciones | Claves, endpoints y webhooks Migración del historial de tickets a Cloud Chat

Migración del historial de tickets a Cloud Chat

Última actualización el Sep 22, 2026

Al migrar desde otro helpdesk, las conversaciones antiguas no se transfieren automáticamente — quedan en la herramienta anterior. Si quieres conservarlas en Cloud Chat, mira abajo lo que tienes que entregarnos.

Lo que necesitas entregarnos

1. Bandeja de entrada lista. Asegúrate de que la migración de tu canal esté concluida y de que la bandeja de entrada esté creada y activa en Cloud Chat — solo importamos el historial después de eso (sin bandeja de entrada, no hay adónde importar).

2. El historial en formato JSON. Exporta tus conversaciones antiguas en un archivo JSON con la clave conversations_data — una lista de tickets. Cada ticket tiene:

  • Fechas del ticket: created_at (apertura) y updated_at (última actualización), en ISO 8601 (ej.: 2024-01-15T10:30:00Z).

  • contact: identifier (obligatorio, único y estable por cliente) y, opcionales, name, email, phone_number (E.164).

  • messages: cada mensaje con content (texto), message_type (incoming = cliente, outgoing = agente, activity = nota interna), created_at (ISO 8601) y private (true para nota interna).

  • custom_attributes (recomendado): la información que quieres conservar como referencia. Guarda el ID del ticket antiguo en external_helpdesk_id (trazabilidad), e incluye las tags y atributos del ticket que quieras mantener (ej.: priority, source_queue, tags). Esas tags entran como información/etiqueta de referencia en la conversación importada — no como la tag nativa que filtra en la plataforma. Dinos cuáles quieres conservar.

Ejemplo:

{
  "conversations_data": [
    {
      "contact": { "identifier": "user_6782902", "name": "John Doe", "email": "[email protected]", "phone_number": "+5511988887777" },
      "custom_attributes": { "external_helpdesk_id": "ZD-78901", "priority": "high" },
      "created_at": "2024-01-15T10:30:00Z",
      "updated_at": "2024-01-16T14:22:00Z",
      "messages": [
        { "content": "Meu pedido não chegou.", "message_type": "incoming", "created_at": "2024-01-15T10:30:00Z", "private": false },
        { "content": "Oi! Já verifiquei, sai hoje.", "message_type": "outgoing", "created_at": "2024-01-15T10:31:00Z", "private": false },
        { "content": "Cliente VIP, priorizar.", "message_type": "activity", "created_at": "2024-01-15T11:16:00Z", "private": true }
      ]
    }
  ]
}

3. Acuerda el alcance con tu contacto. Alinea con nosotros el período (todo el historial o un recorte, ej.: los últimos 12 meses), qué tags/atributos quieres conservar, y si quieres separar por canal (WhatsApp, Instagram, correo electrónico…).

4. Envía el archivo. Sube el/los archivo(s) .json a la carpeta de Google Drive que compartimos contigo — o, si prefieres, envía un enlace del archivo (Google Drive, OneDrive, el que sea). Si quieres mantener los canales separados, envía un archivo por canal (ej.: historico_whatsapp.json).

5. Empieza por una muestra. Antes del archivo completo, envía 20–50 tickets en el formato — nosotros los importamos en un ambiente de validación, tú los revisas, y solo entonces procesamos todo.

No se importa: imágenes y adjuntos. La migración es de texto (mensajes, notas internas y metadatos). Si un adjunto era esencial, incluye su enlace en el texto del mensaje.

Reglas: fechas siempre en ISO 8601 (si no puedes enviarlas en UTC, avísanos la zona horaria); identifier realmente único (dos clientes con el mismo valor se convierten en uno solo); archivo en UTF-8.

Cloud Humans hace la importación por ti

Con el archivo enviado, el equipo de Cloud Humans ejecuta la importación — importamos por lotes, respetando los límites de la plataforma, y confirmamos el resultado contigo. No necesitas tocar ninguna API ni darnos acceso a tu herramienta antigua.

¿Prefieres hacerlo por tu cuenta? Este es el paso a paso

Si tu equipo tiene una persona desarrolladora y prefiere ejecutar la importación, usa la API. Además del archivo en el formato de arriba, vas a necesitar: API Key (ver Cómo obtener tu API Key), CLOUDCHAT_DOMAIN, ACCOUNT_ID e INBOX_ID.

Endpoint

POST https://{{CLOUDCHAT_DOMAIN}}/api/v1/accounts/{{ACCOUNT_ID}}/inboxes/{{INBOX_ID}}/conversations/import
Header Valor
content-type application/json
api_access_token Tu token de API

El cuerpo es el mismo conversations_data descrito arriba.

Límites — cada solicitud acepta como máximo 10.000 tickets o 15 MB. Para volúmenes mayores, divide en varias solicitudes. El identifier del contacto es único (dedup). Para que los custom_attributes aparezcan formateados en el panel, defínelos antes en Settings → Custom Attributes (alcance: Conversation).

Dónde encontrar los IDs

CLOUDCHAT_DOMAIN

Parte de la URL al iniciar sesión en tu cuenta:

ACCOUNT_ID

En "Configurações da conta" (Configuración de la cuenta):

API_TOKEN

En https://{{CLOUDCHAT_DOMAIN}}/app/accounts/{{ACCOUNT_ID}}/profile/settings:

INBOX_ID

ID de la bandeja que recibirá los tickets. Se puede obtener en la URL de la pestaña de configuración de la bandeja de entrada:

Observaciones