Guia para principiantes

Si nunca has usado una API REST, esta guia es para ti. En menos de 10 minutos vas a enviar tu primer mensaje de WhatsApp.

1. Consigue tus credenciales

Necesitas 2 cosas:

1. Una cuenta en MultiMensajes — si no tienes, contactanos por WhatsApp.
2. Un numero de WhatsApp vinculado — escaneas un QR desde tu celular real y queda asociado a tu cuenta.

Una vez dentro, abre el panel y ve a Celulares. Ahi veras tu numero y una API key (algo como WA_8_a1b2c3d4e5f6). Esa es tu llave magica.

2. Envia tu primer mensaje

El endpoint mas simple es mensaje_enviar_texto. Solo necesitas 3 cosas:

• key — tu API key
• destinatario — el numero al que quieres escribir (con codigo de pais, sin el signo +)
• mensaje — el texto que quieres enviar

Opcion A: con cURL (terminal)

Si tienes Linux, Mac, o Git Bash en Windows, abre una terminal y pega esto (cambia los valores):

curl -X POST 'https://api.multimensajes.com/api/mensaje_enviar_texto.php' \
  -d 'key=WA_8_a1b2c3d4e5f6' \
  -d 'destinatario=5218711281619' \
  -d 'mensaje=Hola desde MultiMensajes'

Opcion B: con PHP

<?php
$ch = curl_init('https://api.multimensajes.com/api/mensaje_enviar_texto.php');
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_POSTFIELDS, [
    'key' => 'WA_8_a1b2c3d4e5f6',
    'destinatario' => '5218711281619',
    'mensaje' => 'Hola desde MultiMensajes'
]);
$response = curl_exec($ch);
curl_close($ch);
$data = json_decode($response, true);
print_r($data);

Opcion C: con Python

import requests

response = requests.post(
    'https://api.multimensajes.com/api/mensaje_enviar_texto.php',
    data={
        'key': 'WA_8_a1b2c3d4e5f6',
        'destinatario': '5218711281619',
        'mensaje': 'Hola desde MultiMensajes'
    },
    timeout=30
)
print(response.json())

3. Lee la respuesta

La API siempre devuelve JSON. Si todo salio bien, veras algo como:

{
  "ok": true,
  "msg_id": "a1b2c3d4e5f6...",
  "estado": "pendiente"
}

El msg_id es el identificador unico de tu mensaje. Guardalo si quieres consultar su estado despues.

Si algo salio mal, veras:

{
  "ok": false,
  "error": "Saldo insuficiente"
}

4. Verifica que llego

El mensaje pasa por 5 estados: pendiente -> en_proceso -> enviado -> entregado -> leido.

Para consultarlo, usa el endpoint mensaje_estado:

curl 'https://api.multimensajes.com/api/mensaje_estado.php?key=WA_8_a1b2c3d4e5f6&msg_id=a1b2c3d4e5f6'

5. Recibe respuestas automaticamente

Si el destinatario te responde, puedes recibir ese mensaje en tu servidor via webhook. Configura tu URL con el endpoint webhook_configurar y te llegara un POST cada vez que pase algo.

6. Enviar imagenes, audio, video y archivos

Tienes 2 opciones para cada tipo:

• Por URL publica — subes el archivo a tu server y mandas la URL. Ej: mensaje_enviar_imagen con imageUrl.
• Por base64 — envias el archivo directamente codificado en base64. Ideal cuando no tienes donde hospedar o generas el contenido dinamicamente. Ej: mensaje_enviar_imagen_base64.

Los endpoints base64 (con sufijo _base64) aceptan el contenido como data URI o base64 puro, lo guardan temporalmente (24h), y el worker lo envia a WhatsApp.

Limites: imagenes 16MB, documentos 50MB, audio 16MB, video 50MB, stickers 1MB.

Ejemplo con Python enviando una imagen base64:

import base64, requests

with open('foto.jpg', 'rb') as f:
    img_b64 = base64.b64encode(f.read()).decode()

r = requests.post(
    'https://api.multimensajes.com/api/mensaje_enviar_imagen_base64.php',
    headers={'Authorization': 'Bearer WA_8_a1b2c3d4e5f6...'},
    json={
        'destinatario': '5218711281619',
        'imageBase64': img_b64,
        'mime': 'image/jpeg',
        'caption': 'Mira esta foto',
    },
    timeout=30,
)
print(r.json())

7. Personaliza cada mensaje (proteccion anti-baneo)

WhatsApp bloquea cuentas que envian el mismo mensaje muchas veces en poco tiempo. Para protegerte a ti mismo (de bugs en tu codigo) y a tu cuenta de WhatsApp (de baneos), la API tiene 2 mecanismos automaticos:

Cola humanizada (por default)

Cuando mandas un mensaje, no se envia al instante. Se encola y un worker lo procesa en los proximos segundos, distribuyendo el trafico para que parezca mas natural. Esto reduce MUCHO el riesgo de baneo.

Si mandas 1000 mensajes con la API, no llegan 1000 a la vez: se envian ~1 cada 5 segundos.

Proteccion anti-duplicado

Si envias el mismo mensaje (mismo texto + mismo destinatario + mismo celular) 3 veces en 2 minutos, tu cuenta queda bloqueada 5 minutos para ese celular. La proteccion es por cliente y por celular: un cliente NO puede afectar a otro.

Esto evita que:

• Un while(true) { enviar() } en tu codigo mande 10,000 mensajes identicos antes de que lo detectes.
• Un bot con logica de retry mal hecha multiplique el mismo mensaje 100 veces.
• WhatsApp detecte tu cuenta como spam y te la suspenda.

Ejemplo de personalizacion

Mal (todos reciben lo mismo):

$mensaje = "Tu pedido esta listo para recoger. Gracias por tu compra.";

Bien (cada mensaje es unico):

$nombre = "Juan";
$pedido_id = "ORD-2026-004827";
$fecha = date('Y-m-d');
$mensaje = "Hola $nombre, tu pedido $pedido_id esta listo para recoger hoy $fecha. Gracias por tu compra.";

O bien, con un ID unico por envio (util para sistemas transaccionales):

$codigo_unico = bin2hex(random_bytes(4));  // 8 chars unicos
$mensaje = "Tu codigo de verificacion es: 482915 (ref: $codigo_unico)";

Como saber cuantos envios llevas

La respuesta exitosa incluye anti_dupe: { count, max: 3, window_s: 120 }. Si count llega a 3, el siguiente envio sera rechazado con HTTP 429 y tu cuenta queda bloqueada 5 minutos.

{
  "ok": true,
  "msg_id": "a1b2c3d4-...",
  "saldo": 100,
  "texto": "Mensaje encolado",
  "anti_dupe": { "count": 1, "max": 3, "window_s": 120 }
}

Modo directo (envio instantaneo)

Si tu caso de uso requiere envio instantaneo (chatbots, 2FA, alertas en tiempo real), agrega "directo": 1 al body. La API llama a WhatsApp al instante y registra el resultado en tu historial. No uses este modo para envios masivos: la cola es mas segura.

import requests

r = requests.post(
    'https://api.multimensajes.com/api/mensaje_enviar_texto.php',
    headers={'Authorization': 'Bearer WA_8_a1b2c3d4e5f6...'},
    json={
        'destinatario': '5218711281619',
        'mensaje': 'Tu codigo de verificacion es: 482915',
        'directo': 1,
    },
    timeout=10,
)
data = r.json()
# data['modo'] == 'directo' indica envio instantaneo

Siguientes pasos

• Guia para avanzados — webhooks firmados, manejo de errores, rate limits, modo directo vs cola.
• Coleccion de Postman — importa y prueba todos los endpoints visualmente.
• Todos los endpoints de mensajes — texto, imagen, documento, audio, video, sticker.