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.

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

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.

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"
}

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, menús 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"
            }
        }
    }
}

Observación

Permite enviar botones, listas, menús 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"
    },
    "media": {
        "has_media": false,
        "media_id": null,
        "mime_type": null
    },
    "meta": {
        "phone_number_id": "1085958094604323",
        "to_number": "5215545472988"
    },
    "payload": {}
}

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.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"
        }
    ]
}