WhatsApp

Envía y recibe mensajes de WhatsApp (texto, imágenes/audio/video/documentos, ubicación, contactos, botones de respuesta y listas) desde un número vinculado a tu cuenta. Todos los endpoints van bajo /v1/whatsapp/* y usan el mismo token Authorization: Bearer que el resto de la API.

1. Vincular un número

Antes de enviar nada necesitas una cuenta con un número vinculado por QR — esto se hace una sola vez desde el panel (/mi-cuenta/whatsapp) o por API:

Crear cuenta

POST/whatsapp/cuentas

curl -X POST https://mblapirest.com/api/v1/whatsapp/cuentas \
  -H "Authorization: Bearer TU_API_TOKEN" \
  -d "phone_number=51987654321&provider=Ventas"

Generar QR y vincular

GET/whatsapp/cuentas/{id}/qr — devuelve el QR (imagen en base64) para escanear desde el WhatsApp del número. Vuelve a llamarlo si expira (los QR de WhatsApp duran ~20 segundos).

GET/whatsapp/cuentas/{id}/estado — consulta si ya quedó connected. Ideal para hacer polling cada 2-3 segundos mientras el usuario escanea.

Otras acciones sobre la cuenta

2. Enviar mensajes

Todos los endpoints de envío reciben account_id (opcional si solo tienes una cuenta vinculada — en ese caso se usa automáticamente) y devuelven {"success": true, ...} o {"success": false, "message": "..."} (HTTP 502 si el número no está conectado).

Texto

POST/whatsapp/enviar-texto

curl -X POST https://mblapirest.com/api/v1/whatsapp/enviar-texto \
  -H "Authorization: Bearer TU_API_TOKEN" \
  -d "numero=51987654321&mensaje=Hola!+tu+pedido+ya+esta+listo"

Multimedia (imagen, video, audio, documento, sticker)

POST/whatsapp/enviar-multimedia

curl -X POST https://mblapirest.com/api/v1/whatsapp/enviar-multimedia \
  -H "Authorization: Bearer TU_API_TOKEN" \
  -d "numero=51987654321&tipo=image&caption=Tu+comprobante&media_base64=/9j/4AAQSkZJRg..."

Ubicación

POST/whatsapp/enviar-ubicacion

curl -X POST https://mblapirest.com/api/v1/whatsapp/enviar-ubicacion \
  -H "Authorization: Bearer TU_API_TOKEN" \
  -d "numero=51987654321&latitud=-16.409&longitud=-71.537&nombre=Tienda+Arequipa"

Contacto

POST/whatsapp/enviar-contacto

curl -X POST https://mblapirest.com/api/v1/whatsapp/enviar-contacto \
  -H "Authorization: Bearer TU_API_TOKEN" \
  -d "numero=51987654321&contacto_nombre=Soporte+MBL&contacto_numero=51999999999"

Botones de respuesta rápida

POST/whatsapp/enviar-botones — hasta 3 botones que el contacto puede tocar en vez de escribir.

curl -X POST https://mblapirest.com/api/v1/whatsapp/enviar-botones \
  -H "Authorization: Bearer TU_API_TOKEN" -H "Content-Type: application/json" \
  -d '{
    "numero": "51987654321",
    "texto": "¿Confirmas tu cita de mañana 3pm?",
    "botones": [
      {"id": "confirmar", "texto": "Sí, confirmar"},
      {"id": "cancelar", "texto": "Cancelar"}
    ]
  }'

Listas

POST/whatsapp/enviar-lista — menú desplegable con secciones, para más de 3 opciones.

curl -X POST https://mblapirest.com/api/v1/whatsapp/enviar-lista \
  -H "Authorization: Bearer TU_API_TOKEN" -H "Content-Type: application/json" \
  -d '{
    "numero": "51987654321",
    "texto": "Elige el servicio que te interesa",
    "texto_boton": "Ver opciones",
    "secciones": [
      {"titulo": "Consultas", "filas": [
        {"id": "dni", "titulo": "Consulta DNI", "descripcion": "Validación de identidad"},
        {"id": "ruc", "titulo": "Consulta RUC", "descripcion": "Datos de empresa"}
      ]}
    ]
  }'

Marcar como leído

POST/whatsapp/marcar-leido — marca los mensajes de un contacto como leídos (doble check azul).

curl -X POST https://mblapirest.com/api/v1/whatsapp/marcar-leido \
  -H "Authorization: Bearer TU_API_TOKEN" \
  -d "numero=51987654321"

3. Funciones avanzadas

Vinculación por código, reacciones, edición/eliminación de mensajes, gestión de chats, grupos, difusión, estados, encuestas y más. Cada una requiere su propia función habilitada en la cuenta (ver tabla). Todos reciben account_id igual que los envíos básicos.

curl -X POST https://mblapirest.com/api/v1/whatsapp/reaccionar-mensaje \
  -H "Authorization: Bearer TU_API_TOKEN" \
  -d "numero=51987654321&message_id=3EB0ABC123&reaccion=%F0%9F%91%8D"

4. Recibir mensajes y descargar multimedia

Los mensajes entrantes se guardan automáticamente y quedan visibles en el panel (/mi-cuenta/whatsapp/conversaciones). Para bajar un archivo multimedia recibido por API:

GET/whatsapp/cuentas/{id}/media/{archivo}

{archivo} es el nombre de archivo que acompaña al mensaje entrante (formato id_del_mensaje.ext). Requiere que tu cuenta tenga habilitada la función "Descargar multimedia recibido".

Respuesta de error típica

{
  "success": false,
  "message": "Esta cuenta no tiene habilitado el envio de botones."
}

Última actualización: 03/09/2026