Introducción

Este documento describe los formatos de archivo soportados (JSON, XML y Excel) para cargar lotes de mensajes masivos en el sistema. Los archivos contienen una lista de mensajes con los datos necesarios para enviar mensajes de WhatsApp, incluyendo un token que identifica a tu empresa. El sistema genera automáticamente un identificador de lote (id_batch) basado en el ID del lote creado.

Formatos de Archivo Soportados

Los archivos deben estar en uno de los siguientes formatos:

• JSON: Un archivo con estructura JSON que contiene una lista de mensajes.
• XML: Un archivo XML con una lista de mensajes estructurada.
• Excel: Un archivo .xlsx con columnas que representan los campos de los mensajes.

Estructura General

Cada archivo debe contener una lista de mensajes, donde cada mensaje incluye los siguientes campos:

Notas:

• El campo id_batch no debe incluirse en el archivo, ya que se genera automáticamente como batch_{id} donde {id} es el ID del lote.
• El token se valida contra el sistema para obtener el identificador de la compañía.

Ejemplos de Archivos

JSON

Un archivo JSON debe tener una clave messages que contenga un arreglo de mensajes.

    {
        "messages": [
            {
                "token": "abc123xyz",
                "phone": "+573111111111",
                "message": "Hola, este es un mensaje de prueba",
                "type": "chat",
                "fecha_envio_programada": "2025-07-25 10:00:00"
            },
            {
                "token": "abc123xyz",
                "phone": "+573222222222",
                "type": "location",
                "title": "Ubicación de prueba",
                "latitude": 40.7128,
                "longitude": -74.0060,
                "address": "123 Main St",
                "fecha_envio_programada": "2025-07-25 10:30:00"
            },
            {
                "token": "abc123xyz",
                "phone": "+573333333333",
                "type": "poll_creation",
                "questions": "Color favorito",
                "options": ["Blanco", "Azul", "Verde"],
                "fecha_envio_programada": "2025-07-25 11:00:00"
            }
        ]
    }
                

XML

Un archivo XML debe tener un elemento raíz batch con un elemento messages que contenga elementos message.

    <batch>
        <messages>
            <message>
                <token>abc123xyz</token>
                <phone>+573111111111</phone>
                <message>Hola, este es un mensaje de prueba</message>
                <type>chat</type>
                <fecha_envio_programada>2025-07-25 10:00:00</fecha_envio_programada>
            </message>
            <message>
                <token>abc123xyz</token>
                <phone>+573222222222</phone>
                <type>location</type>
                <title>Ubicación de prueba</title>
                <latitude>40.7128</latitude>
                <longitude>-74.0060</longitude>
                <address>123 Main St</address>
                <fecha_envio_programada>2025-07-25 10:30:00</fecha_envio_programada>
            </message>
            <message>
                <token>abc123xyz</token>
                <phone>+573333333333</phone>
                <type>poll_creation</type>
                <questions>Color favorito</questions>
                <options>["Blanco", "Azul", "Verde"]</options>
                <fecha_envio_programada>2025-07-25 11:00:00</fecha_envio_programada>
            </message>
        </messages>
    </batch>
                

Excel

Un archivo Excel (.xlsx) debe tener una hoja con encabezados en la primera fila y los datos de los mensajes en las filas siguientes.

Notas para Excel:

• Los encabezados deben coincidir exactamente con los nombres de los campos (case-sensitive).
• Los campos opcionales pueden dejarse vacíos.
• El campo options debe ser un string JSON válido (por ejemplo, ["Blanco","Azul","Verde"]).

Proceso de Carga

1. Validación del Archivo: El sistema verifica que el archivo sea de tipo .json, .xml o .xlsx y no supere los 10 MB. Si el archivo no cumple con estos requisitos, se muestra un mensaje de error en la interfaz.
2. Procesamiento de Mensajes: Cada mensaje se revisa para asegurar que los campos requeridos estén completos y correctos. El token se verifica contra el sistema para identificar la empresa asociada. Si el token no es válido o no está registrado, el mensaje se marca como no procesado y se muestra un error.
3. Almacenamiento: Se crea un lote con un identificador único (batch_{id}) generado automáticamente. Los mensajes válidos se guardan en el sistema con el identificador del lote. Se registran estadísticas sobre cuántos mensajes se procesaron correctamente y cuántos tuvieron errores.
4. Retroalimentación: La interfaz muestra un resumen indicando cuántos mensajes se cargaron correctamente y cuántos no. Los errores específicos (por ejemplo, tokens inválidos o datos incorrectos) se muestran en una lista.

Notas para un Uso Correcto

• Verificación del Token: Asegúrate de que el token incluido en el archivo sea válido y esté registrado en el sistema. Este token identifica a tu empresa y debe coincidir con uno proporcionado al configurar tu cuenta. Si el token no es válido, los mensajes no se procesarán y se mostrará un error.
• Formato de la Fecha: El campo fecha_envio_programada debe especificar la fecha y hora en que deseas enviar los mensajes, usando el formato AÑO-MES-DÍA HORA:MINUTOS:SEGUNDOS (por ejemplo, 2025-07-25 10:00:00). Asegúrate de que la fecha sea correcta para evitar problemas al programar los envíos.
• Archivos con Muchos Mensajes: Si tu archivo contiene una gran cantidad de mensajes, el proceso de carga puede tomar algo de tiempo. Para agilizarlo, el sistema puede manejar los mensajes en segundo plano, pero te recomendamos contactar al soporte si planeas enviar lotes muy grandes.
• Seguridad: Para cargar archivos, debes iniciar sesión en el sistema con tu cuenta autorizada. Esto asegura que solo usuarios registrados puedan enviar mensajes.