Enviar SMS via API

Resumen

La API de WhatsBoost ofrece dos endpoints para el envio de SMS:

Dos modos de envio

Cada endpoint soporta dos modos de envio fundamentalmente diferentes. Debes elegir uno en cada peticion mediante el parametro mode:

Envio individual — POST /api/send/sms

Envia un unico mensaje SMS a un destinatario. La URL completa del endpoint es:

POST //whatsboost.netapi/send/sms

Parametros

Spintax: variaciones automaticas de texto

El sistema soporta spintax, una sintaxis que permite definir variantes de texto separadas por el caracter | dentro de llaves. El sistema elige una variante aleatoria en cada envio, lo que hace que cada mensaje sea ligeramente diferente. Esto es util para evitar filtros de spam y para personalizar comunicaciones.

Formato de numero de telefono (E.164)

El parametro phone debe contener el numero en formato internacional, incluyendo el codigo de pais. No incluyas el signo +, espacios ni guiones. El sistema valida automaticamente que sea un numero de telefono movil valido.

Limites del mensaje y moderacion IA

El sistema aplica validaciones automaticas al contenido del mensaje:

• Longitud minima: El mensaje debe tener al menos la cantidad minima de caracteres configurada por el administrador del sistema.
• Longitud maxima: Si hay un limite maximo configurado (mayor a 0), los mensajes que lo excedan seran rechazados con un error 400.
• Moderacion con IA: Si la moderacion automatica esta activada en el sistema, el contenido del mensaje sera analizado antes del envio. Los mensajes con contenido inapropiado seran rechazados con un error 400 y se registraran en el log de moderacion.

Ejemplo de envio individual

# Envio con modo dispositivo Android
curl -X POST //whatsboost.netapi/send/sms \
  -d "secret=TU_API_KEY" \
  -d "phone=34612345678" \
  -d "message=Hola, tu pedido #1234 esta listo para recoger." \
  -d "mode=devices" \
  -d "device=TU_DEVICE_ID" \
  -d "sim=1" \
  -d "priority=1"

# Envio con modo creditos/pasarela
curl -X POST //whatsboost.netapi/send/sms \
  -d "secret=TU_API_KEY" \
  -d "phone=34612345678" \
  -d "message=Hola, tu pedido #1234 esta listo para recoger." \
  -d "mode=credits" \
  -d "gateway=1"

<?php
$apiKey  = getenv("WHATSBOOST_API_KEY");
$baseUrl = "//whatsboost.netapi/send/sms";

// --- Modo dispositivo ---
$params = [
    "secret"   => $apiKey,
    "phone"    => "34612345678",
    "message"  => "Hola, tu pedido #1234 esta listo para recoger.",
    "mode"     => "devices",
    "device"   => "TU_DEVICE_ID",
    "sim"      => 1,
    "priority" => 1
];

$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, $baseUrl);
curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_POSTFIELDS, http_build_query($params));
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);

$response = curl_exec($ch);
$httpCode = curl_getinfo($ch, CURLINFO_HTTP_CODE);
curl_close($ch);

$data = json_decode($response, true);

if ($httpCode === 200) {
    echo "SMS enviado. ID: " . $data["data"]["messageId"];
} else {
    echo "Error ({$httpCode}): " . $data["message"];
}

const API_KEY  = process.env.WHATSBOOST_API_KEY;
const BASE_URL = "//whatsboost.netapi/send/sms";

// --- Modo dispositivo ---
const params = new URLSearchParams({
    secret:   API_KEY,
    phone:    "34612345678",
    message:  "Hola, tu pedido #1234 esta listo para recoger.",
    mode:     "devices",
    device:   "TU_DEVICE_ID",
    sim:      "1",
    priority: "1"
});

const response = await fetch(BASE_URL, {
    method: "POST",
    headers: { "Content-Type": "application/x-www-form-urlencoded" },
    body: params
});

const data = await response.json();

if (response.ok) {
    console.log("SMS enviado. ID:", data.data.messageId);
} else {
    console.error("Error (" + response.status + "):", data.message);
}

import os
import requests

API_KEY  = os.environ["WHATSBOOST_API_KEY"]
BASE_URL = "//whatsboost.netapi/send/sms"

# --- Modo dispositivo ---
params = {
    "secret":   API_KEY,
    "phone":    "34612345678",
    "message":  "Hola, tu pedido #1234 esta listo para recoger.",
    "mode":     "devices",
    "device":   "TU_DEVICE_ID",
    "sim":      1,
    "priority": 1
}

response = requests.post(BASE_URL, data=params)
data = response.json()

if response.status_code == 200:
    print("SMS enviado. ID:", data["data"]["messageId"])
else:
    print("Error (" + str(response.status_code) + "):", data["message"])

Respuesta exitosa (envio individual)

{
    "status": 200,
    "message": "Message has been queued for sending!",
    "data": {
        "messageId": 48291
    }
}

El campo messageId es un identificador unico que puedes usar posteriormente para consultar el estado del mensaje con el endpoint /api/get/message.

Envio masivo — POST /api/send/sms.bulk

Envia SMS a multiples destinatarios de forma simultanea, creando una campana que puedes monitorizar y controlar desde el Dashboard o via API. La URL completa del endpoint es:

POST //whatsboost.netapi/send/sms.bulk

Parametros

Variables de plantilla para mensajes masivos

En el envio masivo, puedes usar variables dinamicas que se reemplazan automaticamente con los datos de cada contacto. Esto permite personalizar cada mensaje individual dentro de la campana:

Ejemplo de mensaje con variables y spintax:

{Hola|Buenos dias} {{contact.name}}, te recordamos tu cita del {{date.now}}.
Grupo: {{group.name}}. Responde STOP para darte de baja.

Ejemplo de envio masivo

# Envio masivo por numeros directos (modo dispositivo)
curl -X POST //whatsboost.netapi/send/sms.bulk \
  -d "secret=TU_API_KEY" \
  -d "campaign=Promo Verano 2026" \
  -d "message={Hola|Hey} {{contact.name}}, aprovecha un 20%% de descuento hoy." \
  -d "mode=devices" \
  -d "device=TU_DEVICE_ID" \
  -d "sim=1" \
  -d "priority=2" \
  -d "numbers=34612345678,34698765432,5215512345678"

# Envio masivo por grupos (modo creditos)
curl -X POST //whatsboost.netapi/send/sms.bulk \
  -d "secret=TU_API_KEY" \
  -d "campaign=Recordatorio Citas Marzo" \
  -d "message=Hola {{contact.name}}, recuerda tu cita de manana." \
  -d "mode=credits" \
  -d "gateway=1" \
  -d "groups=5,12"

<?php
$apiKey  = getenv("WHATSBOOST_API_KEY");
$baseUrl = "//whatsboost.netapi/send/sms.bulk";

$params = [
    "secret"   => $apiKey,
    "campaign"  => "Promo Verano 2026",
    "message"  => "{Hola|Hey} {{contact.name}}, aprovecha un 20% hoy.",
    "mode"     => "devices",
    "device"   => "TU_DEVICE_ID",
    "sim"      => 1,
    "priority" => 2,
    "numbers"  => "34612345678,34698765432,5215512345678"
];

$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, $baseUrl);
curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_POSTFIELDS, http_build_query($params));
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);

$response = curl_exec($ch);
$httpCode = curl_getinfo($ch, CURLINFO_HTTP_CODE);
curl_close($ch);

$data = json_decode($response, true);

if ($httpCode === 200) {
    echo "Campana creada: " . $data["message"];
} else {
    echo "Error ({$httpCode}): " . $data["message"];
}

const API_KEY  = process.env.WHATSBOOST_API_KEY;
const BASE_URL = "//whatsboost.netapi/send/sms.bulk";

const params = new URLSearchParams({
    secret:   API_KEY,
    campaign: "Promo Verano 2026",
    message:  "{Hola|Hey} {{contact.name}}, aprovecha un 20% hoy.",
    mode:     "devices",
    device:   "TU_DEVICE_ID",
    sim:      "1",
    priority: "2",
    numbers:  "34612345678,34698765432,5215512345678"
});

const response = await fetch(BASE_URL, {
    method: "POST",
    headers: { "Content-Type": "application/x-www-form-urlencoded" },
    body: params
});

const data = await response.json();

if (response.ok) {
    console.log("Campana creada:", data.message);
} else {
    console.error("Error (" + response.status + "):", data.message);
}

import os
import requests

API_KEY  = os.environ["WHATSBOOST_API_KEY"]
BASE_URL = "//whatsboost.netapi/send/sms.bulk"

params = {
    "secret":   API_KEY,
    "campaign":  "Promo Verano 2026",
    "message":  "{Hola|Hey} {{contact.name}}, aprovecha un 20% hoy.",
    "mode":     "devices",
    "device":   "TU_DEVICE_ID",
    "sim":      1,
    "priority": 2,
    "numbers":  "34612345678,34698765432,5215512345678"
}

response = requests.post(BASE_URL, data=params)
data = response.json()

if response.status_code == 200:
    print("Campana creada:", data["message"])
else:
    print("Error (" + str(response.status_code) + "):", data["message"])

Respuesta exitosa (envio masivo)

{
    "status": 200,
    "message": "Bulk messages has been queued for sending!"
}

A diferencia del envio individual, la respuesta masiva no incluye un messageId por cada mensaje. Se crea una campana que puedes consultar con el endpoint /api/get/sms.campaigns y ver el progreso de envio de cada mensaje individual.

Controlar campanas de forma remota

Una vez creada una campana masiva, puedes pausarla y reanudarla de forma remota sin necesidad de acceder al Dashboard. Esto es util para automatizaciones que necesitan detener temporalmente el envio (por ejemplo, fuera de horario comercial).

Reanudar campana — POST /api/remote/start.sms

Reanuda una campana SMS que esta actualmente pausada. Requiere el permiso start_sms_campaign.

curl -X POST //whatsboost.netapi/remote/start.sms \
  -d "secret=TU_API_KEY" \
  -d "campaign=142"

Respuesta:

{
    "status": 200,
    "message": "SMS campaign has been resumed!"
}

Pausar campana — POST /api/remote/stop.sms

Pausa una campana SMS que esta actualmente activa/en proceso. Requiere el permiso stop_sms_campaign. Los mensajes que ya estan en cola en el dispositivo podrian seguir enviandose hasta que la app procese la senal de pausa.

curl -X POST //whatsboost.netapi/remote/stop.sms \
  -d "secret=TU_API_KEY" \
  -d "campaign=142"

Respuesta:

{
    "status": 200,
    "message": "SMS campaign has been paused!"
}

Flujo completo de envio

Comprender el ciclo de vida de un SMS te ayudara a depurar problemas y a entender los estados que veras en el Dashboard y en los webhooks.

Modo devices (dispositivo Android)

1. Peticion API: Tu aplicacion envia la solicitud POST con los parametros requeridos.
2. Validacion: El servidor valida la API Key, los permisos, el formato del numero, la longitud del mensaje, la moderacion IA, y la cuota de tu suscripcion.
3. Cola de envio: El mensaje se encola con estado pending (1). Si la prioridad es alta (1), el dispositivo lo procesara de inmediato.
4. Push al dispositivo: El servidor envia una notificacion push (FCM) al dispositivo Android para que recoja los mensajes pendientes.
5. Envio desde SIM: La app Android en tu telefono lee los mensajes pendientes y los envia uno a uno a traves de la SIM seleccionada, como un SMS convencional.
6. Confirmacion: El dispositivo reporta al servidor si el mensaje fue enviado correctamente, entregado al destinatario o si fallo. El estado se actualiza y, si tienes webhooks configurados, se dispara una notificacion.

Modo credits (pasarela SMS)

1. Peticion API: Tu aplicacion envia la solicitud POST.
2. Validacion: Se validan las credenciales, permisos, formato del numero y contenido del mensaje.
3. Calculo de coste: El sistema determina el precio del mensaje segun el pais destino y las tarifas de la pasarela seleccionada. Si no tienes suficientes creditos, se rechaza con error 403.
4. Envio via pasarela: El mensaje se envia instantaneamente a traves de la pasarela SMS configurada (Twilio, Vonage, etc.) o a traves del dispositivo global del partner.
5. Descuento de creditos: Si el envio es exitoso, se descuenta el coste de tu saldo de creditos.
6. Callback / Webhook: Si la pasarela soporta callbacks de estado de entrega, el estado se actualiza cuando la pasarela notifica (entregado, fallido, etc.). Los webhooks configurados se disparan en consecuencia.

Estados del mensaje

Errores comunes y solucion

Para una referencia completa de todos los codigos de error de la API, consulta la seccion Errores y estados.

Prompt para asistentes de IA

Eres un desarrollador backend experto. Necesito integrar el envio de SMS
usando la API de WhatsBoost. Estos son los detalles tecnicos:

ENVIO INDIVIDUAL:
- Endpoint: POST //whatsboost.netapi/send/sms
- Parametros obligatorios: secret (API Key), phone (E.164), message, mode
- mode=devices: requiere "device" (DID del Android). Opcional: sim (1|2), priority (1|2)
- mode=credits: requiere "gateway" (int ID o string nombre partner)
- Opcional: shortener (int, ID del acortador de URLs)
- Respuesta exitosa: {"status":200, "message":"...", "data":{"messageId":INT}}

ENVIO MASIVO:
- Endpoint: POST //whatsboost.netapi/send/sms.bulk
- Parametros adicionales: campaign (nombre), numbers (comas) y/o groups (IDs comas)
- Variables de plantilla: {{contact.name}}, {{contact.number}}, {{group.name}}, {{date.now}}, {{date.time}}
- Soporta spintax: {opcion1|opcion2|opcion3}

CONTROL DE CAMPANAS:
- POST /api/remote/start.sms (secret + campaign ID) - reanudar
- POST /api/remote/stop.sms (secret + campaign ID) - pausar

Ayudame a:
1. Crear funciones para envio individual y masivo con manejo de errores.
2. Implementar validacion de numeros E.164 antes de enviar.
3. Crear una cola de reintentos para errores transitorios (500).
4. Integrar con [MI CASO DE USO: e-commerce / CRM / chatbot / etc.]

Mi stack tecnologico es: [INDICA TU STACK AQUI]

Siguientes pasos