Documentación API

API técnica

Esta documentación describe los endpoints disponibles actualmente en Totum Connect para el envío y recepción de mensajes mediante WhatsApp Cloud API.

La URL base para todas las solicitudes es https://totum-connect.com.

En los endpoints de envío, to es obligatorio y acepta el teléfono con lada internacional o el BSUID del contacto. Cuando no exista número telefónico, envía en to el valor recibido como contact.from_user_id en el webhook; no omitas el campo.

Si prefieres probar los endpoints de forma rápida, puedes descargar nuestra colección de Postman con ejemplos listos para importar y ejecutar desde tu cuenta.

Descargar colección Postman V3

Autenticación

Todos los endpoints requieren el header:

X-TOTUM-KEY: {totum_key_del_canal}

El totum key corresponde al canal de WhatsApp configurado en Totum Connect.

Formato de errores

Todas las respuestas de error de la API incluyen estos campos. El código HTTP y status_code siempre coinciden.

JSON

{
    "success": false,
    "message": "La solicitud no es válida.",
    "status_code": 422
}

En errores de validación también se incluye errors, con el detalle por campo. Los errores de Meta pueden incluir además response, payload o trace_id.

Endpoints Disponibles

Método	Ruta	Descripción
POST	`/api/messages/text`	Envío de texto
POST	`/api/messages/image`	Envío de imagen
POST	`/api/messages/document`	Envío de documento
POST	`/api/messages/audio`	Envío de audio
POST	`/api/messages/video`	Envío de video
POST	`/api/messages/location`	Envío de ubicación
POST	`/api/messages/interactive`	Mensajes interactivos
POST	`/api/messages/template`	Templates aprobados
GET	`/api/media/{media_id}`	Descarga de multimedia

1. Envío de Texto

Endpoint /api/messages/text

Método POST

JSON

{
    "to": "5215513447932",
    "message": "Hola desde Totum Connect"
}

to acepta el teléfono del destinatario con lada internacional o su BSUID. Si WhatsApp no proporciona un teléfono, usa el valor contact.from_user_id incluido en el webhook; conserva el campo to y coloca ahí ese identificador.

JSON con BSUID

{
    "to": "CO.1234567890123456",
    "message": "Hola desde Totum Connect usando el identificador de WhatsApp"
}

Al recibir un BSUID, Totum lo convierte al formato de destinatario que requiere Meta. El ejemplo usa un identificador ilustrativo; sustitúyelo por el from_user_id real del contacto.

2. Envío de Imagen

Endpoint /api/messages/image

Método POST

Tamaño máximo: 5 MB

JSON

{
    "to": "5215513447932",
    "image_url": "https://midominio.com/imagen.jpg",
    "caption": "Imagen de prueba"
}

3. Envío de Documento

Endpoint /api/messages/document

Método POST

Formatos soportados: PDF, DOCX, XLSX, PPTX, ZIP, TXT, CSV y más.

JSON

{
    "to": "5215513447932",
    "document_url": "https://midominio.com/archivo.pdf",
    "filename": "cotizacion.pdf",
    "caption": "Documento de prueba"
}

4. Envío de Audio

Endpoint /api/messages/audio

Método POST

Tamaño máximo: 16 MB

JSON

{
    "to": "5215513447932",
    "audio_url": "https://midominio.com/audio.mp3"
}

5. Envío de Video

Endpoint /api/messages/video

Método POST

Tamaño máximo: 16 MB

JSON

{
    "to": "5215513447932",
    "video_url": "https://midominio.com/video.mp4",
    "caption": "Video de prueba"
}

6. Envío de Ubicación

Endpoint /api/messages/location

Método POST

JSON

{
    "to": "5215513447932",
    "latitude": 19.4326,
    "longitude": -99.1332,
    "name": "Totum Connect",
    "address": "Ciudad de México"
}

7. Mensajes Interactive

Endpoint /api/messages/interactive

Método POST

Permite enviar botones, listas, CTA URL, FLOWS y otros componentes interactivos disponibles por Meta.

Ejemplo Buttons

JSON

{
    "to": "5215513447932",
    "interactive": {
        "type": "button",
        "body": {
            "text": "¿Cómo calificarías el servicio?"
        },
        "action": {
            "buttons": [
                {
                    "type": "reply",
                    "reply": {
                        "id": "excelente",
                        "title": "Excelente"
                    }
                },
                {
                    "type": "reply",
                    "reply": {
                        "id": "bueno",
                        "title": "Bueno"
                    }
                }
            ]
        }
    }
}

Ejemplo Lists

JSON

{
    "to": "5215513447932",
    "interactive": {
        "type": "list",
        "header": {
            "type": "text",
            "text": "Totum Connect"
        },
        "body": {
            "text": "Selecciona una opción"
        },
        "footer": {
            "text": "Powered by Totum"
        },
        "action": {
            "button": "Ver opciones",
            "sections": [
                {
                    "title": "Servicios",
                    "rows": [
                        {
                            "id": "ventas",
                            "title": "Ventas",
                            "description": "Hablar con ventas"
                        },
                        {
                            "id": "soporte",
                            "title": "Soporte",
                            "description": "Abrir ticket"
                        }
                    ]
                }
            ]
        }
    }
}

Ejemplo CTA URL

JSON

{
    "to": "5215513447932",
    "interactive": {
        "type": "cta_url",
        "body": {
            "text": "Visita Totum Connect"
        },
        "action": {
            "name": "cta_url",
            "parameters": {
                "display_text": "Abrir sitio",
                "url": "https://totum-connect.com"
            }
        }
    }
}

Ejemplo FLOW

Envía un Flow publicado en Meta y permite abrirlo desde WhatsApp con datos iniciales opcionales.

JSON

{
    "to": "5215513447932",
    "interactive": {
        "type": "flow",
        "body": {
            "text": "Completa este formulario"
        },
        "action": {
            "name": "flow",
            "parameters": {
                "flow_message_version": "3",
                "flow_token": "TOKEN_UNICO_DEL_FLOW",
                "flow_id": "123456789012345",
                "flow_cta": "Continuar",
                "flow_action": "navigate",
                "flow_action_payload": {
                    "screen": "INICIO",
                    "data": {
                        "nombre": "Juan"
                    }
                }
            }
        }
    }
}

flow_id debe ser el ID del Flow publicado en Meta.
flow_token debe ser único para rastrear la respuesta del usuario.
screen indica la pantalla de inicio del Flow.
data contiene las variables y sus valores iniciales para esa pantalla.
flow_action_payload es opcional y agrupa la pantalla de inicio y sus variables.

Observación

Permite enviar botones, listas, CTA URL, FLOWS y otros componentes interactivos disponibles por Meta.
Las URLs multimedia deben ser accesibles públicamente por Meta.
Totum Connect utiliza URLs temporales para descargas seguras.

8. Templates

Endpoint /api/messages/template

Método POST

Los templates deben existir y estar previamente aprobados por Meta antes de poder ser utilizados.

JSON

{
    "to": "5215513447932",
    "template": {
        "name": "pedido_listo",
        "language": {
            "code": "es_MX"
        },
        "components": [
            {
                "type": "body",
                "parameters": [
                    {
                        "type": "text",
                        "text": "Juan Carlos"
                    }
                ]
            }
        ]
    }
}

9. Webhooks y Status Events

Totum Connect procesa automáticamente eventos enviados por Meta, incluyendo mensajes entrantes y estados de mensajes salientes.

Estados

queued sent delivered read failed

10. Notas Técnicas

Todos los mensajes enviados quedan registrados.
Los archivos multimedia son validados automáticamente por tipo y tamaño.
Los MIME types se detectan automáticamente mediante la extensión del archivo.
Las URLs multimedia deben ser accesibles públicamente por Meta.
Totum Connect utiliza URLs temporales para descargas seguras.

11. Descarga de Multimedia

Este endpoint permite obtener una URL temporal segura para descargar archivos multimedia recibidos por WhatsApp, como imágenes, documentos, audios o videos. El cliente debe enviar su X-TOTUM-KEY para validar que el media_id pertenece a su canal de WhatsApp.

Endpoint /api/media/{media_id}

Método GET

Header requerido:

X-TOTUM-KEY: {token_del_canal}

Ejemplo de solicitud:

GET https://totum-connect.com/api/media/2474924186285708

Ejemplo de respuesta exitosa:

JSON

{
    "success": true,
    "media_id": "2474924186285708",
    "message_type": "image",
    "mime_type": "image/jpeg",
    "filename": null,
    "url": "https://url-temporal.com/..."
}

Posibles respuestas de error:

401 - Token requerido: no se envió el header X-TOTUM-KEY.
401 - Token inválido: la key no corresponde a ningún canal de WhatsApp.
404 - Archivo no encontrado: el media_id no existe o no pertenece al canal autenticado.
404 - Archivo aún no disponible: el archivo todavía no ha sido procesado o subido a Wasabi.

La URL devuelta es temporal y debe utilizarse dentro del tiempo de vigencia (15min). No se recomienda almacenar esta URL de forma permanente; si el cliente necesita acceder de nuevo al archivo, debe solicitar nuevamente el endpoint con el mismo media_id.

12. Webhook del Cliente

Totum Connect puede reenviar automáticamente al webhook del cliente todos los mensajes entrantes recibidos desde WhatsApp.

12.1 Headers enviados por Totum

Content-Type: application/json
User-Agent: Totum-Connect-Webhook/1.0

12.2 Payload General

JSON

{
    "totum": {
        "log_id": 123,
        "cliente_whatsapp_id": 1,
        "received_at": "2026-05-24 12:00:00"
    },
    "event": {
        "event_type": "messages",
        "direction": "inbound",
        "message_type": "text"
    },
    "message": {
        "id": "wamid.xxxxxx",
        "body": "Hola Totum",
        "timestamp": "1779604083"
    },
    "contact": {
        "name": "Juan Carlos",
        "from_number": "5215513447932",
        "from_wa_id": "5215513447932",
        "from_user_id": "CO.1234567890123456"
    },
    "media": {
        "has_media": false,
        "media_id": null,
        "mime_type": null
    },
    "meta": {
        "phone_number_id": "1085958094604323",
        "to_number": "5215545472988"
    },
    "payload": {}
}

Si WhatsApp no proporciona un teléfono, contact.from_number y contact.from_wa_id pueden venir vacíos. En ese caso usa contact.from_user_id como destinatario en el campo to de las solicitudes de envío.

12.3 Ejemplo Mensaje Texto

{
    "event": {
        "event_type": "messages",
        "direction": "inbound",
        "message_type": "text"
    },
    "message": {
        "body": "Hola, necesito soporte"
    }
}

12.4 Ejemplo Mensaje Imagen

{
    "event": {
        "event_type": "messages",
        "direction": "inbound",
        "message_type": "image"
    },
    "media": {
        "has_media": true,
        "media_id": 15,
        "mime_type": "image/jpeg"
    }
}

12.5 Ejemplo Interactive

{
    "event": {
        "event_type": "messages",
        "direction": "inbound",
        "message_type": "interactive"
    },
    "message": {
        "id": "wamid.xxxxxx"
    },
    "interactive": {
        "type": "button_reply",
        "button_reply": {
            "id": "excelente",
            "title": "Excelente"
        }
    }
}

12.5.1 Respuesta de QUICK REPLY de una plantilla

Meta envía el texto visible en button.text y el valor configurado para validar en button.payload. En el webhook de Totum, consulta el evento original dentro de payload.entry[0].changes[0].value.messages[0].button.

{
    "event": {
        "event_type": "messages",
        "direction": "inbound",
        "message_type": "button"
    },
    "message": {
        "body": "Descargar"
    },
    "payload": {
        "entry": [
            {
                "changes": [
                    {
                        "value": {
                            "messages": [
                                {
                                    "type": "button",
                                    "button": {
                                        "text": "Descargar",
                                        "payload": "RECOMENDACION ESTUDIOSABC123"
                                    }
                                }
                            ]
                        }
                    }
                ]
            }
        ]
    }
}

12.6 Descarga de Multimedia

La descarga de multimedia se detalla con mayor claridad en el punto 11, donde se explica el endpoint, el método y el uso del media_id para obtener el archivo.

GET /api/media/{media_id}

Header: X-TOTUM-KEY: xxxxxxxxx

12.7 Eventos de Estado

Totum Connect procesa automáticamente eventos enviados por Meta como sent, delivered, read y failed para mantener actualizado el estado de los mensajes salientes.

JSON

{
    "statuses": [
        {
            "id": "wamid.xxxxx",
            "status": "delivered"
        }
    ]
}