WhatsApp

Envío de mensajes de WhatsApp desde tu propia línea, conectada escaneando un QR desde el panel: texto, imagen, video, audio y documentos. Sin trámites de Meta ni plantillas. Guía completa en WhatsApp.

Este canal es para mensajes transaccionales: uno a uno, derivados de una acción del usuario (confirmaciones, avisos, recibos, respuestas). La regla práctica: si disparas dos mensajes simultáneos, ya es masivo; promociones, cobranza y recordatorios en lote cuentan como masivo aunque el texto cambie. WhatsApp puede restringir tu línea; para volumen usa SMS Masivos.

¿Envías códigos de verificación, login o 2FA por WhatsApp? Usa Verificación OTP (POST /v2/otp con channel: "whatsapp"): sale por la integración oficial de SMS Masivos, sin instance_id, sin cuenta de WhatsApp Business ni verificación de Meta, y la API genera y valida el código por ti.

El envío sale desde una instancia de WhatsApp vinculada a tu cuenta, que debe existir, estar conectada y permanecer operativa. Cada instancia se identifica con su instance_id.

Enviar WhatsApp
POST /whatsapp/send
Enviar WhatsApp
GET /whatsapp/send

Enviar WhatsApp

POST https://api.smsmasivos.com.mx/whatsapp/send
Envía un mensaje de WhatsApp. Soporta texto, imagen, video, audio y documentos

Para códigos de verificación o 2FA no necesitas instancia: POST /v2/otp con channel: "whatsapp" envía por la integración oficial de SMS Masivos, sin instance_id ni cuenta de Meta, y la API genera y valida el código por ti.

Para los tipos multimedia (image, video, audio, document), el campo message contiene la URL del archivo. Esa URL debe usar HTTPS, ser accesible públicamente desde Internet sin autenticación y permanecer disponible mientras se procesa el envío. El caption agrega un texto descriptivo al medio.

Este canal es para mensajes transaccionales: uno a uno, derivados de una acción del usuario. Si disparas dos mensajes simultáneos, ya es masivo (promociones y cobranza incluidas) y WhatsApp puede restringir tu línea; para volumen usa SMS Masivos. La instancia de WhatsApp (instance_id) debe estar conectada y operativa al momento del envío; se conecta desde el panel escaneando un QR (guía).

Cuerpo de la solicitud
instance_idstringrequerido
Identificador de la instancia de WhatsApp vinculada a tu cuenta. La instancia debe existir y estar activa.
numberstringrequerido
Número de teléfono destino de 10 dígitos, sin código de país. Actualmente el envío está disponible para números de México (código de país 52).
messagestringrequerido
Contenido del mensaje (máximo 1000 caracteres). Para mensajes multimedia, es la URL pública HTTPS del archivo; la URL debe terminar con la extensión del archivo, sin parámetros adicionales.
typeenumopcional

Tipo de mensaje. Extensiones aceptadas por tipo:

  • image: jpg, jpeg, png, svg, webp
  • video: mp4
  • audio: ogg, amr, 3gp, aac, mpeg
  • document: pdf, doc, docx, pptx, xlsx, xls, csv
textimagevideoaudiodocument
country_codestringopcional
Código de país (por defecto 52). Actualmente solo se admite 52 (México).
find_country_codeenumopcional
Con valor 1, el código de país se extrae del propio número en lugar de tomarse de country_code.01
datestringopcional
Fecha de programación para envío diferido (formato YYYY-MM-DD HH:MM:SS). Debe ser futura.
namestringopcional
Nombre del contacto
captionstringopcional
Texto que acompaña al archivo multimedia (imagen, video, audio o documento). Máximo 1000 caracteres. No aplica para mensajes de texto.
read_confirmationobjectopcional
Configuración de confirmación de lectura por URL.

Además de los errores globales de autenticación (auth_*, ver Errores y límites), este endpoint puede responder:

Códigos de error

CódigoCuándo ocurreQué hacer
whatsapp_04 / whatsapp_08instance_id ausente, o la instancia no existe o está inactiva.Verifica el identificador y el estado de tu instancia en el panel.
whatsapp_05 / whatsapp_06 / whatsapp_07type, message o number ausentes o inválidos.Revisa los campos obligatorios.
whatsapp_22 / whatsapp_35Código de país ausente o no soportado.Actualmente solo se admite México (52).
whatsapp_23Número con formato incorrecto.Envía 10 dígitos sin código de país.
whatsapp_24 / whatsapp_29Fecha programada en el pasado o con formato inválido.Usa YYYY-MM-DD HH:MM:SS futuro.
whatsapp_28 / whatsapp_38message o caption de más de 1000 caracteres.Acorta el texto.
whatsapp_37URL multimedia inválida o con extensión no permitida.La URL debe ser pública y terminar en la extensión del archivo, sin query string.
sms_07Créditos insuficientes.Consulta tu saldo con /credits/consult.

El éxito responde whatsapp_21.

curl -X POST https://api.smsmasivos.com.mx/whatsapp/send \
  -H "Content-Type: application/json" \
  -H "apikey: TU_API_KEY" \
  -d '{
    "instance_id": "instance_abc123",
    "number": "5512345678",
    "message": "Hola desde WhatsApp!",
    "type": "text"
  }'
<?php
$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, 'https://api.smsmasivos.com.mx/whatsapp/send');
curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, [
    'Content-Type: application/json',
    'apikey: ' . getenv('API_KEY')
]);
curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode([
    'instance_id' => 'instance_abc123',
    'number' => '5512345678',
    'message' => 'Hola desde WhatsApp!',
    'type' => 'text'
]));
$response = curl_exec($ch);
curl_close($ch);
echo $response;
import requests

response = requests.post(
    'https://api.smsmasivos.com.mx/whatsapp/send',
    headers={
        'Content-Type': 'application/json',
        'apikey': 'TU_API_KEY'
    },
    json={
        'instance_id': 'instance_abc123',
        'number': '5512345678',
        'message': 'Hola desde WhatsApp!',
        'type': 'text'
    }
)
print(response.json())
const response = await fetch('https://api.smsmasivos.com.mx/whatsapp/send', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'apikey': process.env.API_KEY
  },
  body: JSON.stringify({
    instance_id: 'instance_abc123',
    number: '5512345678',
    message: 'Hola desde WhatsApp!',
    type: 'text'
  })
});
const data = await response.json();
console.log(data);
const axios = require('axios');

const { data } = await axios.post(
  'https://api.smsmasivos.com.mx/whatsapp/send',
  {
    instance_id: 'instance_abc123',
    number: '5512345678',
    message: 'Hola desde WhatsApp!',
    type: 'text'
  },
  {
    headers: {
      'Content-Type': 'application/json',
      'apikey': process.env.API_KEY
    }
  }
);
console.log(data);
require 'net/http'
require 'json'

uri = URI('https://api.smsmasivos.com.mx/whatsapp/send')
http = Net::HTTP.new(uri.host, uri.port)
http.use_ssl = true

request = Net::HTTP::Post.new(uri.path, {
  'Content-Type' => 'application/json',
  'apikey' => ENV['API_KEY']
})
request.body = {
  instance_id: 'instance_abc123',
  number: '5512345678',
  message: 'Hola desde WhatsApp!',
  type: 'text'
}.to_json

response = http.request(request)
puts JSON.parse(response.body)
using var client = new HttpClient();
client.DefaultRequestHeaders.Add("apikey", "TU_API_KEY");

var payload = new
{
    instance_id = "instance_abc123",
    number = "5512345678",
    message = "Hola desde WhatsApp!",
    type = "text"
};

var response = await client.PostAsJsonAsync(
    "https://api.smsmasivos.com.mx/whatsapp/send",
    payload
);
var result = await response.Content.ReadFromJsonAsync<JsonElement>();
Console.WriteLine(result);
OkHttpClient client = new OkHttpClient();

String json = "{"
    + "\"instance_id\":\"instance_abc123\","
    + "\"number\":\"5512345678\","
    + "\"message\":\"Hola desde WhatsApp!\","
    + "\"type\":\"text\""
    + "}";

Request request = new Request.Builder()
    .url("https://api.smsmasivos.com.mx/whatsapp/send")
    .post(RequestBody.create(json, MediaType.parse("application/json")))
    .addHeader("apikey", "TU_API_KEY")
    .build();

Response response = client.newCall(request).execute();
System.out.println(response.body().string());
Response
{
  "success": true,
  "message": "message sent",
  "status": 200,
  "code": "whatsapp_21",
  "credit": 1.5,
  "reference": "abc123def456ghi789jkl",
  "id": 12345
}
{
  "success": false,
  "message": "Parámetros inválidos.",
  "status": 200,
  "code": "<string>"
}
{
  "success": false,
  "message": "API Key inválida o no existe.",
  "status": 401,
  "code": "auth_05"
}
{
  "success": false,
  "message": "Parámetros inválidos.",
  "status": 200,
  "code": "<string>"
}
{
  "success": false,
  "message": "La dirección IP no está autorizada para acceder.",
  "status": 403,
  "code": "auth_04"
}
{
  "success": false,
  "message": "Parámetros inválidos.",
  "status": 200,
  "code": "<string>"
}
{
  "error": true,
  "message": "Too many requests",
  "rate-limited": "2 minutes",
  "reason": "Bulk messages using WhatsApp is not allowed, use SMS instead."
}
{
  "success": false,
  "message": "Error interno del servidor. Contacta a soporte con el request_id.",
  "status": 200,
  "code": "server_01",
  "request_id": "550e8400-e29b-41d4-a716-446655440000"
}
{
  "success": false,
  "message": "Parámetros inválidos.",
  "status": 200,
  "code": "<string>"
}

Enviar WhatsApp

GET https://api.smsmasivos.com.mx/whatsapp/send
Envía un mensaje de WhatsApp con los parámetros en el query string. Recomendamos usar la versión POST para no exponer tu API Key en la URL.
Parámetros de consulta
instance_idstringrequerido
ID de la instancia de WhatsApp desde la cual se envía el mensaje
numberstringrequerido
Número de teléfono destino
messagestringrequerido
Contenido del mensaje o URL del archivo multimedia
typestringopcional
Tipo de mensaje: text, image, video, audio o document (por defecto: text)
country_codestringopcional
Código de país (por defecto: 52)
datestringopcional
Fecha de programación para envío diferido
captionstringopcional
Texto descriptivo del medio
curl https://api.smsmasivos.com.mx/whatsapp/send?instance_id=value&number=value&message=value
const WhatsApp = await sms.whatsapp.list({ instance_id: 'value', number: 'value', message: 'value' })
WhatsApp = sms.whatsapp.list(instance_id="value", number="value", message="value")
WhatsApp, err := client.Whatsapp.List(ctx, nil)
Response
{
  "success": true,
  "message": "message sent",
  "status": 200,
  "code": "whatsapp_21",
  "credit": 1.5,
  "reference": "abc123def456ghi789jkl",
  "id": 12345
}
{
  "success": false,
  "message": "Parámetros inválidos.",
  "status": 200,
  "code": "<string>"
}
{
  "success": false,
  "message": "API Key inválida o no existe.",
  "status": 401,
  "code": "auth_05"
}
{
  "success": false,
  "message": "Parámetros inválidos.",
  "status": 200,
  "code": "<string>"
}
{
  "success": false,
  "message": "La dirección IP no está autorizada para acceder.",
  "status": 403,
  "code": "auth_04"
}
{
  "success": false,
  "message": "Parámetros inválidos.",
  "status": 200,
  "code": "<string>"
}
{
  "error": true,
  "message": "Too many requests",
  "rate-limited": "2 minutes",
  "reason": "Bulk messages using WhatsApp is not allowed, use SMS instead."
}
{
  "success": false,
  "message": "Error interno del servidor. Contacta a soporte con el request_id.",
  "status": 200,
  "code": "server_01",
  "request_id": "550e8400-e29b-41d4-a716-446655440000"
}
{
  "success": false,
  "message": "Parámetros inválidos.",
  "status": 200,
  "code": "<string>"
}

Objeto de respuesta

Estructura de la respuesta que devuelven estos endpoints.

Atributos
successboolean
messagestring
Mensaje de estado
statusinteger
codestring
Código de respuesta
creditnumber
Créditos consumidos
referencestring
ID de referencia del mensaje
idinteger
ID del mensaje (solo cuando show_id=1)
Objeto de respuesta
{
  "success": true,
  "message": "message sent",
  "status": 200,
  "code": "whatsapp_21",
  "credit": 1.5,
  "reference": "abc123def456ghi789jkl",
  "id": 12345
}