Raphael Serafim· Publicado el 10 de septiembre de 2026· 8 min de lectura

Cómo enviar mensajes, botones, imágenes y listas por la API de WhatsApp

La API de WhatsApp envía mucho más que texto: imágenes, documentos, audio, video, ubicación, contactos, botones interactivos y menús de lista. Todos los endpoints, con ejemplos listos para copiar.

Ver como Markdown

La API de WhatsApp envía mucho más que texto: imágenes, documentos, audio, video, ubicación, contactos, botones interactivos y menús de lista — todo por peticiones HTTP a endpoints específicos. Todos siguen el mismo patrón: un POST a https://us.api-wa.me/{key}/message/<tipo> con un cuerpo JSON. El destinatario (to) es siempre el número en formato internacional, solo dígitos.

Esta guía muestra los tipos más usados, con ejemplos listos.

El formato del número

Antes de cualquier envío, el detalle que más falla en las pruebas:

País	Código	Ejemplo
México	52	`525512345678`
Argentina	54	`5491123456789`
Chile	56	`56912345678`
Colombia	57	`573001234567`

Sin +, sin espacios, sin guiones y sin el cero inicial del código de área.

Mensaje de texto

curl -X POST "https://us.api-wa.me/TU_KEY/message/text" \
  -H "Content-Type: application/json" \
  -d '{ "to": "525512345678", "text": "¡Hola! ¿En qué te puedo ayudar?" }'

Imagen y otros archivos

Se envía desde una URL pública, con leyenda opcional:

curl -X POST "https://us.api-wa.me/TU_KEY/message/image" \
  -H "Content-Type: application/json" \
  -d '{
    "to": "525512345678",
    "url": "https://ejemplo.com/foto.jpg",
    "caption": "Mira nuestro nuevo producto"
  }'

Los mismos campos valen para los demás tipos, cambiando solo el endpoint:

Archivo	Endpoint
Imagen	`/{key}/message/image`
Video	`/{key}/message/video`
Audio	`/{key}/message/audio`
Documento	`/{key}/message/document`
Ubicación	`/{key}/message/location`
Contacto	`/{key}/message/contact`

¿Necesitas enviar un archivo local en lugar de una URL? Usa las versiones en base64: /{key}/message/base64/image, /base64/audio y /base64/document.

El error número uno con archivos es la URL que exige autenticación. En tu navegador abre, porque tienes sesión; para la plataforma devuelve la página de login. Pruébala siempre en una ventana de incógnito antes de culpar al código.

Botones de respuesta rápida

Muestran opciones que el cliente toca para contestar:

curl -X POST "https://us.api-wa.me/TU_KEY/message/button_reply" \
  -H "Content-Type: application/json" \
  -d '{
    "to": "525512345678",
    "header": { "title": "Confirmación" },
    "text": "¿Confirmas tu pedido?",
    "footer": "Elige una opción",
    "buttons": [
      { "type": "quick_reply", "id": "si",  "text": "Sí" },
      { "type": "quick_reply", "id": "no",  "text": "No" }
    ]
  }'

El id es lo que vuelve en el webhook cuando la persona toca el botón. Ponle algo que tu código entienda sin adivinar: confirmar:1042 sirve mucho más que boton1.

Botones de acción

Abren una URL, llaman a un número o copian un código:

curl -X POST "https://us.api-wa.me/TU_KEY/message/button_action" \
  -H "Content-Type: application/json" \
  -d '{
    "to": "525512345678",
    "text": "Tu pedido ya está en camino",
    "buttons": [
      { "type": "url",  "text": "Rastrear", "url": "https://tienda.com/p/1042" },
      { "type": "call", "text": "Llamar",   "phone": "525512345678" }
    ]
  }'

Menús de lista

Cuando hay más opciones de las que caben en botones:

curl -X POST "https://us.api-wa.me/TU_KEY/message/list" \
  -H "Content-Type: application/json" \
  -d '{
    "to": "525512345678",
    "title": "Menú de atención",
    "description": "¿Con qué te ayudamos hoy?",
    "buttonText": "Ver opciones",
    "sections": [{
      "title": "Pedidos",
      "rows": [
        { "id": "estado",  "title": "Estado de mi pedido" },
        { "id": "cambio",  "title": "Cambios y devoluciones" }
      ]
    }, {
      "title": "Otros",
      "rows": [
        { "id": "humano",  "title": "Hablar con una persona" }
      ]
    }]
  }'

Una lista bien armada reemplaza buena parte de un bot: el cliente elige, tu código recibe un id fijo y no tienes que interpretar texto libre.

Los tres canales, el mismo envío

Los endpoints aceptan el campo provider. Sin él va a WhatsApp; con instagram o messenger, el mismo código envía al Direct de Instagram o a Messenger — porque es la misma instancia cubriendo los tres canales.

-d '{ "to": "IG_USER_ID", "text": "¡Hola!", "provider": "instagram" }'

Con SDK, más corto

En PHP:

$wa->message->sendText($to, "¡Hola!");
$wa->message->sendImage($to, 'https://ejemplo.com/foto.jpg', 'Nuevo producto');

En JavaScript o TypeScript:

await wa.message.send({ type: TypeMessage.TEXT, body: { to, text: '¡Hola!' } });

Los detalles están en el SDK de PHP y en el SDK de JavaScript y TypeScript.

Antes de pasar a producción

Enviar es la parte fácil. Lo que decide si el módulo aguanta es el otro lado: recibir la respuesta. Si el webhook no te está llegando, las 7 causas y la prueba de 30 segundos resuelven casi todos los casos.

Y si vas a enviar a mucha gente, la cola con límite de ritmo es lo que evita que un bucle for te queme el número.

¿Listo para automatizar tu WhatsApp?

Crea tu cuenta gratis y empieza a enviar mensajes por la API en minutos.

Empezar gratis

Preguntas frecuentes

¿Cómo envío un mensaje de texto por la API de WhatsApp?+

Con un POST a /{key}/message/text y un cuerpo JSON con 'to', el número en formato internacional solo con dígitos, y 'text'. Por ejemplo: { "to": "525512345678", "text": "¡Hola!" }.

¿Cómo envío botones por la API de WhatsApp?+

Hay dos endpoints. /{key}/message/button_reply crea botones de respuesta rápida, que el cliente toca para contestar. /{key}/message/button_action crea botones de acción: abrir una URL, llamar a un número o copiar un código.

¿Cómo envío una imagen o un documento?+

Para imagen, con /{key}/message/image, indicando 'to', 'url' con un enlace público y 'caption' opcional. Para documento, audio y video existen endpoints equivalentes. También hay versiones en base64 cuando el archivo es local y no tiene URL pública.

¿Se pueden enviar menús de lista?+

Sí. El endpoint /{key}/message/list envía un mensaje de lista con título, descripción, texto del botón y secciones con opciones — es lo más práctico para armar un menú de atención sin escribir un bot.

¿Por qué mi imagen no llega?+

Casi siempre es la URL. Debe ser pública y accesible sin autenticación: si en tu navegador abre porque tienes sesión iniciada, para la plataforma devolverá la página de login en lugar del archivo. Pruébala siempre en una ventana de incógnito.