API de MundoSMS (v3)

Índice

Integra la centralita, los SMS, las llamadas automáticas (VozPush), la verificación de números y WhatsApp de MundoSMS en tu CRM, ERP o aplicación. Es una API REST: cada cosa tiene su ruta y cada ruta, su verbo HTTP.

  • Dirección: https://api.mundosms.es/v3/ seguida de la ruta. Por ejemplo, GET https://api.mundosms.es/v3/calls.
  • Petición: en GET y DELETE, los parámetros en la query; en POST y PATCH, en un cuerpo JSON. Las credenciales, en las cabeceras Authorization: Bearer <token>, X-Timestamp y X-Signature.
  • Respuesta: siempre JSON, con su código HTTP (200 si todo fue bien), status, status_code y message, y los datos en data. Cada respuesta lleva la cabecera X-Request-Id, con la que encuentras esa petición en Logs API.
  • Fechas: hora de Madrid con milisegundos, y cada una con su gemela en ISO 8601 con zona.
  • SDK: un fichero que copias en tu proyecto, en PHP, Python o Node.js, y que firma solo.

Especificación OpenAPI 3.1 (JSON)Colección de Postman

Inicio rápido#

Tu primera llamada a la API en dos minutos.

  1. En el panel, entra en API y Soporte → Claves de API y pulsa Crear API Key: se abre su ficha. En Permisos deja «Solo consultas», en Caducidad elige «No caduca», deja activadas Firmar cada petición y Rechazar peticiones repetidas, y guarda.
  2. Copia el Token (empieza por eyJ) y, con el botón Mostrar, la clave privada (20 letras y números).
  3. Pega los dos en este script y ejecútalo en un terminal con bash, curl y openssl. Pide las cinco últimas llamadas entrantes de tu centralita:
curl (bash)
TOKEN='PEGA_AQUI_EL_TOKEN'
PRIVATE_KEY='PEGA_AQUI_LA_CLAVE_PRIVADA'
RUTA='/v3/calls?type=in&limit=5'
TS=$(date +%s)
SIG=$(printf '%s' "$TOKEN.$TS.GET $RUTA." | openssl dgst -sha256 -hmac "$PRIVATE_KEY" -binary | base64 | tr '+/' '-_' | tr -d '=\n')
curl -sS "https://api.mundosms.es$RUTA" \
  -H "Authorization: Bearer $TOKEN" \
  -H "X-Timestamp: $TS" \
  -H "X-Signature: $SIG"

Si todo va bien, la API contesta con HTTP 200 y algo así:

JSON
{
  "status": "success",
  "status_code": "0",
  "message": "5 results",
  "data": {
    "results": 5,
    "calls": [
      {
        "id": 8812345,
        "client_id": null,
        "type": "in",
        "from": "34600123456",
        "from_name": null,
        "to": "34910123456",
        "to_type": "landline",
        "state": "answered",
        "state_code": 1,
        "date_start": "2026-11-20 10:15:03.250",
        "date_start_iso": "2026-11-20T10:15:03.250+01:00",
        "date_answer": "2026-11-20 10:15:09.118",
        "date_answer_iso": "2026-11-20T10:15:09.118+01:00",
        "date_end": "2026-11-20 10:18:41.902",
        "date_end_iso": "2026-11-20T10:18:41.902+01:00",
        "duration": 213,
        "duration_ring": 6,
        "pickup_extension": "recepcion",
        "credits": 0.0,
        "credits_total": 0.0,
        "bundle_id": null,
        "callingcard_id": null,
        "parent_type": null,
        "parent_id": null
      }
    ],
    "has_more": true,
    "next_from_id": null,
    "next_cursor": null
  }
}

has_more es true y next_cursor es null porque, sin cursor ni from_datetime, el orden es desc (las últimas), que no tiene página siguiente. Para recorrer o sincronizar, usa order=asc con cursor o from_datetime (Paginación con cursor).

Si no, el message dice qué falla (lo explica Catálogo de errores). Lo más habitual al empezar: Authentication failure (la firma no casa: revisa que el token y la clave privada sean de la misma clave de API, y que firmas la ruta con su query tal cual la envías) y Signed requests must include the X-Timestamp header… (falta X-Timestamp o el reloj de tu equipo va desfasado).

Pruébalo desde esta página#

En la página de esta referencia, www.mundosms.es/api-v3, tienes un formulario para lanzar peticiones de verdad a tu cuenta sin escribir código: pegas tu token y tu clave privada, eliges una ruta de consulta y editas sus parámetros. La petición se firma en tu navegador y va directamente de tu navegador a la API. La clave privada no se envía a ningún sitio ni se guarda. Solo están las rutas que consultan (GET): ninguna envía, cambia ni borra nada.

Peticiones reales sobre tu cuenta, solo de consulta. La petición se firma en tu navegador y va directamente de tu navegador a api.mundosms.es. Tu clave privada no se envía a ningún sitio ni se guarda: ni en este navegador ni en nuestros servidores; se borra al salir de la página. Para probar, mejor una clave de solo lectura.

Rutas#

Todas las rutas de la API. Cada una enlaza a su referencia; el permiso es el que necesita la clave (ver Permisos).

Ruta Qué hace Permiso
GET /v3/calls historial de llamadas read, voip o list_voipcalls
GET /v3/calls/{type}/{id} una llamada por su id read, voip o list_voipcalls
POST /v3/calls llamar desde una extensión (click2dial) write, voip o click2dial
GET /v3/calls/missed llamadas perdidas por devolver read, voip o list_voipmissedcalls
GET /v3/calls/live llamadas en curso read, voip o list_voiplivecalls
POST /v3/calls/live/{type}/{id}/hangup colgar una llamada en curso write, voip o action_voiplivecalls
GET /v3/calls/{type}/{id}/recording grabación de una llamada read, voip o getrecording_voipcalls
GET /v3/numbers tus números read, voip o get_voipdids
GET /v3/numbers/{did} uno de tus números read, voip o get_voipdids
PATCH /v3/numbers/{did} cambiar un número write, voip o set_voipdids
GET /v3/extensions tus extensiones read, voip o get_voipextensions
GET /v3/extensions/{extension} una de tus extensiones read, voip o get_voipextensions
POST /v3/extensions crear una extensión write, voip o new_voipextensions
PATCH /v3/extensions/{extension} cambiar una extensión write, voip o set_voipextensions
GET /v3/diagrams tus diagramas read, voip, vozpush o getdiagrams_voip
GET /v3/diagrams/{id} uno de tus diagramas read, voip, vozpush o getdiagrams_voip
POST /v3/callerid-validations verificar un número para presentarlo write, voip, vozpush o callerid_validation
POST /v3/voicefiles subir una locución write, voip, vozpush o upload_voicefile
GET /v3/voicefiles/{id} descargar una locución read, voip, vozpush o get_voicefile
DELETE /v3/voicefiles/{id} borrar una locución write, voip, vozpush o delete_voicefile
POST /v3/campaigns lanzar una campaña de VozPush write, vozpush o sendcall
GET /v3/campaigns la campaña con tu referencia (client_id) read, vozpush o getreport_call
GET /v3/campaigns/{id} estado de una campaña read, vozpush o getreport_call
POST /v3/campaigns/{id}/pause pausar una campaña write, vozpush o getreport_call
POST /v3/campaigns/{id}/resume reanudarla write, vozpush o getreport_call
POST /v3/campaigns/{id}/cancel cancelarla write, vozpush o getreport_call
GET /v3/campaigns/{id}/calls/{to}/recording grabación de una llamada de VozPush read, vozpush o getrecording_vozpush
POST /v3/sms enviar SMS write, sms o sendsms
GET /v3/sms SMS enviados, uno por destinatario read, sms o getreport
POST /v3/sms/certified enviar un SMS certificado write, sms o sendsms_cert
POST /v3/sms/quote calcular el coste antes de enviar read, sms o quotesms
GET /v3/sms/replies respuestas a tus SMS read, sms o getreport
GET /v3/sms/sends varios envíos, o el de tu referencia read, sms o getreport
GET /v3/sms/sends/{id} estado de un envío read, sms o getreport
POST /v3/sms/sends/{id}/send-now enviar ya un envío programado write, sms o scheduled_sendings
POST /v3/sms/sends/{id}/cancel cancelar un envío programado write, sms o scheduled_sendings
POST /v3/numchecks comprobar un número de móvil write, numcheck o numcheck
GET /v3/whatsapp/numbers tus números de WhatsApp whatsapp o whatsapp_numbers
GET /v3/whatsapp/templates las plantillas de un número y su estado whatsapp o whatsapp_templates
POST /v3/whatsapp/messages enviar un WhatsApp whatsapp o whatsapp_send
GET /v3/whatsapp/messages/{message_id} el estado de un WhatsApp whatsapp o whatsapp_status
POST /v3/whatsapp/campaigns crear un envío masivo de WhatsApp whatsapp o whatsapp_campaign
GET /v3/whatsapp/campaigns/{campaign_id} el estado de un envío masivo whatsapp o whatsapp_campaign
POST /v3/whatsapp/campaigns/{campaign_id}/pause pausarlo whatsapp o whatsapp_campaign
POST /v3/whatsapp/campaigns/{campaign_id}/resume reanudarlo whatsapp o whatsapp_campaign
POST /v3/whatsapp/campaigns/{campaign_id}/cancel cancelarlo whatsapp o whatsapp_campaign

all vale para todas. Una ruta que no existe da 404 Route not found; una que existe con otro verbo, 405 Method not allowed con la cabecera Allow (los verbos que admite).

Autenticación y firma#

La clave de API#

Las claves se crean en el panel, en API y Soporte → Claves de API. Cada una tiene:

  • el token, que va en la cabecera Authorization: Bearer <token>. Empieza por eyJ y son tres trozos separados por puntos;
  • la clave privada (botón «Mostrar»): 20 letras y números. No se envía nunca: solo sirve para calcular la firma;
  • sus permisos (ver Permisos), su caducidad (vacía = no caduca), su lista de IPs (vacía = cualquiera) y si exige firma y ts.

Una clave nueva nace con permiso de lectura, firma con ts y una hora de caducidad, a propósito: para una prueba rápida basta, y no se queda abierta para siempre. Para una integración, dale los permisos que necesite y deja vacía la caducidad. Quitarle la firma pide una confirmación en el panel: sin firma, quien vea el token puede usarlo.

La petición#

Una consulta (GET): los parámetros en la query.

HTTP
GET /v3/calls?type=in&from_datetime=2026-11-01 HTTP/1.1
Host: api.mundosms.es
Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJqdGkiOiIxMjMifQ.c2lnbmF0dXJh
X-Timestamp: 1795100000
X-Signature: 3bQkX0m7y6l9Jx3f0cQyq8l2m5Gk1Vb0wzq6c8u4t1E

Un envío o un cambio (POST, PATCH): los datos en un cuerpo JSON.

HTTP
POST /v3/sms HTTP/1.1
Host: api.mundosms.es
Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJqdGkiOiIxMjMifQ.c2lnbmF0dXJh
X-Timestamp: 1795100000
X-Signature: Qk9JRk5wM2xKZzZ2b0xUcXBZcHN5Z3BtQ1VxQmZ3ZE0
Content-Type: application/json

{"to":"34600123456","text":"Tu cita es mañana a las 10:00","from":"MiClinica","client_id":"cita-4521"}

Las reglas, que la API comprueba:

  • Cada cosa va en un solo sitio. En GET y DELETE no se admite cuerpo (400 Body not allowed); en POST y PATCH, no se admite query (400 Query not allowed) y el cuerpo tiene que ser un objeto JSON (400 Body not valid).
  • Lo que va en la ruta ({id}, {did}…) manda: si lo repites en la query o en el cuerpo con otro valor, 400 Parameter <nombre> not valid.
  • Las credenciales van siempre en las cabeceras. No pongas el token ni la firma en la URL: lo que va en una URL acaba en registros (de tu sistema, de proxies, del navegador) y en las vistas previas de chats y correos, que abren el enlace y repiten la petición.

La firma#

Texto
X-Signature = base64url( HMAC-SHA256( clave_privada,
                token + "." + X-Timestamp + "." + MÉTODO + " " + ruta_con_query + "." + cuerpo ) )      # sin relleno "="
  • MÉTODO en mayúsculas (GET, POST, PATCH, DELETE) y un espacio.
  • ruta_con_query: desde /v3/, con la query tal cual la envías (mismo orden y mismos escapes): /v3/calls?type=in&from_datetime=2026-11-01. Sin query, solo la ruta.
  • cuerpo: el texto exacto del JSON que envías. En GET y DELETE, vacío: la cadena acaba en ..
  • X-Timestamp: la hora actual en segundos (epoch Unix) o en milisegundos, a menos de 5 minutos de la de nuestro servidor.
  • base64url es base64 con - en vez de +, _ en vez de / y sin los = del final. La clave privada es la clave del HMAC, tal cual (como texto, no decodificada).

Así la firma cubre qué pides (verbo y ruta), con qué datos (query y cuerpo) y cuándo: una petición firmada no sirve para otra ruta ni para otros datos, y caduca a los 5 minutos.

Hay tres modos, que se eligen en la clave:

Modo En «Claves de API» Qué exige
firma con ts (recomendado, el de una clave nueva) «Firmar cada petición» y «Rechazar peticiones repetidas» la firma y X-Timestamp, y cada petición firmada vale una sola vez: repetida, 409 Duplicated request
firma «Firmar cada petición» la firma y X-Timestamp (a menos de 5 minutos). En las rutas de WhatsApp, además, cada petición firmada vale una sola vez, como con ts
sin firma «Firmar cada petición» desactivado solo el token. Desaconsejado: quien vea el token puede usarlo

Para reintentar una petición firmada con ts, fírmala de nuevo con un X-Timestamp nuevo (ver Reintentos seguros). Con milisegundos en X-Timestamp, dos peticiones iguales seguidas no chocan.

Ejemplos completos#

Los cuatro definen la misma función, mundosms(método, ruta, datos), que firma y envía cualquier petición (en GET y DELETE pone los datos en la query y en POST y PATCH, en el cuerpo), y piden las llamadas entrantes de hoy. Valen igual con una clave que no exija firma (deja la clave privada vacía). Si prefieres no escribir esto, el SDK lo hace por ti.

curl (bash)
#!/bin/bash
# API de MundoSMS con bash, curl y openssl
TOKEN='PEGA_AQUI_EL_TOKEN'               # Claves de API: «Token» (empieza por eyJ)
PRIVATE_KEY='PEGA_AQUI_LA_CLAVE_PRIVADA' # «Mostrar»; déjala vacía ('') si la clave no exige firma

# mundosms MÉTODO RUTA [JSON]: firma y escribe la respuesta (con el código HTTP en la última línea). En GET y DELETE, la
# query va ya en la RUTA (escapada); en POST y PATCH, el JSON es el cuerpo
mundosms() {
  local metodo="$1" ruta="$2" cuerpo="${3:-}" ts firma=() datos=()
  ts=$(date +%s)
  if [ -n "$PRIVATE_KEY" ]; then
    firma=(-H "X-Signature: $(printf '%s' "$TOKEN.$ts.$metodo $ruta.$cuerpo" | openssl dgst -sha256 -hmac "$PRIVATE_KEY" -binary | base64 | tr '+/' '-_' | tr -d '=\n')")
  fi
  [ -n "$cuerpo" ] && datos=(-H 'Content-Type: application/json' --data-raw "$cuerpo")
  curl -sS -X "$metodo" "https://api.mundosms.es$ruta" \
    -H "Authorization: Bearer $TOKEN" -H "X-Timestamp: $ts" "${firma[@]}" "${datos[@]}" -w '\nHTTP %{http_code}\n'
}

mundosms GET "/v3/calls?type=in&from_datetime=$(date +%F)"
PHP
<?php
// API de MundoSMS con PHP 7.4 o superior y la extensión curl
$token       = "PEGA_AQUI_EL_TOKEN";
$private_key = "PEGA_AQUI_LA_CLAVE_PRIVADA";   // "" si la clave no exige firma

function mundosms($metodo, $ruta, array $datos, $token, $private_key = "") {
    $query = ""; $cuerpo = "";
    if ($metodo === "GET" || $metodo === "DELETE") {
        foreach ($datos as $k => $v) {                       // listas separadas por comas; sí/no como true/false (los null, fuera)
            if (is_array($v)) $datos[$k] = implode(",", $v);
            elseif (is_bool($v)) $datos[$k] = $v ? "true" : "false";
        }
        if ($datos) $query = "?" . http_build_query($datos, "", "&", PHP_QUERY_RFC3986);
    } elseif ($datos) {
        $cuerpo = json_encode($datos, JSON_UNESCAPED_UNICODE | JSON_UNESCAPED_SLASHES);   // se firma y se envía EXACTAMENTE esto
    }
    $ts = (string) time();
    $cabeceras = ["Authorization: Bearer " . $token, "X-Timestamp: " . $ts];
    if ($private_key !== "") {
        $firmado = $token . "." . $ts . "." . $metodo . " " . $ruta . $query . "." . $cuerpo;
        $cabeceras[] = "X-Signature: " . rtrim(strtr(base64_encode(hash_hmac("sha256", $firmado, $private_key, true)), "+/", "-_"), "=");
    }
    if ($cuerpo !== "") $cabeceras[] = "Content-Type: application/json";
    $ch = curl_init("https://api.mundosms.es" . $ruta . $query);
    curl_setopt_array($ch, [
        CURLOPT_CUSTOMREQUEST => $metodo, CURLOPT_RETURNTRANSFER => true, CURLOPT_HTTPHEADER => $cabeceras, CURLOPT_TIMEOUT => 60,
    ]);
    if ($cuerpo !== "") curl_setopt($ch, CURLOPT_POSTFIELDS, $cuerpo);
    $respuesta = curl_exec($ch);
    $http = curl_getinfo($ch, CURLINFO_RESPONSE_CODE);
    if ($respuesta === false) return ["http" => 0, "status" => "error", "message" => "No se pudo conectar: " . curl_error($ch)];
    $r = json_decode($respuesta, true);
    return is_array($r) ? ["http" => $http] + $r : ["http" => $http, "status" => "error", "status_code" => "2", "message" => "Respuesta inesperada"];
}

$r = mundosms("GET", "/v3/calls", ["type" => "in", "from_datetime" => date("Y-m-d")], $token, $private_key);
if ($r["status"] === "success") foreach ($r["data"]["calls"] as $c) echo $c["date_start"], " ", $c["from"], " ", $c["state"], "\n";
else echo "Error HTTP ", $r["http"], ": ", $r["message"], "\n";
Python
# API de MundoSMS con Python 3.8 o superior, sin librerías externas
import base64, hashlib, hmac, json, time, urllib.error, urllib.parse, urllib.request

TOKEN = "PEGA_AQUI_EL_TOKEN"
PRIVATE_KEY = "PEGA_AQUI_LA_CLAVE_PRIVADA"   # "" si la clave no exige firma


def mundosms(metodo, ruta, datos=None, token=TOKEN, private_key=PRIVATE_KEY):
    datos = datos or {}
    query, cuerpo = "", b""
    if metodo in ("GET", "DELETE"):
        if datos:   # listas separadas por comas; sí/no como true/false; sin None
            q = {k: ",".join(map(str, v)) if isinstance(v, (list, tuple)) else ("true" if v is True else "false" if v is False else v)
                 for k, v in datos.items() if v is not None}
            query = "?" + urllib.parse.urlencode(q, quote_via=urllib.parse.quote)
    elif datos:
        cuerpo = json.dumps(datos, ensure_ascii=False, separators=(",", ":")).encode()   # se firma y se envía EXACTAMENTE esto
    ts = str(int(time.time()))
    cabeceras = {"Authorization": "Bearer " + token, "X-Timestamp": ts}
    if private_key:
        firmado = (token + "." + ts + "." + metodo + " " + ruta + query + ".").encode() + cuerpo
        cabeceras["X-Signature"] = base64.urlsafe_b64encode(hmac.new(private_key.encode(), firmado, hashlib.sha256).digest()).decode().rstrip("=")
    if cuerpo:
        cabeceras["Content-Type"] = "application/json"
    peticion = urllib.request.Request("https://api.mundosms.es" + ruta + query, data=cuerpo or None, headers=cabeceras, method=metodo)
    try:
        with urllib.request.urlopen(peticion, timeout=60) as r:
            http, texto = r.status, r.read()
    except urllib.error.HTTPError as e:          # 4xx y 5xx también traen JSON
        http, texto = e.code, e.read()
    try:
        return http, json.loads(texto)
    except ValueError:                           # p. ej. un proxy intermedio que contesta HTML
        return http, {"status": "error", "status_code": "2", "message": "Respuesta inesperada"}


http, r = mundosms("GET", "/v3/calls", {"type": "in", "from_datetime": time.strftime("%Y-%m-%d")})
if http == 200:
    for c in r["data"]["calls"]:
        print(c["date_start"], c["from"], c["state"])
else:
    print("Error HTTP", http, r["status_code"], r["message"], r.get("detail", ""))
Node.js
// API de MundoSMS con Node.js 18 o superior, sin dependencias
const crypto = require("crypto");

const TOKEN = "PEGA_AQUI_EL_TOKEN";
const PRIVATE_KEY = "PEGA_AQUI_LA_CLAVE_PRIVADA";   // "" si la clave no exige firma

async function mundosms(metodo, ruta, datos = {}) {
  let query = "", cuerpo = "";
  if (metodo === "GET" || metodo === "DELETE") {
    const q = new URLSearchParams();
    for (const [k, v] of Object.entries(datos)) {   // listas separadas por comas; sin null ni undefined
      if (v !== null && v !== undefined) q.append(k, Array.isArray(v) ? v.join(",") : String(v));
    }
    if (q.toString()) query = "?" + q.toString();
  } else if (Object.keys(datos).length) {
    cuerpo = JSON.stringify(datos);                 // se firma y se envía EXACTAMENTE esto
  }
  const ts = String(Math.floor(Date.now() / 1000));
  const cabeceras = { "Authorization": "Bearer " + TOKEN, "X-Timestamp": ts };
  if (PRIVATE_KEY) {
    cabeceras["X-Signature"] = crypto.createHmac("sha256", PRIVATE_KEY)
      .update(TOKEN + "." + ts + "." + metodo + " " + ruta + query + "." + cuerpo).digest("base64url");
  }
  if (cuerpo) cabeceras["Content-Type"] = "application/json";
  const r = await fetch("https://api.mundosms.es" + ruta + query,
    { method: metodo, headers: cabeceras, body: cuerpo || undefined, signal: AbortSignal.timeout(60000) });
  const texto = await r.text();
  try {
    return { http: r.status, ...JSON.parse(texto) };
  } catch (e) {                                 // p. ej. un proxy intermedio que contesta HTML
    return { http: r.status, status: "error", status_code: "2", message: "Respuesta inesperada" };
  }
}

mundosms("GET", "/v3/calls", { type: "in", from_datetime: new Date().toISOString().slice(0, 10) }).then((r) => {
  if (r.http === 200) r.data.calls.forEach((c) => console.log(c.date_start, c.from, c.state));
  else console.log("Error HTTP", r.http, r.status_code, r.message, r.detail || "");
});

Lo que hay que respetar en cualquier lenguaje:

  • Se firma el texto del cuerpo y se envía ese mismo texto. Si tu herramienta vuelve a montar el JSON (otro orden de campos, espacios, saltos de línea), la firma ya no vale. En n8n o similares, manda el cuerpo como texto ya hecho.
  • La query se firma tal cual va en la URL: si tu librería la reordena o la escapa de otra forma al enviarla, fírmala después de montarla, no antes.
  • La firma va en base64url sin =. El base64 normal no vale.

Errores de autenticación#

Todos llevan status_code "3"; el código HTTP dice de qué tipo son.

HTTP message Qué pasa
401 Missing Authorization header… no llega la cabecera Authorization
401 The Authorization header must be "Bearer <token>" … lo que va tras Bearer no es un token: vacío, cortado o la clave privada en su lugar
401 Token invalid el token no es de una clave nuestra, o tiene algún carácter cambiado
401 Token expired la clave ha caducado (se alarga en «Claves de API»)
401 Authentication failure la firma no casa: falta X-Signature, se firmó con otra clave, en base64 normal, otra ruta, otra query u otro cuerpo
401 Signed requests must include the X-Timestamp header… falta X-Timestamp, o tu reloj va desfasado más de 5 minutos
403 Not allowed la clave no tiene permiso para esa ruta: detail dice cuáles sirven
403 IP not allowed la petición no llega desde una IP de la lista de la clave
409 Duplicated request esa misma petición firmada (mismo X-Timestamp, ruta y cuerpo) ya había llegado

Permisos#

Cada ruta pide un nivel (lectura o escritura) y pertenece a una o varias categorías. Una clave puede usar una ruta si tiene cualquiera de los permisos que dice su columna en Rutas:

  • all (todo);
  • el permiso de la ruta, por ejemplo click2dial para POST /v3/calls;
  • una de sus categorías: voip (centralita), vozpush (llamadas automáticas), sms, numcheck o whatsapp;
  • su nivel: read (todas las de lectura) o write (todas las de escritura). WhatsApp es la excepción: read y write a secas no entran (ver WhatsApp).

Las locuciones, los diagramas y la verificación de números están en voip y en vozpush.

El permiso de la ruta vale para todo lo que hace ese método: getreport_call deja consultar las campañas de VozPush y pausarlas, reanudarlas o cancelarlas. Para una clave que solo consulte campañas, usa read.

Dale a cada integración solo lo que necesita: un CRM que sincroniza el historial se arregla con read; uno que además llama, con read y click2dial. En la ficha de la clave, «Todo», o marcar a la vez «Todas las consultas» y «Todas las acciones», guarda la clave como all.

Convenciones#

Petición#

  • En GET y DELETE, los parámetros en la query (?type=in&limit=20), escapados como en una URL. En POST y PATCH, en un cuerpo JSON (Content-Type: application/json), codificado en UTF-8.
  • Los nombres de los parámetros, en minúsculas y con _. Un parámetro que la ruta no conoce se ignora.
  • Sí/no: true o false (en la query, el texto true/false). Se aceptan también 1/0.
  • Listas (destinatarios, ids): en JSON, una lista (["34600123456","34600123457"]); en la query, separadas por comas (ids=101,102).
  • Números de teléfono: como texto, en formato internacional y solo cifras: "34600123456". Un + delante se acepta y se quita.
  • Fechas de entrada: AAAA-MM-DD, AAAA-MM-DD hh:mm, AAAA-MM-DD hh:mm:ss o AAAA-MM-DD hh:mm:ss.mmm, en hora de Madrid. También se acepta ISO 8601 con zona (2026-11-20T09:00:00Z) en date_scheduled y en los filtros from_datetime y to_datetime. Una fecha que no vale da 400 Parameter <nombre> not valid. AAAA-MM-DD sola es ese día a las 00:00:00.

Respuesta#

Siempre JSON (Content-Type: application/json; charset=utf-8) con su código HTTP:

Campo Tipo Qué es
status texto success o error
status_code texto "0" si fue bien; si no, el tipo de error (tabla siguiente)
message texto OK, N results en los listados, o la frase del error, en inglés y estable: puedes compararla
detail texto solo en algunos errores: más contexto (qué valor se espera, qué contestó el servidor de voz)
data objeto los datos, cuando los hay
HTTP status_code Significado
200 "0" bien
400 "3" falta un parámetro o no vale
401 "3" autenticación: token, firma o X-Timestamp
402 "5" saldo insuficiente
403 "3" sin permiso para la ruta, IP no admitida o número no verificado
404 "4" no existe (en tu cuenta), o la ruta no existe
405 "3" la ruta existe, pero no con ese verbo (cabecera Allow)
409 "3" conflicto: petición repetida, o no se puede en el estado actual (ya enviado, ya cancelado, ya existe)
429 "7" demasiadas peticiones o intentos
500 "2" error interno o el servidor de voz no responde: reintenta más tarde

WhatsApp usa además sus propios códigos ("6" a "12", ver WhatsApp). status_code es texto ("0", no 0): es un código, no una cantidad. En JavaScript, "0" !== 0.

Cada respuesta lleva la cabecera X-Request-Id (26 letras y cifras). Guárdala cuando algo falle: con ella encuentras la petición en Logs API y, si nos escribes, la encontramos nosotros.

Ejemplo de error:

JSON
{
  "status": "error",
  "status_code": "3",
  "message": "Parameter from_datetime not valid",
  "detail": "formato AAAA-MM-DD[ hh:mm[:ss[.mmm]]], hora de Madrid"
}

Fechas y zona horaria#

Cada fecha de la respuesta sale dos veces:

  • date_x: AAAA-MM-DD hh:mm:ss.mmm, hora de Madrid, con milisegundos. Es la forma cómoda para guardar en una base de datos que trabaje en hora de España.
  • date_x_iso: la misma en ISO 8601 con su zona (+01:00 en invierno, +02:00 en verano). Es la que hay que usar para convertir a otra zona o a UTC sin ambigüedad (la hora repetida del cambio de horario de octubre solo la distingue esta).
JSON
{ "date_start": "2026-11-20 10:15:03.250", "date_start_iso": "2026-11-20T10:15:03.250+01:00" }

Las horas que guardamos sin fracción salen con .000. Si no hay fecha (una llamada que no se descolgó no tiene date_answer), las dos son null.

Las fechas que mandas (from_datetime, to_datetime, date_scheduled) valen de las dos formas:

  • AAAA-MM-DD hh:mm:ss, en hora de Madrid (los segundos, los minutos y la hora se pueden omitir; la fracción, también);
  • ISO 8601 con su zona: 2026-11-20T09:15:03Z o 2026-11-20T10:15:03+01:00. Las convertimos a hora de Madrid. Sin zona (2026-11-20T10:15:03) cuenta como hora de Madrid.

Así puedes mandar tal cual una fecha date_x_iso que te hayamos devuelto.

null, números y textos#

  • Un dato que no existe o no aplica es null, nunca "". Los campos salen siempre, aunque valgan null, salvo los que dependen de un parámetro include_* o del tipo de objeto (por ejemplo, extension solo en las llamadas salientes): cada ruta lo dice.
  • Las cantidades son números JSON: credits: 0.0125, duration: 213. Los ids, enteros.
  • Los teléfonos, los DID y los códigos son texto: "34600123456", "0".
  • Las duraciones van en segundos y no llevan sufijo (duration, duration_ring); los campos en otra unidad lo dicen en el nombre (latency_ms, retry_delay_min).

Identificadores: id y client_id#

  • id es nuestro identificador del objeto (una llamada, un envío, una extensión). Es un entero y no cambia.
  • Un SMS a un destinatario se identifica por su envío y su número: send_id + to.
  • client_id es tu referencia, la que mandas al crear algo (un SMS, una campaña de VozPush, una consulta de NumCheck, un WhatsApp). Sale en las respuestas y sirve para buscar por ella. En los objetos que no la admiten (llamadas, números, extensiones, locuciones) es siempre null.
  • Topes de client_id: 50 caracteres en SMS y SMS certificados, 30 en NumCheck, 20 en campañas de VozPush y 100 en WhatsApp.
  • client_id no impide duplicados: dos envíos con la misma referencia son dos envíos. Para no duplicar al reintentar, mira Reintentos seguros.

Paginación con cursor#

GET /v3/calls, GET /v3/sms, GET /v3/sms/replies, GET /v3/numbers y GET /v3/diagrams devuelven como mucho limit elementos, en data.<lista>, con:

Campo Qué es
results cuántos elementos trae esta página
has_more true si hay más después de esta página
next_cursor la posición desde la que pedir la página siguiente: pásala tal cual como cursor. Es texto y no hay que interpretarlo; null en orden desc
next_from_id en las listas que avanzan por id, lo mismo como número (pásalo como from_id). Sigue por compatibilidad: usa next_cursor

Cómo se recorre un listado:

  • El mismo mecanismo en todas las listas: pide la primera página, y la siguiente con cursor = el next_cursor que te devolvimos, mientras has_more sea true. No hace falta saber cómo avanza cada lista por dentro.
  • cursor y from_id son la misma posición en las listas que avanzan por id. No mandes los dos distintos: da 400.
  • from_id es exclusivo: devuelve los elementos con id mayor que él.
  • order: asc (del más antiguo al más nuevo) o desc (los últimos primero). Por defecto, asc si pasas cursor, from_id o from_datetime, y desc si no (las últimas).
  • Para recorrer todo o sincronizar, usa order=asc y avanza con cursor = next_cursor mientras has_more sea true. Guarda el último next_cursor: es tu marca para la siguiente sincronización. En asc llega también con has_more: false (es la posición del último): con él, más tarde, pides solo lo nuevo.
  • El orden desc sirve para «las últimas N»; no tiene página siguiente: trae has_more: true si hay más antiguas, pero next_cursor: null. Un bucle que siga mientras has_more sea true tiene que ir en asc, o no avanzará nunca.
  • GET /v3/numbers y GET /v3/diagrams van siempre en orden de id (sin order).
  • GET /v3/calls con type=all (el valor por defecto) mezcla tres tablas, cada una con su numeración, así que no avanza por id: solo tiene next_cursor (y next_from_id sale null). Por eso conviene usar siempre cursor.
    • No te salta ni te repite ninguna llamada.
    • Si no hay nada nuevo, devuelve 0 resultados y el mismo cursor.
  • En cada página repite los mismos filtros: el cursor solo lleva la posición.
  • Los SDK lo hacen por ti: todos() recorre las páginas y te da los elementos uno a uno.

Nombres anteriores (alias)#

Algunos parámetros aceptan también el nombre que tenían en /APIv3/ (por ejemplo destination por to, o message por text, en POST /v3/sms). En la respuesta solo sale el nombre nuevo. Usa siempre el nuevo: los alias son para migrar, y la tabla está en Equivalencias de nombres.

Llamadas en curso e historial#

Estados de una llamada#

state es una palabra estable. Los grupos del filtro status de GET /v3/calls son answered y missed; las llamadas en curso no entran en ninguno.

En las entrantes, state no dice si alguien la atendió. La centralita descuelga para el menú o la cola, así que una entrante que nadie coge acaba answered. Para saber si la atendió una persona, mira attended_by, o filtra con status: en las entrantes, status va por quién atendió, no por state.

state Qué pasó Grupo de status
ringing está sonando en curso
talking descolgada, en conversación en curso
forwarding desviándose en curso
ending terminando en curso
answered se descolgó y ya terminó answered
ended una llamada de función (menú, buzón, locución) que terminó —
no_answer sonó y nadie la cogió missed
busy comunicando missed
unreachable no se llegó al teléfono (apagado, sin cobertura, extensión no conectada) missed
cancelled quien llamaba colgó mientras sonaba missed
rejected rechazada missed
do_not_disturb el destino tenía «no molestar» missed
failed error: número inexistente, destino no admitido… missed
forwarded se desvió a otro destino (la llamada desviada va aparte, enlazada con parent_id) —
unknown cualquier otro —

En GET /v3/calls, state_code lleva además el código numérico de la versión anterior (0-11, -1 si no tiene), para quien lo necesite: distingue, por ejemplo, entre una llamada terminada por quien llamó o desde la centralita, que en state son las dos answered.

Tipos de llamada#

type Qué es
in entrante: alguien llama a uno de tus números
out saliente: una extensión llama fuera, o una pata que crea la centralita (un desvío a un móvil)
func de función: el tramo que la llamada pasa en un menú, un buzón, una locución o una cola

Cada tipo tiene su propia serie de id: la llamada in 8812345 y la out 8812345 son dos distintas. Por eso las rutas de llamadas piden type junto al id.

Una llamada con desvíos o transferencias son varias filas enlazadas: la entrante, la saliente que la desvió a un móvil y el tramo del menú llevan parent_type/parent_id apuntando a la que las originó, y con include_related: true cada llamada trae sus relacionadas dentro, en related.

GET /v3/calls/live — llamadas en curso#

GET https://api.mundosms.es/v3/calls/live Pruébalo

Las llamadas que están sonando o en conversación ahora mismo. Sirve para un panel de recepción («¿con quién habla cada extensión?»), para mostrar la ficha del cliente cuando suena el teléfono o para saber si un número está ya al teléfono.

Permiso: read, voip o list_voiplivecalls.

Parámetro Tipo Obligatorio Qué es
type texto no all (por defecto), in, out o func
extension texto no solo las llamadas en las que participa esta extensión. Con ella, cada llamada lleva other_party: con quién habla la extensión
number texto no solo las llamadas en las que aparece este número (origen, destino o alguna pata)
from_datetime fecha no solo las que empezaron desde esta hora
all_legs sí/no no true: también las llamadas que ya van como pata de otra, sueltas. Por defecto, solo las principales (como en GET /v3/calls)
limit entero no 1-500, 100 por defecto

Petición:

HTTP
GET /v3/calls/live?extension=recepcion

Respuesta (200):

JSON
{
  "status": "success",
  "status_code": "0",
  "message": "1 results",
  "data": {
    "results": 1,
    "calls": [
      {
        "id": 8812399,
        "client_id": null,
        "type": "in",
        "from": "34600123456",
        "to": "34910123456",
        "party": "recepcion",
        "state": "talking",
        "date_start": "2026-11-20 11:02:10.031",
        "date_start_iso": "2026-11-20T11:02:10.031+01:00",
        "date_answer": "2026-11-20 11:02:14.540",
        "date_answer_iso": "2026-11-20T11:02:14.540+01:00",
        "date_bridged": "2026-11-20 11:02:14.602",
        "date_bridged_iso": "2026-11-20T11:02:14.602+01:00",
        "legs": [
          {
            "id": 5511203,
            "client_id": null,
            "type": "out",
            "from": "34910123456",
            "to": "recepcion",
            "party": "recepcion",
            "state": "talking",
            "date_start": "2026-11-20 11:02:10.412",
            "date_start_iso": "2026-11-20T11:02:10.412+01:00",
            "date_answer": "2026-11-20 11:02:14.540",
            "date_answer_iso": "2026-11-20T11:02:14.540+01:00",
            "date_bridged": null,
            "date_bridged_iso": null
          }
        ],
        "other_party": "34600123456"
      }
    ],
    "has_more": false
  }
}

Campos de cada llamada (y de cada pata de legs, que tienen la misma forma salvo legs y other_party):

Campo Tipo Qué es
id, type entero, texto la llamada; el mismo id que dará GET /v3/calls con ese type cuando termine
client_id null siempre null
from, to texto origen y destino
party texto o null la llamada vista desde tu búsqueda: sin extension, el participante actual; con extension, esa extensión
state texto ringing (sin descolgar) o talking (descolgada)
date_start, date_answer, date_bridged fecha o null inicio, descuelgue y cuándo quedaron conectados los dos lados
legs lista las patas de la llamada (desvíos, grupos que suenan a la vez, transferencias)
other_party texto o null solo con extension: el otro lado de la conversación visto desde esa extensión. Si hay más de dos partes, el principal; el resto está en legs

Las llamadas en curso son pocas y cambian a cada segundo: este listado no tiene cursor (next_from_id). Si has_more es true, hay más de limit: afina el filtro o sube limit.

Errores propios: 400 Parameter limit not valid, 400 Parameter number not valid.

POST /v3/calls/live/{type}/{id}/hangup — colgar una llamada en curso#

POST https://api.mundosms.es/v3/calls/live/{type}/{id}/hangup

Cuelga una llamada que está en curso.

Permiso: write, voip o action_voiplivecalls.

Parámetro Tipo Obligatorio Qué es
type texto sí in, out o func (en la ruta)
id entero sí el id de la llamada (de GET /v3/calls/live) (en la ruta)

Petición:

HTTP
POST /v3/calls/live/in/8812399/hangup

Respuesta (200):

JSON
{"status":"success","status_code":"0","message":"OK","data":{"id":8812399,"type":"in","changed":true}}

changed: false quiere decir que la llamada ya había terminado: no es un error, y message lo dice (Call already terminated).

Errores propios: 404 Call not found, 400 Parameter type not valid.

GET /v3/calls — historial de llamadas#

GET https://api.mundosms.es/v3/calls Pruébalo

El historial de llamadas terminadas (y, si no pides lo contrario, también las que siguen en curso), con sus horas, estado, duración, coste y desvíos. Es la ruta para sincronizar las llamadas con un CRM (ver Sincronizar llamadas sin perder ninguna). Sin type, trae todas: entrantes, salientes y funciones que empiezan solas, ordenadas por hora de inicio, así que una sola petición basta.

Permiso: read, voip o list_voipcalls.

También: GET /v3/calls/{type}/{id} — una llamada por su id (sin paginación; si no existe, 404 Call not found).

Parámetro Tipo Obligatorio Qué es
type texto no all (por defecto): entrantes, salientes y funciones sin padre (las que empiezan solas, no las que son un paso de una llamada; esas salen con include_related), ordenadas por hora de inicio. O solo in, out o func
cursor texto no el next_cursor de la página anterior, tal cual (con cualquier type)
from_id entero no con type in, out o func: lo mismo que cursor, como número (por compatibilidad)
limit entero no 1-100, 20 por defecto
order texto no asc o desc (ver Paginación con cursor)
from_datetime fecha no desde esta hora de inicio (incluida)
to_datetime fecha no hasta esta hora de inicio (sin incluir)
stop_at_ongoing sí/no no true: la página se corta antes de la primera llamada que siga en curso (no la quita: se para ahí), para que no te saltes ninguna a medias. Una que lleve más de 12 horas «en curso» (un registro que no se cerró) no la corta: sale con su estado. Exige order: "asc"
number texto no las llamadas en las que este número es el origen o el destino
status texto no answered o missed. Entrantes: answered = la atendió alguien (attended_by); missed = no la atendió nadie y ya colgó, aunque la centralita la descolgara para el menú o la cola. Salientes: por el estado, answered = contestó el destino (ver Estados de una llamada). Solo con type in u out
extension texto no salientes: la extensión que llamó; entrantes: la que descolgó. Solo con type in u out
did texto no entrantes: tu número al que llamaron; salientes: el número que se presentó. Solo con type in u out
all_legs sí/no no true: también las patas internas de cada llamada (por defecto solo las principales)
include_related sí/no no true: cada llamada trae sus relacionadas (desvíos, transferencias, funciones) en related
include_xml sí/no no true: en las de función, el plan XML entero en xml_plan (es grande)

Petición: las llamadas perdidas de un número desde el día 1:

HTTP
GET /v3/calls?type=in&number=34600123456&status=missed&from_datetime=2026-11-01

Respuesta (200):

JSON
{
  "status": "success",
  "status_code": "0",
  "message": "1 results",
  "data": {
    "results": 1,
    "calls": [
      {
        "id": 8812001,
        "client_id": null,
        "type": "in",
        "from": "34600123456",
        "from_name": null,
        "to": "34910123456",
        "to_type": "landline",
        "state": "no_answer",
        "state_code": 3,
        "date_start": "2026-11-18 17:40:22.113",
        "date_start_iso": "2026-11-18T17:40:22.113+01:00",
        "date_answer": null,
        "date_answer_iso": null,
        "date_end": "2026-11-18 17:40:52.907",
        "date_end_iso": "2026-11-18T17:40:52.907+01:00",
        "duration": 0,
        "duration_ring": 30,
        "pickup_extension": null,
        "attended_by": null,
        "last_attended_by": null,
        "followup": {
          "state": "called_back",
          "id": 8812950,
          "type": "out",
          "date": "2026-11-18 17:52:10.120",
          "date_iso": "2026-11-18T17:52:10.120+01:00",
          "extension": "recepcion",
          "callback_attempts": 1
        },
        "credits": 0.0,
        "credits_total": 0.0,
        "bundle_id": null,
        "callingcard_id": null,
        "parent_type": null,
        "parent_id": null
      }
    ],
    "has_more": false,
    "next_from_id": 8812001,
    "next_cursor": "8812001"
  }
}

Campos de cada llamada. Según type salen unos u otros:

  • todas: id, client_id, type, from, to, state, state_code, date_start, date_answer, date_end, duration, credits, credits_total, bundle_id, callingcard_id, parent_type y parent_id;
  • in y out, además: from_name, to_type y duration_ring;
  • out (salientes): extension, bridge_type y date_bridged;
  • in (entrantes): pickup_extension, attended_by, last_attended_by y followup;
  • las que nos llegaron desviadas: los redirected_*;
  • func (de función): trace_steps, trace_ivr, result_ivr, result_record, result_subivr y, con include_xml, xml_plan.
Campo Tipo Qué es
id, type entero, texto la llamada
client_id null siempre null
from texto o null quien llama. En las de función, null
from_name texto o null el nombre que se presentó con el número, si lo hubo
to texto o null el destino
to_type texto o null extension, landline (fijo), mobile, special, function o unknown. No sale en las de función
state, state_code texto, entero ver Estados de una llamada
date_start, date_answer, date_end fecha o null inicio, descuelgue y fin (en las de función, date_answer es la entrada en la función)
date_bridged fecha o null solo salientes: cuándo quedaron conectados los dos lados
duration entero o null segundos de conversación
duration_ring entero o null segundos sonando (no en las de función)
extension texto o null solo salientes: la extensión que llamó
bridge_type texto o null solo salientes: cómo se conectó (por ejemplo, attended_transfer)
pickup_extension texto o null solo entrantes: la extensión que la cogió
attended_by, last_attended_by texto o null solo entrantes: quién la atendió primero y último. null si no la atendió nadie (es una perdida, aunque state diga answered)
followup objeto o null solo entrantes, y solo en las perdidas (en las demás, null): qué pasó después. Ver abajo
redirected_from, redirected_reason, redirected_count, redirected_chain, redirected_headers solo si la llamada nos llegó desviada desde otro número: quién la desvió (anonymous si lo ocultó), por qué y la cadena completa
credits, credits_total número o null coste de esta llamada y con sus relacionadas
bundle_id entero o null el bono de minutos que se usó
callingcard_id entero o null la tarjeta de llamadas, si la hubo
trace_steps, trace_ivr, result_ivr, result_record, result_subivr texto o null solo las de función: el recorrido por el plan, las teclas pulsadas y lo grabado, separados por barras verticales
xml_plan texto o null solo las de función y con include_xml
parent_type, parent_id texto, entero o null la llamada que originó esta (un desvío, una transferencia)
related lista solo con include_related: las llamadas relacionadas, con esta misma forma

En una llamada que nos llega desviada, from es quien llamó, to es tu número y quien desvió va en redirected_from. En la pata que crea tu centralita al desviar a un móvil, from es el número que se presenta, to es el móvil y parent_id apunta a la entrante.

Llamadas perdidas. Cada perdida entrante (nadie la atendió y ya colgó) lleva siempre followup, con lo primero que pasó después con ese número:

followup.state Qué pasó
called_back alguien de tu cuenta le llamó y contestó (más de 5 segundos, o sigue hablando)
called_again volvió a llamar y le atendieron (más de 5 segundos, o sigue hablando)
pending nada de lo anterior: está por devolver
no_number llamó con el número oculto: no se puede devolver
  • id, type, date y extension son de esa llamada (de quién la devolvió o de quién le atendió). Con pending, null.
  • callback_attempts cuenta las llamadas que se le hicieron sin que contestara, hasta resolverse.
  • El seguimiento se calcula al pedirlo: una perdida pending hoy puede ser called_back mañana.
  • Para saber a quién llamar (las perdidas pendientes, una por número), usa GET /v3/calls/missed.

Errores propios: 400 Parameter type not valid, 400 Parameter <nombre> not valid (con detail: qué se espera), 404 Call not found (con id).

GET /v3/calls/missed — llamadas perdidas por devolver#

GET https://api.mundosms.es/v3/calls/missed Pruébalo

A quién llamar: los números con llamadas perdidas que nadie ha atendido después, uno por número, la más reciente primero.

  • Perdida: una entrante que no atendió nadie, aunque la centralita la descolgara para el menú o la cola.
  • Atendida después: volvió a llamar y le atendieron, o alguien de tu cuenta le llamó y contestó (más de 5 segundos, o sigue hablando).

Es una foto, sin cursor: un número sale de la lista en cuanto se le atiende. Pídela entera cada vez.

Permiso: read, voip o list_voipcalls.

Parámetro Tipo Obligatorio Qué es
from_datetime fecha no desde (incluida). Por defecto, hace 7 días; como mucho, hace 31
to_datetime fecha no hasta (sin incluir). Por defecto, ahora
number texto no un número que llamó
did texto no tu número al que llamaron
include_returned sí/no no true: también los números ya atendidos, con quién y cómo. Por defecto, solo los pendientes
limit entero no 1-500, 100 por defecto

Petición (sin parámetros: los números con llamadas perdidas sin devolver de los últimos 7 días, en todos tus números):

HTTP
GET /v3/calls/missed

Respuesta (200):

JSON
{
  "status": "success",
  "status_code": "0",
  "message": "1 results",
  "data": {
    "results": 1,
    "numbers": [
      {
        "number": "34600123456",
        "did": "34910123456",
        "missed_count": 2,
        "first_missed": "2026-11-20 09:58:02.410",
        "first_missed_iso": "2026-11-20T09:58:02.410+01:00",
        "last_missed": "2026-11-20 10:31:15.002",
        "last_missed_iso": "2026-11-20T10:31:15.002+01:00",
        "last_call_id": 8812001,
        "followup": {
          "state": "pending",
          "id": null,
          "type": null,
          "date": null,
          "date_iso": null,
          "extension": null,
          "callback_attempts": 1
        }
      }
    ],
    "has_more": false,
    "anonymous": 3
  }
}
Campo Qué es
number quien llamó
did tu número al que llamó la última vez
missed_count perdidas desde la última vez que se le atendió (dentro de la ventana)
first_missed, last_missed la primera y la última de esas perdidas
last_call_id la última perdida, por si la quieres ver en GET /v3/calls (type in, id)
followup como en GET /v3/calls: pending o, con include_returned, called_back / called_again con la llamada, su hora y la extensión. callback_attempts: las veces que se le llamó sin que contestara
anonymous perdidas con el número oculto en la ventana: no se pueden devolver, así que no salen en la lista

Errores propios: 400 Parameter from_datetime not valid (más de 31 días atrás), 400 Parameter <nombre> not valid.

GET /v3/calls/{type}/{id}/recording — grabación de una llamada#

GET https://api.mundosms.es/v3/calls/{type}/{id}/recording

Descarga la grabación de una llamada (si la llamada se grabó).

Permiso: read, voip o getrecording_voipcalls.

Parámetro Tipo Obligatorio Qué es
type texto sí in, out o func (en la ruta)
id entero sí el id de la llamada (en la ruta)
mode_out texto no inline (por defecto: el audio en la respuesta), download (el audio como descarga) o base64 (JSON con el audio en base64)
format texto no mp3: convertido a MP3, que reproduce cualquier navegador. Sin él, el formato original (normalmente OGG/Opus)
filename texto no el nombre del fichero, sin extensión

Con inline y download la respuesta es el audio (con su Content-Type, por ejemplo audio/ogg o audio/mpeg), y admite peticiones parciales (Range) para reproducirlo a saltos. Los errores son JSON, como en el resto.

Petición:

HTTP
GET /v3/calls/in/8812345/recording?mode_out=base64&format=mp3

Respuesta (200):

JSON
{
  "status": "success",
  "status_code": "0",
  "message": "OK",
  "data": {
    "id": 8812345,
    "type": "in",
    "client_id": null,
    "filename": "llamada_8812345.mp3",
    "content_type": "audio/mpeg",
    "size": 845120,
    "base64": "SUQzBAAAAAAAI1RTU0UAAAAPAAADTGF2ZjYxLjcuMTAw..."
  }
}

Errores propios: 404 Call not found, 404 Recording not found (la llamada existe pero no tiene grabación), 500 Internal error (no se pudo leer la grabación: reintenta más tarde).

Números y extensiones#

GET /v3/numbers — tus números#

GET https://api.mundosms.es/v3/numbers Pruébalo

Tus números de teléfono (DID) con su configuración y su coste.

Permiso: read, voip o get_voipdids.

También: GET /v3/numbers/{did} — uno de tus números.

Parámetro Tipo Obligatorio Qué es
did texto no un número concreto
include_xml sí/no no true: el plan de llamadas XML de cada número en xml_plan (es grande)
cursor texto no el next_cursor de la página anterior: la página siguiente
from_id entero no lo mismo que cursor, como número (por compatibilidad)
limit entero no 1-500, 100 por defecto

Devuelve tus números en orden de id, con cursor (Paginación con cursor). Con did, solo ese número y sin cursor (has_more false y next_from_id null).

Petición:

HTTP
GET /v3/numbers?limit=100

Respuesta (200):

JSON
{
  "status": "success",
  "status_code": "0",
  "message": "1 results",
  "data": {
    "results": 1,
    "dids": [
      {
        "id": 4410,
        "client_id": null,
        "did": "34910123456",
        "name": "Centralita Madrid",
        "date_created": "2025-03-02 12:30:00.000",
        "date_created_iso": "2025-03-02T12:30:00.000+01:00",
        "date_expire": null,
        "date_expire_iso": null,
        "date_last_activity": "2026-11-20 11:02:10.000",
        "date_last_activity_iso": "2026-11-20T11:02:10.000+01:00",
        "calls_enabled": true,
        "fax_enabled": false,
        "sms_enabled": false,
        "diagram_id": 3120,
        "sms_url": null,
        "sms_email": null,
        "fax_url": null,
        "fax_email": null,
        "fax_extension": null,
        "monthly_cost_euro": 1.95,
        "monthly_cost_credits": 39.0,
        "minute_cost_landline": 0.0,
        "minute_cost_mobile": 0.0,
        "sms_cost": 0.0,
        "record_calls": true
      }
    ],
    "has_more": false,
    "next_from_id": 4410,
    "next_cursor": "4410"
  }
}

date_expire es null si el número no caduca. diagram_id es el diagrama (plan de llamadas) que atiende el número; lo describe GET /v3/diagrams.

Errores propios: 404 DID not found (con did).

PATCH /v3/numbers/{did} — cambiar un número#

PATCH https://api.mundosms.es/v3/numbers/{did}

Cambia uno o varios datos de la configuración de uno de tus números, de una vez: se comprueba todo antes de guardar, y si un campo no vale no se cambia ninguno. Manda solo los campos que quieres cambiar.

Permiso: write, voip o set_voipdids.

Parámetro Tipo Obligatorio Qué es
did texto sí el número (en la ruta)
name texto no el nombre del número, de 5 a 45 caracteres
diagram_id entero no el diagrama (de tu cuenta, con plan) que atiende las llamadas. Deja de usar xml_plan
xml_plan texto no el plan en XML (se comprueba antes de guardar). Deja de usar diagram_id. diagram_id y xml_plan a la vez dan 400
record_calls sí/no no grabar las llamadas
sms_url texto no URL http:// o https:// (hasta 100) a la que reenviar los SMS que lleguen al número; "" o null la quita. Hoy ningún número recibe SMS: se guarda, pero no se usa
sms_email texto no correo (hasta 45) al que reenviar esos SMS; "" o null lo quita. Como sms_url, hoy no se usa
fax_url texto no URL a la que reenviar los faxes; "" o null la quita
fax_email texto no correo al que reenviar los faxes; "" o null lo quita
fax_extension texto no extensión que recibe los faxes; "" o null la quita

Petición:

HTTP
PATCH /v3/numbers/34910123456
Content-Type: application/json

{"record_calls":false,"diagram_id":3120,"sms_email":"recepcion@ejemplo.com"}

Respuesta (200):

JSON
{"status":"success","status_code":"0","message":"OK","data":{"id":4410,"did":"34910123456","changed":true,"fields":["record_calls","diagram_id","sms_email"]}}

fields son los campos que mandaste. changed: false quiere decir que ya tenían esos valores: no es un error, y message lo dice (DID parameter was already set).

Errores propios: 404 DID not found, 400 Parameter <campo> not valid (con detail: qué se espera; en xml_plan, qué falla en el XML), 400 Body not valid (nada que cambiar).

GET /v3/extensions — tus extensiones#

GET https://api.mundosms.es/v3/extensions Pruébalo

Las extensiones de tu centralita y, si lo pides, si están conectadas ahora y desde dónde.

Permiso: read, voip o get_voipextensions.

También: GET /v3/extensions/{extension} — una de tus extensiones.

Parámetro Tipo Obligatorio Qué es
extension texto no una extensión concreta
include_status sí/no no true: el registro de cada extensión en registration. Por defecto, true con extension y false sin ella

Devuelve todas tus extensiones de una vez, sin cursor, las más nuevas primero.

Petición:

HTTP
GET /v3/extensions?extension=recepcion

Respuesta (200):

JSON
{
  "status": "success",
  "status_code": "0",
  "message": "1 results",
  "data": {
    "results": 1,
    "extensions": [
      {
        "id": 20431,
        "client_id": null,
        "extension": "recepcion",
        "date_created": "2025-03-02 12:41:07.000",
        "date_created_iso": "2025-03-02T12:41:07.000+01:00",
        "date_last_activity": "2026-11-20 11:02:14.000",
        "date_last_activity_iso": "2026-11-20T11:02:14.000+01:00",
        "caller_id": "\"Recepción\" <34910123456>",
        "caller_id_name": "Recepción",
        "caller_id_number": "34910123456",
        "comment": null,
        "record_calls": true,
        "password": null,
        "registration": {
          "state": "registered",
          "max_latency_ms": 31.4,
          "connections_count": 1,
          "keepalive": "ok",
          "connections": [
            {
              "type": "sip",
              "state": "reachable",
              "host": "203.0.113.25",
              "port": 5060,
              "local_host": "192.168.1.30",
              "local_port": 5060,
              "server_host": null,
              "server_port": null,
              "protocol": "udp",
              "latency_ms": 31.4,
              "user_agent": "Yealink SIP-T54W 96.86.0.70",
              "date_last_keepalive": "2026-11-20 11:05:00.000",
              "date_last_keepalive_iso": "2026-11-20T11:05:00.000+01:00",
              "outbound_proxy": null
            }
          ]
        }
      }
    ]
  }
}

Campos destacados:

Campo Qué es
caller_id, caller_id_name, caller_id_number el número (y el nombre) que presenta la extensión al llamar fuera
password la contraseña SIP. Solo al pedir una extension concreta y con una clave que pueda modificar extensiones; si no, null
registration.state registered (conectada), unregistered (desconectada), unknown o pbx_unreachable (la centralita no respondió: reintenta)
registration.connections[] cada aparato o app conectado: type sip (teléfono o softphone) o push (app móvil en reposo), y state reachable, unreachable o pending (recién conectado)

Errores propios: 404 Extension not found (con extension).

PATCH /v3/extensions/{extension} — cambiar una extensión#

PATCH https://api.mundosms.es/v3/extensions/{extension}

Cambia uno o varios datos de una extensión, de una vez: se comprueba todo antes de guardar, y si un campo no vale no se cambia ninguno. Manda solo los campos que quieres cambiar.

Permiso: write, voip o set_voipextensions.

Parámetro Tipo Obligatorio Qué es
extension texto sí la extensión (en la ruta)
caller_id texto no lo que presenta al llamar, entero: "Texto" <número>. O este, o sus partes
caller_id_number texto no solo el número que presenta (el texto se conserva)
caller_id_name texto no solo el texto que presenta (hasta 40, sin comillas ni < >; el número se conserva)
comment texto no un comentario, hasta 45 caracteres
record_calls sí/no no grabar sus llamadas

Petición:

HTTP
PATCH /v3/extensions/recepcion
Content-Type: application/json

{"caller_id_number":"34910123456","record_calls":true}

Respuesta (200):

JSON
{"status":"success","status_code":"0","message":"OK","data":{"id":20431,"extension":"recepcion","changed":true,"fields":["caller_id_number","record_calls"]}}

changed: false quiere decir que ya tenía esos valores: no es un error, y message lo dice (Extension parameter was already set).

El número que presenta una extensión tiene que ser tuyo: uno de tus números (DID) o uno verificado con POST /v3/callerid-validations. Si no, 403 Caller ID not verified. El texto y el número juntos caben en 50 caracteres.

Errores propios: 404 Extension not found, 400 Parameter <campo> not valid, 400 Body not valid (nada que cambiar), 403 Caller ID not verified.

POST /v3/extensions — crear una extensión#

POST https://api.mundosms.es/v3/extensions

Crea una extensión y devuelve su contraseña SIP para configurar el teléfono o la app.

Permiso: write, voip o new_voipextensions.

Parámetro Tipo Obligatorio Qué es
extension texto sí el nombre de la extensión
caller_id texto no el número que presenta, como "Texto" <número>; o, por separado, caller_id_name y caller_id_number
comment texto no una nota
record_calls sí/no no grabar sus llamadas (true por defecto)

Petición:

HTTP
POST /v3/extensions
Content-Type: application/json

{"extension":"ventas2","caller_id_name":"Ventas","caller_id_number":"34910123456","record_calls":false}

Respuesta (200):

JSON
{"status":"success","status_code":"0","message":"OK","data":{"id":20577,"client_id":null,"extension":"ventas2","password":"q8Rk2mXz7LwP"}}

Guarda la contraseña en un sitio seguro: es la de la extensión.

Errores propios: 400 Parameter extension not valid, 400 Parameter caller_id not valid, 403 Caller ID not verified, 409 Extension already exists.

POST /v3/callerid-validations — verificar un número para presentarlo#

POST https://api.mundosms.es/v3/callerid-validations

Para presentar como remitente un número que no es de MundoSMS (el fijo de tu oficina, un móvil), hay que verificar que es tuyo: llamamos a ese número y una locución dicta un código que hay que introducir en el panel.

Permiso: write, voip, vozpush o callerid_validation.

Parámetro Tipo Obligatorio Qué es
number texto sí el número que se verifica
url_callback texto no URL tuya (https://, pública, hasta 250 caracteres) a la que avisamos cuando termina la llamada de verificación (qué llega)

Petición:

HTTP
POST /v3/callerid-validations
Content-Type: application/json

{"number":"34981123456"}

Respuesta (200):

JSON
{
  "status": "success",
  "status_code": "0",
  "message": "OK",
  "data": {"number":"34981123456","state":"in_progress","relaunched":false,"code":"4821","attempts":1,"vozpush_id":991203,"cost":0.05,"balance":120.35}
}

state es in_progress (la llamada está en marcha) o verified (el número ya estaba verificado: entonces no se llama). relaunched: true quiere decir que había una verificación pendiente y se ha vuelto a llamar. vozpush_id se consulta con GET /v3/campaigns/{id}.

Errores propios: 400 Parameter number not valid, 402 Insufficient credit, 429 Too many attempts (como mucho 10 intentos por número).

Click2dial#

POST /v3/calls — llamar desde una extensión#

POST https://api.mundosms.es/v3/calls

Hace sonar una extensión y, cuando la descuelgan, llama al destino y los conecta. Es el botón «Llamar» de un CRM.

Permiso: write, voip o click2dial.

Parámetro Tipo Obligatorio Qué es
extension texto sí la extensión que suena primero
to texto sí el número al que se llama
from texto no el número que verá el destino. Tiene que ser tuyo (un DID o un número verificado); si no, se presenta el de la extensión
extension_caller_id texto no lo que ve la extensión en su pantalla mientras suena (por defecto, «Click2dial» y el destino)
url_callback texto no se acepta (https://, pública, hasta 150 caracteres), pero hoy no se envía ningún aviso: consulta la llamada en GET /v3/calls

Petición:

HTTP
POST /v3/calls
Content-Type: application/json

{"extension":"recepcion","to":"34600123456","from":"34910123456"}

Respuesta (200):

JSON
{"status":"success","status_code":"0","message":"OK"}

La respuesta quiere decir que la llamada se ha lanzado; la llamada en sí aparece en GET /v3/calls/live y, al terminar, en GET /v3/calls como saliente (type: "out") con from igual al número presentado.

Errores propios:

HTTP message Qué pasa
404 Extension not found la extensión no es de tu cuenta
409 Extension not registered la extensión no está conectada (ningún teléfono ni app): no puede sonar. detail lo explica
400 Parameter extension not valid
400 Parameter to not valid falta el destino o no vale
500 Voice server unavailable / Voice server error la centralita no respondió: reintenta

Grabaciones, locuciones y diagramas#

Las grabaciones de las llamadas se descargan con GET /v3/calls/{type}/{id}/recording, y las de VozPush con GET /v3/campaigns/{id}/calls/{to}/recording. Aquí están las locuciones (los audios que suenan en tus menús y campañas) y los diagramas (los planes de llamada).

GET /v3/voicefiles/{id} — descargar una locución#

GET https://api.mundosms.es/v3/voicefiles/{id}

Permiso: read, voip, vozpush o get_voicefile.

Parámetro Tipo Obligatorio Qué es
id entero sí la locución (en la ruta)
mode_out texto no inline (por defecto), download o base64
format texto no mp3: convertida a MP3. Sin él, el formato en que se guardó
filename texto no el nombre del fichero, sin extensión

Petición:

HTTP
GET /v3/voicefiles/77120?mode_out=base64

Respuesta (200):

JSON
{"status":"success","status_code":"0","message":"OK","data":{"id":77120,"client_id":null,"filename":"bienvenida.mp3","content_type":"audio/mpeg","size":48210,"base64":"SUQzBAAAAAAA..."}}

Errores propios: 404 Voice file not found (también si se borró: detail lo dice).

POST /v3/voicefiles — subir una locución#

POST https://api.mundosms.es/v3/voicefiles

Permiso: write, voip, vozpush o upload_voicefile.

Parámetro Tipo Obligatorio Qué es
filetype texto sí base64 (el audio va en file) o url (en file va una URL pública de la que lo descargamos)
file texto sí el audio en base64, o su URL
filename texto no el nombre con el que se guarda

Con url, la dirección tiene que ser pública, sin redirecciones, y el fichero de 16 MB como mucho.

Petición:

HTTP
POST /v3/voicefiles
Content-Type: application/json

{"filetype":"url","file":"https://www.ejemplo.com/audios/bienvenida.mp3","filename":"bienvenida"}

Respuesta (200):

JSON
{"status":"success","status_code":"0","message":"OK","data":{"id":77121,"client_id":null}}

Errores propios: 400 Parameter file not valid (con detail: URL not valid, URL not allowed, URL not downloadable, File too large o Empty file).

DELETE /v3/voicefiles/{id} — borrar una locución#

DELETE https://api.mundosms.es/v3/voicefiles/{id}

Permiso: write, voip, vozpush o delete_voicefile.

Parámetro Tipo Obligatorio Qué es
id entero sí la locución (en la ruta)

Respuesta (200):

JSON
{"status":"success","status_code":"0","message":"OK","data":{"id":77121,"deleted":true}}

Errores propios: 404 Voice file not found, 409 Voice file cannot be deleted (tiene un coste asociado: una locución generada), 409 Voice file cannot be deleted yet (recién usada: reintenta en unos minutos).

GET /v3/diagrams — tus diagramas#

GET https://api.mundosms.es/v3/diagrams

Los diagramas (planes de llamada) de tu cuenta: los que atienden tus números y los que usan tus campañas de VozPush.

Permiso: read, voip, vozpush o getdiagrams_voip.

También: GET /v3/diagrams/{id} — uno de tus diagramas.

Parámetro Tipo Obligatorio Qué es
id entero no un diagrama concreto
cursor texto no sin id: el next_cursor de la página anterior
from_id entero no lo mismo que cursor, como número (por compatibilidad)
limit entero no sin id: 1-500, 50 por defecto
mode_out texto no con id: image_base64 (por defecto: la imagen del diagrama en image_base64), image_inline (la imagen tal cual) o xml (el plan en xml_plan)

Respuesta (200):

JSON
{
  "status": "success",
  "status_code": "0",
  "message": "1 results",
  "data": {
    "results": 1,
    "diagrams": [
      {"id":3120,"client_id":null,"date_created":"2025-03-02 12:35:10.000","date_created_iso":"2025-03-02T12:35:10.000+01:00","date_updated":"2026-10-14 09:12:44.000","date_updated_iso":"2026-10-14T09:12:44.000+02:00","name":"Horario oficina","comment":null,"snapshot_width":1280,"snapshot_height":720}
    ],
    "has_more": false,
    "next_from_id": 3120,
    "next_cursor": "3120"
  }
}

Sin id, devuelve tus diagramas en orden de id, con cursor (Paginación con cursor). Con id, solo ese y sin cursor (has_more false y next_from_id null).

Errores propios: 404 Diagram not found (con id).

VozPush: llamadas automáticas#

VozPush lanza llamadas automáticas a una lista de números siguiendo un plan (una locución, un menú de teclas, una transferencia a un agente…). Una campaña es un lanzamiento a uno o varios destinatarios.

POST /v3/campaigns — lanzar una campaña#

POST https://api.mundosms.es/v3/campaigns

Permiso: write, vozpush o sendcall.

Parámetro Tipo Obligatorio Qué es
to texto o lista sí los destinatarios
diagram_id entero sí, o xml_plan el diagrama que siguen las llamadas
xml_plan texto sí, o diagram_id el plan en XML (el que exporta el editor de diagramas del panel)
from texto no el número que se presenta. Tiene que ser tuyo (un DID o un número verificado)
client_id texto no tu referencia (hasta 20 caracteres)
name, description texto no para reconocerla en el panel
date_scheduled fecha no cuándo lanzarla. Sin ella, ahora. (date_start, el nombre anterior, da 400: ahora date_* es la ventana)
date_window_start, date_window_end fecha no días entre los que se puede llamar, AAAA-MM-DD
time_window_start, time_window_end hh:mm no horas entre las que se puede llamar
weekdays lista no qué días de la semana se puede llamar: siete true/false, de lunes a domingo. También vale el texto del panel, siete 1 o 0 separados por barras verticales
max_concurrent entero no llamadas a la vez
delay_calls entero no segundos entre llamada y llamada
retry_delay_min entero no minutos antes de reintentar un destinatario
max_no_answer, max_busy, max_unreachable, max_answering_machine, max_fax, max_total_retries entero no reintentos por motivo y en total
replace_vars, var1 … var8 no personalización del plan por destinatario
url_callback texto no URL tuya (https://, pública, hasta 250 caracteres) a la que avisamos cuando la campaña termina o se cancela (qué llega)
url_callback_single_failed texto no URL tuya (hasta 250 caracteres) a la que avisamos cuando un destinatario falla del todo (por ejemplo, para mandarle un SMS) (qué llega)
skip_errors, show_errors sí/no no seguir aunque el plan tenga avisos; devolverlos en xml_errors

Las llamadas salen siempre por la ruta 1 (route se acepta y se ignora).

Petición:

HTTP
POST /v3/campaigns
Content-Type: application/json

{"to":["34600123456","34600123457"],"diagram_id":3120,"from":"34910123456","client_id":"recordatorio-1120","time_window_start":"09:00","time_window_end":"20:00","weekdays":[true,true,true,true,true,false,false]}

Respuesta (200):

JSON
{"status":"success","status_code":"0","message":"OK","data":{"id":991250,"client_id":"recordatorio-1120","state":"in_progress","cost":0.0,"balance":120.35}}

state es in_progress o scheduled (con date_scheduled). Una campaña grande puede partirse en varias: entonces id es la primera y ids, la lista de todas. Con show_errors, los avisos del plan van en xml_errors.

Errores propios: 400 Parameters not valid (con detail), 400 Parameter xml_plan not valid (con detail: los avisos del plan), 403 Caller ID not verified, 404 Diagram not found, 402 Insufficient credit.

GET /v3/campaigns/{id} — estado de una campaña#

GET https://api.mundosms.es/v3/campaigns/{id}

Permiso: read, vozpush o getreport_call. Para pausar, reanudar o cancelar: write, vozpush o getreport_call (con read se consulta, pero no se controla; getreport_call deja las dos cosas).

También: GET /v3/campaigns — la campaña con tu referencia (?client_id=…); POST /v3/campaigns/{id}/pause — pausarla; POST /v3/campaigns/{id}/resume — reanudarla; POST /v3/campaigns/{id}/cancel — cancelarla.

Parámetro Tipo Obligatorio Qué es
id entero sí la campaña (en la ruta)
client_id texto no en GET /v3/campaigns: tu referencia, para buscar la campaña sin saber su id

Petición:

HTTP
GET /v3/campaigns/991250

Respuesta (200):

JSON
{
  "status": "success",
  "status_code": "0",
  "message": "OK",
  "data": {
    "id": 991250,
    "client_id": "recordatorio-1120",
    "state": "finished",
    "cost": 0.18,
    "answered_count": 1,
    "failed_count": 1,
    "date_last_update": "2026-11-20 09:04:51.000",
    "date_last_update_iso": "2026-11-20T09:04:51.000+01:00",
    "duration_total": 74,
    "duration_functions": 74,
    "duration_mobile": 74,
    "duration_landline": 0,
    "duration_sip": 0,
    "results": [
      {"to":"34600123456","state":"answered","recording_id":null,"ivr_keys":"1"},
      {"to":"34600123457","state":"no_answer","recording_id":null,"ivr_keys":null}
    ]
  }
}

Estados de la campaña (state): scheduled, in_progress, paused, finished, cancelled, failed. Estados de cada destinatario (results[].state): los de una llamada (ringing, talking, answered, no_answer, busy, unreachable, cancelled, rejected, failed…) más scheduled, paused, answering_machine y fax. recording_id es la grabación de esa llamada, si la hubo, e ivr_keys, las teclas que pulsó el destinatario.

Al pausar, reanudar o cancelar (POST /v3/campaigns/{id}/pause, /resume, /cancel, sin cuerpo), la respuesta es data: {id, client_id, state} con el estado nuevo.

Errores propios: 404 Campaign not found, 409 Not possible in the current state (por ejemplo, reanudar una terminada), 403 Not allowed (pausar, reanudar o cancelar con una clave de solo lectura).

GET /v3/campaigns/{id}/calls/{to}/recording — grabación de una llamada de VozPush#

GET https://api.mundosms.es/v3/campaigns/{id}/calls/{to}/recording

Permiso: read, vozpush o getrecording_vozpush.

Parámetro Tipo Obligatorio Qué es
id entero sí la campaña (en la ruta)
to texto sí el destinatario (en la ruta)
mode_out texto no inline (por defecto), download o base64
filename texto no el nombre del fichero, sin extensión

Con base64, data es {id, client_id, to, filename, content_type, size, base64}, como en GET /v3/calls/{type}/{id}/recording.

Errores propios: 404 Call not found, 404 Recording not found.

SMS#

Estados de un SMS#

Cada envío (POST /v3/sms) puede ir a varios destinatarios. El envío tiene un estado y cada destinatario, el suyo.

Estado del envío (GET /v3/sms/sends/{id}) Qué es
scheduled programado para más tarde
in_progress enviándose, o esperando los informes de entrega
completed terminado: todos los destinatarios tienen resultado (o pasaron 15 días)
failed falló entero
cancelled se canceló antes de salir
Estado de un destinatario (GET /v3/sms) Qué es
pending aún no ha salido hacia el operador
sent salió y el operador no ha mandado todavía el informe de entrega. Algunas rutas no dan informe: entonces se queda en sent
delivered entregado en el teléfono
failed no se entregó; el motivo, en error_code

POST /v3/sms — enviar SMS#

POST https://api.mundosms.es/v3/sms

Permiso: write, sms o sendsms.

Parámetro Tipo Obligatorio Qué es
to texto o lista sí los destinatarios
text texto sí el mensaje
from texto no el remitente: de 1 a 11 caracteres
client_id texto no tu referencia, hasta 50 caracteres
date_scheduled fecha no cuándo enviarlo; sin ella, ahora. Una fecha que no vale da 400 (no se envía)
url_callback texto no URL tuya (https://, pública, hasta 150 caracteres) a la que avisamos del informe de entrega de cada destinatario (qué llega). Sin ella, la URL de avisos de tu cuenta, si la tienes
route entero no la ruta: 1, 2, 3 o 4
concatenated sí/no no permitir mensajes de más de 160 caracteres (varias partes)
unicode sí/no no enviar en Unicode (emojis, alfabetos no latinos; 70 caracteres por parte)
keep_sms_size sí/no no no partir el mensaje: recortarlo a una parte
expire_secs entero no segundos tras los que el operador deja de intentarlo
type texto no sms (por defecto) o rcs_simple
replace_vars, var1 … var8 texto no un texto distinto para cada destinatario (abajo)
gsmcharset_table, gsmcharset_extension no tabla de caracteres

Petición:

HTTP
POST /v3/sms
Content-Type: application/json

{"to":["34600123456","34600123457"],"text":"Tu cita es mañana a las 10:00. Responde NO para anularla.","from":"Clinica","client_id":"cita-88123"}

Respuesta (200):

JSON
{"status":"success","status_code":"0","message":"OK","data":{"id":71234567,"client_id":"cita-88123","state":"in_progress","cost":0.14,"balance":120.21}}

id es nuestro identificador del envío, para GET /v3/sms/sends/{id}, GET /v3/sms y POST /v3/sms/sends/{id}/send-now. state es in_progress o scheduled (con date_scheduled).

Un texto distinto para cada destinatario (replace_vars y var1 … var8):

  • En replace_vars van los marcadores que quieras sustituir, separados por |. El marcador es el texto que tú elijas ([NOMBRE], #CITA#…): se busca tal cual en text.
  • En var1 van los valores del primer marcador, uno por destinatario y en el mismo orden que to, separados por |; en var2, los del segundo, y así hasta ocho marcadores.
  • Cada destinatario paga según la longitud de su texto, ya sustituido.
JSON
{"to":["34600123456","34600123457"],"text":"Hola [NOMBRE], te esperamos el [DIA].","from":"MiClinica",
 "replace_vars":"[NOMBRE]|[DIA]","var1":"Ana|Luis","var2":"lunes|martes"}

Ana recibe «Hola Ana, te esperamos el lunes.» y Luis, «Hola Luis, te esperamos el martes.».

Errores propios: 400 Parameter to not valid, 400 Parameter from not valid, 400 Parameter client_id not valid, 400 Parameter date_scheduled not valid, 400 Parameter route not valid, 402 Insufficient credit, 403 RCS not enabled for this account.

POST /v3/sms/certified — enviar un SMS certificado#

POST https://api.mundosms.es/v3/sms/certified

Un SMS con certificado de envío y entrega con validez como prueba. Mismos parámetros y respuesta que POST /v3/sms, más:

Permiso: write, sms o sendsms_cert.

Parámetro Tipo Obligatorio Qué es
cert_name texto sí a nombre de quién se emite el certificado
cert_type texto no el tipo de certificado (D por defecto)
cert_tax_id texto no NIF/CIF del titular
cert_language texto no idioma del certificado (ES por defecto)
cert_email texto no correo al que se envía el certificado

Va siempre por la ruta 1 (route se ignora). Ojo: el id de un SMS certificado es de otra serie que el de POST /v3/sms; GET /v3/sms/sends/{id} y GET /v3/sms no lo encuentran. Por la API no se puede consultar: el certificado se envía al correo de cert_email.

POST /v3/sms/quote — calcular el coste antes de enviar#

POST https://api.mundosms.es/v3/sms/quote

Mismos parámetros que POST /v3/sms; no envía nada.

Permiso: read, sms o quotesms.

Respuesta (200):

JSON
{"status":"success","status_code":"0","message":"OK","data":{"cost":0.14,"balance":120.35}}

cost es lo que costaría el envío y balance, tu saldo. Errores propios: 400 Parameter to not valid (también si algún destino no tiene precio).

GET /v3/sms/sends — estado de tus envíos#

GET https://api.mundosms.es/v3/sms/sends Pruébalo

Permiso: read, sms o getreport.

También: GET /v3/sms/sends/{id} — uno solo, por su id.

Parámetro Tipo Obligatorio Qué es
id lista sí, o client_id nuestros ids de envío, uno o varios, separados por comas
client_id lista sí, o id tus referencias, una o varias, separadas por comas

Hasta 100 ids y referencias por petición.

Petición:

HTTP
GET /v3/sms/sends?id=71234567,71234568

Respuesta (200):

JSON
{
  "status": "success",
  "status_code": "0",
  "message": "OK",
  "data": {
    "results": 2,
    "sms": [
      {"id":71234567,"client_id":"cita-88123","state":"completed","delivered":["34600123456"],"failed":["34600123457"]},
      {"id":71234568,"client_id":null,"error":{"status_code":"4","message":"SMS not found"}}
    ]
  }
}

Cada envío que no existe lleva su error y la respuesta sigue siendo 200. Con uno solo (GET /v3/sms/sends/71234567), si no existe: 404 SMS not found. El detalle por destinatario, con sus horas, lo da GET /v3/sms con send_id.

Estados del envío (state): scheduled, in_progress, completed, failed y cancelled.

Errores propios: 400 Parameter id not valid (tu referencia va en client_id), 400 Too many ids, 404 SMS not found.

POST /v3/sms/sends/{id}/send-now — enviar ya un envío programado#

POST https://api.mundosms.es/v3/sms/sends/{id}/send-now

Adelanta a ahora un envío programado (date_scheduled) que aún no ha salido.

Permiso: write, sms o scheduled_sendings.

También: POST /v3/sms/sends/{id}/cancel — cancelarlo: no sale y se devuelve el saldo.

Parámetro Tipo Obligatorio Qué es
id entero sí nuestro id del envío (en la ruta). Si solo tienes tu referencia, búscalo antes con GET /v3/sms/sends?client_id=…

Petición:

HTTP
POST /v3/sms/sends/71234570/send-now

Respuesta (200):

JSON
{"status":"success","status_code":"0","message":"OK","data":{"id":71234570,"client_id":"campana-black-friday","state":"in_progress"}}

Con /cancel, state es cancelled.

Errores propios: 404 SMS not found, 409 SMS already sent, 409 SMS already cancelled.

GET /v3/sms — SMS enviados, uno por destinatario#

GET https://api.mundosms.es/v3/sms Pruébalo

Los SMS enviados, un elemento por destinatario, con su estado y las horas de cada paso. Sirve para «los SMS de este contacto», para ver qué pasó con un envío o para sincronizar los SMS con un CRM.

Cada elemento es un SMS de un envío a un destinatario: se identifica por send_id + to.

Si un SMS no se entrega, a veces se reintenta por otra ruta sin coste para ti. Sale una sola vez:

  • con las horas de creación y envío de cuando lo mandaste;
  • con el estado del intento que mejor fue (delivered, luego sent, luego pending, luego failed; si empatan, el primero);
  • con la hora real del informe de entrega.

state filtra por ese estado: un SMS que falló y se entregó al reintentar es delivered.

Permiso: read, sms o getreport.

Parámetro Tipo Obligatorio Qué es
cursor texto no el next_cursor de la página anterior: la página siguiente
from_id entero no lo mismo que cursor, como número (por compatibilidad)
limit entero no 1-500, 50 por defecto
order texto no asc o desc
from_datetime, to_datetime fecha no por hora de creación: desde (incluida) y hasta (sin incluir)
number texto no un destinatario
send_id entero no los de un envío (el id que devolvió POST /v3/sms)
client_id texto no los del envío con esa referencia tuya
state texto no pending, sent, delivered o failed
include_text sí/no no true (por defecto): con el texto de cada mensaje

Petición:

HTTP
GET /v3/sms?number=34600123456&order=desc&limit=10

Respuesta (200):

JSON
{
  "status": "success",
  "status_code": "0",
  "message": "1 results",
  "data": {
    "results": 1,
    "messages": [
      {
        "send_id": 71234567,
        "client_id": "cita-88123",
        "from": "Clinica",
        "to": "34600123456",
        "text": "Tu cita es mañana a las 10:00. Responde NO para anularla.",
        "parts": 1,
        "credits": 0.07,
        "state": "delivered",
        "error_code": null,
        "date_created": "2026-11-20 09:00:00.412",
        "date_created_iso": "2026-11-20T09:00:00.412+01:00",
        "date_sent": "2026-11-20 09:00:01.030",
        "date_sent_iso": "2026-11-20T09:00:01.030+01:00",
        "date_accepted": "2026-11-20 09:00:01.311",
        "date_accepted_iso": "2026-11-20T09:00:01.311+01:00",
        "date_report": "2026-11-20 09:00:04.870",
        "date_report_iso": "2026-11-20T09:00:04.870+01:00",
        "date_operator": "2026-11-20 09:00"
      }
    ],
    "has_more": false,
    "next_from_id": null,
    "next_cursor": null
  }
}
Campo Qué es
send_id, to el envío al que pertenece y el destinatario: juntos identifican el SMS
client_id tu referencia del envío
parts, credits en cuántas partes salió y lo que costó (los reintentos no se cobran)
state, error_code ver Estados de un SMS; error_code solo si falló
date_created cuándo lo recibimos
date_sent cuándo salió hacia el operador
date_accepted cuándo lo aceptó el operador
date_report cuándo llegó el informe de entrega
date_operator la hora de entrega que pone el operador en su informe, a minuto (AAAA-MM-DD hh:mm, hora de Madrid)

Errores propios: 400 Parameter <nombre> not valid (con detail).

GET /v3/sms/replies — respuestas a tus SMS#

GET https://api.mundosms.es/v3/sms/replies Pruébalo

Los SMS que te contestan los destinatarios, con el envío al que responden.

Hoy no hay SMS de vuelta: ningún número recibe SMS, así que la lista sale vacía. La ruta se mantiene por compatibilidad.

Permiso: read, sms o getreport.

Parámetro Tipo Obligatorio Qué es
cursor texto no el next_cursor de la página anterior: la página siguiente
from_id entero no lo mismo que cursor, como número (por compatibilidad)
limit entero no 1-500, 50 por defecto
order texto no asc o desc
from_datetime, to_datetime fecha no por hora de recepción
number texto no quien responde
send_id entero no las respuestas a un envío

Petición:

HTTP
GET /v3/sms/replies?order=asc&limit=100

La página siguiente, con cursor = el next_cursor de esta. Hoy la lista sale vacía (results 0); así es cada respuesta cuando las haya.

Respuesta (200):

JSON
{
  "status": "success",
  "status_code": "0",
  "message": "1 results",
  "data": {
    "results": 1,
    "replies": [
      {
        "from": "34600123456",
        "to": "34600999888",
        "text": "NO",
        "date_received": "2026-11-20 09:12:40.000",
        "date_received_iso": "2026-11-20T09:12:40.000+01:00",
        "reply_to": {"send_id": 71234567}
      }
    ],
    "has_more": false,
    "next_from_id": 30111,
    "next_cursor": "30111"
  }
}

reply_to es el envío al que responde (send_id), o null si no se pudo saber. El SMS es el de ese envío a quien responde: en GET /v3/sms, send_id y to = el from de la respuesta. to es nuestro número que recibió la respuesta.

Errores propios: 400 Parameter <nombre> not valid (con detail).

NumCheck#

POST /v3/numchecks — comprobar un número de móvil#

POST https://api.mundosms.es/v3/numchecks

Comprueba si un móvil existe y está activo y en qué operador está, sin llamarlo ni enviarle nada. El resultado llega a tu url_callback.

Permiso: write, numcheck o numcheck.

Parámetro Tipo Obligatorio Qué es
number texto sí el número, en formato internacional. Uno por petición
url_callback texto no URL tuya (https://, pública, hasta 150 caracteres) a la que enviamos el resultado (qué llega)
client_id texto no tu referencia, hasta 30 caracteres

Petición:

HTTP
POST /v3/numchecks
Content-Type: application/json

{"number":"34600123456","url_callback":"https://crm.ejemplo.com/numcheck","client_id":"limpieza-nov"}

Respuesta (200):

JSON
{"status":"success","status_code":"0","message":"OK","data":{"id":551230,"client_id":"limpieza-nov","cost":0.02,"balance":120.33}}

Errores propios: 400 Parameter number not valid (también con una lista: es uno por petición), 402 Insufficient credit.

WhatsApp#

Envía WhatsApp desde tu sistema con el número de tu empresa conectado en el panel (WhatsApp → Números). La autenticación es la de toda la API: una clave de API creada en el panel (API y Soporte → Claves de API) con permiso de WhatsApp.

  • Dirección: https://api.mundosms.es/v3/whatsapp/… (las rutas, abajo).
  • Cabeceras: Authorization: Bearer <token> y, si tu clave exige firma, X-Timestamp y X-Signature.
  • En GET, los parámetros van en la query; en POST, en el cuerpo JSON.
  • Respuesta: JSON con status (success | error), status_code ("0" = correcto), message, detail en algunos errores, y los datos dentro de data. Cada respuesta lleva su código HTTP (tabla de códigos, abajo).

Las rutas de WhatsApp#

ruta qué hace permiso
GET /v3/whatsapp/numbers tus números de WhatsApp whatsapp_numbers
GET /v3/whatsapp/templates las plantillas de un número y su estado whatsapp_templates
POST /v3/whatsapp/messages enviar un mensaje whatsapp_send
GET /v3/whatsapp/messages/{message_id} el estado de un mensaje whatsapp_status
POST /v3/whatsapp/campaigns crear un envío masivo whatsapp_campaign
GET /v3/whatsapp/campaigns/{campaign_id} el estado de un envío masivo whatsapp_campaign
POST /v3/whatsapp/campaigns/{campaign_id}/pause pausarlo (también /resume y /cancel) whatsapp_campaign

Permisos de WhatsApp#

permiso qué permite
whatsapp todo lo de WhatsApp
whatsapp_send enviar mensajes
whatsapp_campaign crear, consultar y controlar envíos masivos
whatsapp_status, whatsapp_templates, whatsapp_numbers las consultas de cada ruta
all todo, como en el resto de la API

Una clave con read o write a secas (las de SMS o voz) no entra a WhatsApp. Con «Todo» en la ficha de la clave, o marcando a la vez «Todas las consultas» y «Todas las acciones», se guarda como all, y all sí entra.

Firma, ejemplos y errores de autenticación#

Son los de toda la API: La firma, Ejemplos completos (la función mundosms() vale tal cual: mundosms("GET", "/v3/whatsapp/templates", {"account_id": 12})) y Errores de autenticación. Dos diferencias:

  • En WhatsApp, cada petición firmada vale una sola vez con cualquier clave que firme, exija ts o no: para reintentar, vuelve a firmar con un X-Timestamp nuevo.
  • Sin permiso para la ruta, el 403 dice cuál falta: Not allowed whatsapp_send.

Para n8n hay un workflow listo para importar, con la firma hecha: n8n-whatsapp-plantillas-firmada.json (pídenoslo si no lo tienes).

Códigos de WhatsApp: status_code y HTTP#

HTTP status_code qué pasa qué hacer
200 0 correcto —
400 3 parámetros que faltan o no valen (detail dice qué) corrige la petición
401, 403, 409 3 autenticación, permiso o petición repetida (tabla anterior) —
404 4 no encontrado en tu cuenta (número, plantilla, mensaje, envío masivo o ruta) —
402 5 sin saldo (Insufficient Credit) recarga
422 6 la plantilla no cumple las reglas de WhatsApp —
429 7 demasiadas peticiones seguidas reintenta pasados los segundos de la cabecera Retry-After
409 8 fuera de las 24 h: el cliente no te ha escrito en las últimas 24 h manda una plantilla
402 9 el número no tiene la cuota mensual activa (data.reason: pending o expired) actívala en el panel
402 10 mensajes del mes agotados y el número no admite exceso (data.used, data.included) activa el exceso en el panel o espera al día 1
202 11 WhatsApp no contestó y el mensaje puede haber salido consulta GET /v3/whatsapp/messages/{message_id} con data.id antes de reintentar
422 12 WhatsApp lo rechazó (data.whatsapp_error_code, p. ej. 131026: ese teléfono no tiene WhatsApp) no reintentes
503 12 WhatsApp lo rechazó por un límite pasajero (data.retry es true) reintenta pasados los segundos de Retry-After
503 2 sin conexión con WhatsApp en ese momento (data.retry es true) reintenta en unos segundos
500 2 error interno —
  • Si el mensaje llegó a crearse, el error trae su data.id. detail lleva el texto original del error para el soporte, sin traducir.
  • El 11 va con 202 a propósito: el mensaje puede haber salido, y un 5xx haría que muchas herramientas lo repitieran solas (en n8n, «Retry on fail») y el cliente lo recibiría dos veces. Si tu herramienta reintenta, que solo lo haga con data.retry a true. Si un 11 no trae data.id (un fichero que tardó más de 50 s en descargarse y subirse), míralo en el Historial del panel.

GET /v3/whatsapp/numbers — tus números#

GET https://api.mundosms.es/v3/whatsapp/numbers

Permiso: whatsapp o whatsapp_numbers.

curl (bash)
curl -s https://api.mundosms.es/v3/whatsapp/numbers -H "Authorization: Bearer $TOKEN"
JSON
{"status":"success","status_code":"0","message":"OK",
 "data":{"numbers":[{"account_id":12,"number":"+34 881 92 28 02","name":"Clínica Sonríe",
  "quality":"GREEN","messaging_limit":"TIER_1K","coexistence":true,
  "monthly_fee":{"state":"active","active":true,"until":"2026-12-10","auto_renew":true},
  "monthly_usage":{"used":2350,"included":10000,"overage_allowed":true}}]}}
  • account_id sirve para elegir número en las demás rutas; si no lo indicas, se usa el primero.
  • monthly_fee.state: exempt, trial (primer mes gratis), active, pending o expired. Sin la cuota activa, los envíos dan 9.
  • monthly_usage: los mensajes de conversación del mes (los que recibes y los que contestas); included es null si el número no tiene límite. Agotados (included) y con overage_allowed a false, los textos dan 10. Las plantillas se cobran aparte y siguen saliendo.

GET /v3/whatsapp/templates — plantillas y su estado#

GET https://api.mundosms.es/v3/whatsapp/templates

Permiso: whatsapp o whatsapp_templates.

curl (bash)
curl -s "https://api.mundosms.es/v3/whatsapp/templates?account_id=12" \
  -H "Authorization: Bearer $TOKEN"

Devuelve data.templates. Cada una trae:

  • name, language y body;
  • category: utility, marketing o authentication;
  • status: approved, pending o rejected;
  • vars: cuántos huecos {{1}}, {{2}}… hay que rellenar.

Las plantillas se crean en el panel (WhatsApp → Plantillas), también las que llevan una foto, un vídeo o un documento en la cabecera.

POST /v3/whatsapp/messages — enviar un mensaje#

POST https://api.mundosms.es/v3/whatsapp/messages

Permiso: whatsapp o whatsapp_send.

Todo envío lleva to (el teléfono, con prefijo de país) y type. Esto es lo que puedes enviar:

type qué recibe el cliente cuándo
template una plantilla aprobada, con su cabecera (texto, foto, vídeo o documento), sus botones y los códigos de las de autenticación siempre
text un texto, hasta 4.096 caracteres 24 h
image, video, audio, document, sticker una foto, un vídeo, un audio o nota de voz, un documento o un sticker 24 h
location un punto en el mapa (tu tienda, la clínica…) 24 h
contacts una o varias tarjetas de contacto para guardar 24 h
buttons un texto con hasta 3 botones de respuesta 24 h
list un menú de hasta 10 opciones 24 h
cta_url un texto con un botón que abre una web 24 h
location_request un botón para que el cliente te envíe su ubicación 24 h
reaction un emoji sobre un mensaje del cliente 24 h

«24 h» quiere decir solo dentro de las 24 h desde el último mensaje del cliente; fuera, vuelve el código 8 y hace falta una plantilla. Cualquier tipo menos reaction puede citar un mensaje con reply_to (ver más abajo).

Para escribir primero a un cliente, o pasadas 24 h desde su último mensaje, una plantilla:

curl (bash)
curl -s https://api.mundosms.es/v3/whatsapp/messages \
  -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  -d '{"to":"34600000001","type":"template",
       "template":{"name":"confirmacion_cita","language":"es","vars":["Ana","martes 16","17:30"]},
       "client_id":"cita-881"}'

Si el cliente te escribió en las últimas 24 h, también texto libre:

curl (bash)
-d '{"to":"34600000001","type":"text","text":"Hola Ana, ¿en qué te ayudamos?"}'

Todos los tipos responden igual:

JSON
{"status":"success","status_code":"0","message":"OK",
 "data":{"id":123,"wamid":"wamid.HBgL…","credits":0.2}}
  • id: el del mensaje, para consultar su estado.
  • wamid: el identificador de WhatsApp.
  • credits: lo que se ha descontado de tu saldo. Una plantilla cuesta créditos; lo demás entra en los mensajes del mes, y pasado el límite se cobra como exceso si el número lo admite.
  • to: con prefijo de país. Valen + y espacios, y un móvil español de 9 cifras se completa con 34.
  • client_id: tu referencia libre (hasta 100 caracteres), que vuelve al consultar el mensaje.
  • account_id: el número desde el que sale; si no lo indicas, el primero.
  • Si algo no cumple los límites de WhatsApp (un botón de más, un título largo), vuelve 400 y detail dice qué.

Plantillas con cabecera, botones y códigos

Además de los huecos del cuerpo (vars, en orden), una plantilla puede necesitar más datos, según cómo se aprobó:

curl (bash)
-d '{"to":"34600000001","type":"template",
     "template":{"name":"cita_con_enlace","language":"es","vars":["Ana","martes 16"],
                 "header":"Recordatorio","buttons":[{"index":0,"url":"cita/881"}]}}'
-d '{"to":"34600000001","type":"template",
     "template":{"name":"factura_mensual","language":"es","vars":["881"],
                 "header":{"type":"document","filename":"factura-881.pdf",
                           "url":"https://erp.ejemplo.es/facturas/881.pdf"}}}'
-d '{"to":"34600000001","type":"template",
     "template":{"name":"codigo_acceso","language":"es","code":"482913"}}'
  • header: si la cabecera de la plantilla es de texto con un hueco, el texto que va en él. Si es una foto, vídeo o documento, el fichero: {"type":"image"|"video"|"document","url":…,"filename":…} (o base64 en vez de url), con las mismas reglas que los ficheros de abajo. Una plantilla con documento en la cabecera no sale sin él: vuelve 400 diciéndolo.
  • Las plantillas con foto, vídeo o documento en la cabecera se crean en el panel (WhatsApp → Plantillas → Nueva, «Cabecera»): WhatsApp pide un fichero de ejemplo para revisarlas, y luego en cada envío va el de verdad.
  • buttons: los botones que llevan un dato, cada uno por su posición (index, empezando en 0): url (lo que se añade al final de la dirección del botón), payload (lo que te llega cuando el cliente pulsa una respuesta rápida) o coupon_code (el cupón de un botón de copiar código).
  • code: en las plantillas de autenticación, el código. Va al texto y al botón de copiar a la vez.
  • La categoría de la plantilla es la que WhatsApp le aprobó: no se elige al enviar.

Documentos, fotos, vídeos, audios y stickers

El fichero puede ir de dos maneras: con su dirección (url), y lo descargamos nosotros, o dentro del JSON en base64. Lo más cómodo, si el fichero ya está en tu servidor o en un almacenamiento como S3, es la dirección:

curl (bash)
-d '{"to":"34600000001","type":"document","client_id":"fra-881",
     "document":{"filename":"factura-881.pdf","url":"https://erp.ejemplo.es/facturas/881.pdf",
                 "caption":"Tu factura de noviembre"}}'
-d '{"to":"34600000001","type":"document","client_id":"fra-881",
     "document":{"filename":"factura-881.pdf","base64":"JVBERi0xLjQK…",
                 "caption":"Tu factura de noviembre"}}'
-d '{"to":"34600000001","type":"image",
     "image":{"url":"https://cdn.ejemplo.es/obras/salon.jpg","caption":"Así queda"}}'
-d '{"to":"34600000001","type":"audio",
     "audio":{"filename":"respuesta.ogg","base64":"T2dnUwACAAAA…","voice":true}}'
type formatos tamaño máximo caption
document pdf, doc, docx, xls, xlsx, ppt, pptx, txt 16 MB sí
image jpg, png 5 MB sí
video mp4, 3gp 16 MB sí
audio ogg (opus), mp3, m4a, aac, amr 16 MB no
sticker webp 500 KB no
  • url (o link, como lo llama WhatsApp): la dirección del fichero. Tiene que ser https y de un servidor público; vale un enlace firmado que caduque (de S3, por ejemplo), siempre que siga vivo unos minutos. Se descarga una vez, en el momento del envío, y si no se puede el envío no sale y vuelve el código 3 con el motivo en detail: la dirección da un error (HTTP 404), devuelve una página web en vez del fichero (un enlace caducado o que pide iniciar sesión), tarda más de 15 s, pasa del tamaño máximo o apunta a una red privada.
  • base64: el fichero entero, en vez de url. Se admiten saltos de línea y el prefijo data:application/pdf;base64,. Uno de los dos, no los dos a la vez.
  • filename: el tipo sale de su extensión, y es el nombre que verá el cliente en los documentos. Con base64 es obligatorio en los documentos; con url es opcional (si falta, se usa el nombre que dé tu servidor y, si no da ninguno, documento.pdf). En las fotos y los stickers es opcional, porque el tipo se reconoce por el contenido.
  • voice: true: el audio llega como nota de voz, como si la hubieras grabado en el móvil. Tiene que ser ogg (opus).
  • caption: el texto que acompaña al fichero, opcional, hasta 1.024 caracteres.
  • Se comprueba que el contenido sea lo que dice el nombre: un fichero que no es un PDF de verdad pero se llama .pdf vuelve con código 3, y detail dice el motivo. Lo mismo un tipo no admitido o un fichero demasiado grande.
  • Si WhatsApp no acepta el fichero al subirlo, vuelve el código 12 con data.whatsapp_error_code, y no se ha enviado nada.
  • Si la descarga y la subida tardan más de 50 s, vuelve el código 11 sin data.id: el envío puede completarse después. No lo repitas sin mirar antes el Historial del panel.
  • Una vez enviado, el fichero aparece en el Historial del panel como si lo hubieras mandado desde allí. También el que enviaste por url: el Historial enseña el fichero que se envió, aunque tu enlace caduque después.

Ubicación y contactos

curl (bash)
-d '{"to":"34600000001","type":"location","location":{"latitude":42.8782,"longitude":-8.5448,
     "name":"Clínica Sonríe","address":"Rúa Nova 12, Santiago"}}'
-d '{"to":"34600000001","type":"contacts",
     "contacts":[{"name":"Recepción Clínica Sonríe","emails":["citas@clinicasonrie.es"],
                  "phones":[{"phone":"+34 881 92 28 02","type":"WORK"}]}]}'
  • location: latitude y longitude en grados decimales; name y address son opcionales.
  • contacts: una lista de 1 a 20 tarjetas. Solo el nombre es obligatorio. Puedes dar name como texto o como {"formatted_name","first_name","last_name"}, y añadir phones, emails, urls, org (company, department, title), addresses y birthday (AAAA-MM-DD). Si añades wa_id a un teléfono, el cliente ve el botón de escribirle por WhatsApp.

Botones, listas y enlaces

curl (bash)
-d '{"to":"34600000001","type":"buttons",
     "buttons":{"text":"¿Confirmas tu cita del martes a las 17:30?","footer":"Clínica Sonríe",
                "options":[{"id":"si","title":"Sí, confirmo"},
                           {"id":"cambiar","title":"Cambiar la hora"}]}}'
-d '{"to":"34600000001","type":"list",
     "list":{"text":"¿Qué día te viene mejor?","button":"Ver días",
             "sections":[{"title":"Esta semana","rows":[
                 {"id":"mar","title":"Martes","description":"de 16:00 a 20:00"},
                 {"id":"jue","title":"Jueves","description":"de 9:00 a 14:00"}]}]}}'
-d '{"to":"34600000001","type":"cta_url",
     "cta_url":{"text":"Tu factura de noviembre ya está lista.","button":"Ver factura",
                "url":"https://www.ejemplo.es/f/881"}}'
-d '{"to":"34600000001","type":"location_request",
     "location_request":{"text":"¿Dónde te recogemos?"}}'
  • buttons: el texto (hasta 1.024 caracteres) y de 1 a 3 options, cada una con su title (hasta 20 caracteres, distintos entre sí) y su id (lo que te llega cuando el cliente pulsa; si no lo das, es el título). Opcionales: header (un texto de hasta 60 caracteres, o una foto, vídeo o documento como en las plantillas) y footer (hasta 60).
  • list: el texto (hasta 4.096), el botón que abre el menú (button, hasta 20) y las opciones: hasta 10 en total, en sections (cada una con su title, hasta 24) o, si es una sola, directamente en rows. Cada opción lleva title (hasta 24), id (hasta 200) y, si quieres, description (hasta 72). Opcionales: header (texto) y footer.
  • cta_url: el texto, el botón (button, hasta 20) y la dirección que abre (url, http o https). Así la dirección no aparece en el texto. Opcionales: header (texto) y footer.
  • location_request: el texto. El cliente ve un botón para enviar su ubicación, y te llega como cualquier ubicación.
  • Lo que el cliente elige te llega por el webhook (respuesta_boton o respuesta_lista, con el id de la opción), igual que su ubicación (ubicacion). Está documentado en https://www.mundosms.es/whatsapp-webhook.

Reacciones y responder citando

curl (bash)
-d '{"to":"34600000001","type":"reaction","reaction":{"message_id":812,"emoji":"👍"}}'
-d '{"to":"34600000001","type":"text","text":"Sí, abrimos el sábado de 10 a 14.","reply_to":812}'
  • reaction: un emoji sobre un mensaje del cliente de los últimos 30 días.
  • reply_to: el mensaje que se cita, como cuando en WhatsApp mantienes pulsado y das a «Responder». Vale en cualquier tipo menos reaction, y puede ser un mensaje del cliente o uno tuyo.
  • En los dos, el mensaje se indica con su id (el que te llega en el webhook o te devolvió el envío) o con su wamid. Tiene que ser de la conversación con ese mismo to; si no, vuelve 404.

GET /v3/whatsapp/messages/{message_id} — estado de un mensaje#

GET https://api.mundosms.es/v3/whatsapp/messages/{message_id}

Permiso: whatsapp o whatsapp_status.

curl (bash)
curl -s https://api.mundosms.es/v3/whatsapp/messages/123 -H "Authorization: Bearer $TOKEN"
JSON
{"status":"success","status_code":"0","message":"OK",
 "data":{"id":123,"to":"34600000001","type":"template","template":"confirmacion_cita",
  "state":"delivered","error_code":null,"error":null,"wamid":"wamid.HBgL…","credits":0.2,
  "client_id":"cita-881",
  "date_created":"2026-11-11 10:30:00.000","date_created_iso":"2026-11-11T10:30:00.000+01:00",
  "date_updated":"2026-11-11 10:30:04.000","date_updated_iso":"2026-11-11T10:30:04.000+01:00"}}

Los valores de state:

  • pending: creado. Si se queda así tras un 11, WhatsApp no ha dicho nada todavía.
  • accepted → sent → delivered → read.
  • failed: WhatsApp no pudo entregarlo, con error_code y error.
  • rejected: no salió.
  • excluded: el destinatario se dio de baja.

Las fechas salen como en el resto de la API: en hora de Madrid con milisegundos, y la misma en ISO 8601 con su zona (_iso). Un mensaje que no es de tu cuenta, o que no existe, da 404.

POST /v3/whatsapp/campaigns — crear un envío masivo#

POST https://api.mundosms.es/v3/whatsapp/campaigns

Permiso: whatsapp o whatsapp_campaign.

También: GET /v3/whatsapp/campaigns/{campaign_id} — su estado; POST /v3/whatsapp/campaigns/{campaign_id}/pause — pausarlo; POST /v3/whatsapp/campaigns/{campaign_id}/resume — reanudarlo; POST /v3/whatsapp/campaigns/{campaign_id}/cancel — cancelarlo.

Crear (hasta 10.000 destinatarios por llamada; para más, varias llamadas):

curl (bash)
curl -s https://api.mundosms.es/v3/whatsapp/campaigns \
  -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  -d '{"name":"Recordatorio citas lunes",
       "template":{"name":"confirmacion_cita","language":"es"},
       "recipients":[{"to":"34600000001","vars":["Ana","lunes 6","10:00"]},
                     {"to":"34600000002","vars":["Luis","lunes 6","11:30"]}],
       "date_scheduled":"2026-10-05T18:00:00+02:00"}'
  • Programar: date_scheduled, como en SMS y VozPush (ISO 8601 con zona, o en hora de Madrid); sin ella, sale ya. scheduled_at, el nombre de antes, sigue valiendo; los dos con fechas distintas dan 400.
  • Respuesta: en data, campaign_id, recipients, rejected_rows (teléfonos no válidos o repetidos) y state.
  • Consultar: GET /v3/whatsapp/campaigns/45. Devuelve en data:
    • name, state, stop_reason y date_scheduled (con su date_scheduled_iso; scheduled_at sigue saliendo);
    • los contadores total, delivered, read, failed, excluded_optout y pending.
  • Controlar: POST /v3/whatsapp/campaigns/45/pause, /resume o /cancel, sin cuerpo.
  • Estados: draft, scheduled, sending, paused, finished, cancelled y error.
  • Cobro: cada mensaje se cobra al salir, como un envío de plantilla. Sin saldo, el envío se pausa, y stop_reason dice por qué.
  • Las plantillas con foto, vídeo o documento en la cabecera todavía no se pueden usar en un envío masivo: envíalas de una en una con POST /v3/whatsapp/messages.

Los contactos que respondieron BAJA o STOP se excluyen automáticamente de los envíos.

Lo que todavía no hace la API de WhatsApp#

  • Crear plantillas: se crean en el panel.
  • Formularios de WhatsApp (Flows), catálogo y productos, y plantillas en carrusel: necesitan prepararse antes en WhatsApp. Si los necesitas, escríbenos.
  • Pedir una dirección postal con el formulario de WhatsApp: solo existe en India.
  • Botón para que el cliente te llame por WhatsApp.
  • Recibir los mensajes de tus clientes: eso no va por la API, sino por el webhook. Se configura en el panel y está documentado en https://www.mundosms.es/whatsapp-webhook.

Mensajes que te llegan (webhook)#

Lo que te escriben tus clientes, y el estado de lo que envías, no se pide a la API: te lo mandamos a tu servidor. Se activa en el panel, en WhatsApp · Números → Detalle del número → «Destino de este número»: la URL (https), los eventos que quieres y, al guardar, el secreto de la firma (whsec_…, se enseña una sola vez).

Cada evento es un POST con JSON, firmado: X-MundoSMS-Signature: t=<segundos unix>,v1=<firma>, donde v1 es el HMAC-SHA256 en hexadecimal, con tu secreto, de t + . + el cuerpo tal cual llega. Comprueba la firma y que t no tenga más de 5 minutos, y contesta un 2xx en menos de 10 segundos (si no, se reintenta, durante unas 22 horas). Un mensaje de texto de un cliente llega así (recortado: el evento completo, en la página del webhook):

HTTP
POST /tu-webhook HTTP/1.1
Content-Type: application/json; charset=utf-8
X-MundoSMS-Signature: t=1795259645,v1=6187525619683fbe958b7f95559f00b121d0faab8582eb77d9a20ec683563409
X-MundoSMS-Event: mensaje.recibido
X-MundoSMS-Event-Id: evt_01a1fdd03d4974f6b012ba27c925e4d6

{
  "id": "evt_01a1fdd03d4974f6b012ba27c925e4d6",
  "tipo": "mensaje.recibido",
  "creado": "2026-11-21T12:14:05.257+01:00",
  "numero": {"id": 1, "telefono": "+34 910 00 00 00", "phone_number_id": "106540352242922", "waba_id": "102290129340398"},
  "datos": {
    "mensaje_id": 1,
    "wamid": "wamid.HBgLMzQ2MDAwMDAwMDEVAgASGBQzQUVGRTY0RDQ2",
    "contacto": "34600000001",
    "nombre_contacto": "Ana Pérez",
    "fecha": "2026-11-21T12:14:05.257+01:00",
    "responde_a": null,
    "historial": false,
    "conversacion": {"id": 1, "contacto": "34600000001", "estado": "abierta", "asignado_tipo": null, "asignado_sid": null},
    "tipo": "texto",
    "texto": "Hola, ¿tenéis mesa para 4 esta noche?"
  }
}

Para contestarle, POST /v3/whatsapp/messages con to = datos.contacto (y reply_to = datos.wamid si quieres citar su mensaje). Los nombres del evento van en español, como en el panel. Hay más eventos (mensaje.estado con el estado de lo que envías, respuesta_boton y respuesta_lista dentro de mensaje.recibido, conversacion.*, contacto.baja, plantilla.estado, numero.*), y receptores completos que comprueban la firma en PHP, Python y Node, en https://www.mundosms.es/whatsapp-webhook.

Buenas prácticas con WhatsApp#

  • Permiso: escribe solo a quien ha aceptado recibir WhatsApp de tu empresa. Si te bloquean o te reportan, WhatsApp baja la calidad de tu número y reduce cuántos mensajes puedes enviar al día.
  • Tipo de plantilla: usa plantillas de aviso (utility) para recordatorios, confirmaciones y avisos de servicio. Las promocionales (marketing) cuestan más y tienen límites de frecuencia por usuario.
  • Reintentos: reintenta solo con data.retry a true, y con el código 11 (HTTP 202) consulta antes el estado.

Catálogo de errores#

Además de los errores de autenticación:

HTTP status_code message Dónde
400 "3" Required parameters missing cualquiera: falta un parámetro obligatorio
400 "3" Parameter <nombre> not valid cualquiera: el parámetro no vale; detail dice qué se espera
400 "3" Body not allowed / Query not allowed / Body not valid cuerpo en un GET, query en un POST, o un cuerpo que no es un objeto JSON
400 "3" Parameters not valid POST /v3/campaigns
400 "3" Too many ids GET /v3/sms/sends (más de 100)
402 "5" Insufficient credit lo que cuesta: SMS, VozPush, NumCheck, verificación de números
403 "3" Caller ID not verified el número que quieres presentar no es tuyo ni está verificado
403 "3" RCS not enabled for this account POST /v3/sms con type: "rcs_simple"
404 "4" Route not found la ruta no existe
404 "4" Call not found llamadas
404 "4" Recording not found grabaciones
404 "4" Extension not found extensiones, POST /v3/calls
404 "4" DID not found números
404 "4" Diagram not found diagramas, POST /v3/campaigns
404 "4" Voice file not found locuciones
404 "4" SMS not found GET /v3/sms/sends, send-now, cancel
404 "4" Campaign not found campañas de VozPush
405 "3" Method not allowed la ruta existe con otro verbo (cabecera Allow)
409 "3" Duplicated request una petición firmada con ts que ya había llegado
409 "3" Extension already exists POST /v3/extensions
409 "3" Extension not registered POST /v3/calls
409 "3" SMS already sent / SMS already cancelled send-now, cancel
409 "3" Voice file cannot be deleted / … yet DELETE /v3/voicefiles/{id}
409 "3" Not possible in the current state pausar, reanudar o cancelar una campaña
429 "7" Too many attempts / Too many requests demasiados intentos o peticiones: espera antes de reintentar
500 "2" Internal error error nuestro: reintenta más tarde
500 "2" Voice server unavailable / Voice server error la centralita no respondió: reintenta

Cómo tratarlos:

  • 400, 403, 404, 405, 409: no los reintentes tal cual: corrige la petición (o, en el 409 Duplicated request, mira Reintentos seguros).
  • 401: revisa el token, la firma y el reloj (X-Timestamp).
  • 402: recarga saldo.
  • 429 y 500: reintenta con espera creciente (1 s, 2 s, 4 s… hasta un minuto), firmando cada vez con un X-Timestamp nuevo.
  • Decide por el código HTTP y por status_code; usa message para casos concretos (es estable) y detail solo para mostrarlo o registrarlo.
  • Guarda el X-Request-Id de la respuesta: con él encuentras la petición en Logs API.

Uso responsable: pide una vez y guarda en tu base de datos#

La API sirve para traer los datos a tu sistema, no para consultarlos cada vez que los enseñas. Pide cada dato una sola vez, guárdalo en tu base de datos y trabaja desde ahí. Así tus pantallas van más rápido, no dependen de tu conexión ni de la nuestra, y puedes filtrar, exportar a CSV o sacar estadísticas sin pedirnos nada.

Ejemplos de mal uso:

  • Pedir el historial de llamadas cada vez que se muestra. Sincroniza con el cursor (Sincronizar llamadas sin perder ninguna) y enséñalas desde tu base de datos. Para saber a quién devolver la llamada está GET /v3/calls/missed, que ya trae el resumen.
  • Preguntar por el estado de un SMS que ya terminó (delivered o failed), o por el de un envío programado antes de su hora. Pregunta solo por los que siguen pendientes, y mejor aún: pasa url_callback en POST /v3/sms y te avisamos de cada informe de entrega en cuanto llega (Avisos a tu URL).
  • Pedir el saldo antes de cada envío. Cada POST /v3/sms devuelve cost y balance: guárdalos y actualízalos con cada envío o compra.
  • Volver a comprobar con POST /v3/numchecks un número que ya comprobaste. Guarda el resultado.

Por eso los listados van por páginas y con tope (Límites). En Logs API ves cuántas peticiones hace tu integración. Si pide mucho más de lo que necesita, nos pondremos en contacto contigo.

Límites#

Ruta limit por defecto limit máximo
GET /v3/calls 20 100
GET /v3/calls/missed 100 500 (ventana: 7 días por defecto, 31 como mucho)
GET /v3/calls/live 100 500
GET /v3/numbers 100 500
GET /v3/extensions sin limit: todas —
GET /v3/diagrams 50 500
GET /v3/sms, GET /v3/sms/replies 50 500
GET /v3/sms/sends — 100 ids o referencias por petición

Otros límites:

  • X-Timestamp: a menos de 5 minutos de nuestra hora; con «Rechazar peticiones repetidas», cada petición firmada una sola vez.
  • client_id: 50 caracteres en SMS, 30 en NumCheck, 20 en VozPush, 100 en WhatsApp.
  • Remitente de SMS (from): de 1 a 11 caracteres.
  • POST /v3/voicefiles por URL: 16 MB.
  • POST /v3/callerid-validations: 10 intentos por número.
  • Para sincronizar, no hace falta preguntar más de una vez por minuto: usa el cursor y pide páginas grandes.
  • Peticiones por minuto: hoy no hay un tope fijo. El 429 solo lo dan la verificación de números (10 intentos por número) y WhatsApp (cuando Meta o nuestro servicio frenan los envíos, con Retry-After). Si te llega un 429, espera lo que diga Retry-After o, si no lo trae, con tiempos crecientes.

Recetas para CRM y ERP#

Guía rápida: qué usar para cada cosa.

Quiero… Usa
Tener en mi CRM todas las llamadas, nuevas y terminadas GET /v3/calls sin type, con cursor y stop_at_ongoing (receta). Si no hay nada nuevo, una sola petición
Saber a quién devolver la llamada GET /v3/calls/missed: perdidas pendientes, una por número
Saber si una perdida concreta se devolvió GET /v3/calls: cada perdida lleva followup
Ver con quién habla ahora una extensión (recepción) GET /v3/calls/live?extension=… → other_party (receta)
Mostrar la ficha del cliente cuando llama GET /v3/calls/live: las in en ringing, por from
Las llamadas y los SMS de un contacto GET /v3/calls y GET /v3/sms con number (receta)
Los SMS que he enviado y cómo acabaron GET /v3/sms con cursor, o con send_id / client_id para un envío
Las respuestas a mis SMS GET /v3/sms/replies
Oír o guardar una grabación GET /v3/calls/{type}/{id}/recording (format=mp3 si es para un iPhone)
Llamar desde una extensión POST /v3/calls
Colgar una llamada POST /v3/calls/live/{type}/{id}/hangup (si ya había colgado: changed: false, «Call already terminated»)
Reintentar sin duplicar Reintentos seguros
Ver qué ha pedido mi integración y qué le contestamos Logs API, con el X-Request-Id

Sincronizar llamadas sin perder ninguna#

El objetivo: tener en tu sistema todas las llamadas terminadas, una sola vez, sin depender de las horas.

  1. La primera vez, decide desde cuándo quieres el historial y pide GET /v3/calls?from_datetime=2026-11-01&stop_at_ongoing=true&order=asc&limit=100. Sin type vienen entrantes, salientes y funciones, ordenadas por hora.
  2. Guarda cada llamada por su type + id: es la clave única en tu sistema, porque el mismo id puede existir en in y en out.
  3. Guarda next_cursor. Mientras has_more sea true, pide la página siguiente con GET /v3/calls?cursor=<next_cursor>&stop_at_ongoing=true&limit=100.
  4. Cuando has_more sea false, has terminado por ahora. En la siguiente sincronización (cada minuto, cada cinco…), haz una petición con el último next_cursor. Si no hay nada nuevo, contesta results: 0 y el mismo cursor.

Por qué stop_at_ongoing: una llamada en curso todavía no tiene fin, duración ni coste. Con stop_at_ongoing la página se corta antes de la primera llamada en curso, así que tu cursor nunca la deja atrás: la recibirás terminada en una sincronización posterior. Si una página llega con results: 0 y has_more: true, la primera llamada pendiente sigue en curso: vuelve a preguntar más tarde con el mismo cursor.

Si prefieres llevar cada tipo por separado, también vale: type in u out con from_id/next_from_id, uno por tipo.

Python
# Sincronización incremental de llamadas (usa la función mundosms() de «Ejemplos completos»)
def sincroniza(cursor):                  # cursor: el último next_cursor guardado (None la primera vez)
    while True:
        datos = {"stop_at_ongoing": "true", "limit": 100}
        if cursor:
            datos["cursor"] = cursor
        else:
            datos.update({"from_datetime": "2026-11-01", "order": "asc"})
        http, r = mundosms("GET", "/v3/calls", datos)
        if http != 200:
            raise RuntimeError(r["message"])
        for llamada in r["data"]["calls"]:
            guarda_llamada(llamada["type"], llamada)   # idempotente: clave única (type, id)
        cursor = r["data"]["next_cursor"] or cursor
        guarda_cursor(cursor)
        if not r["data"]["has_more"]:
            return cursor   # al día
        if r["data"]["results"] == 0:
            return cursor   # la siguiente llamada sigue en curso: la próxima pasada sigue desde aquí

Con el SDK es un bucle: for llamada in api.todos("/calls", {"from_datetime": "2026-11-01", "stop_at_ongoing": True}).

En la primera descarga de un historial largo, una llamada en curso detiene el recorrido en ese punto hasta que termine (o pasen 12 horas): no se pierde nada, la siguiente pasada sigue desde el mismo cursor. Si necesitas saber que la descarga inicial ha terminado, es cuando una página llega con has_more: false.

Las llamadas y los SMS de un contacto#

Para la ficha de un cliente, con su número en formato internacional:

  • llamadas: GET /v3/calls?type=in&number=34600123456&order=desc&limit=20 y lo mismo con type=out;
  • perdidas sin devolver: GET /v3/calls?type=in&number=34600123456&status=missed&from_datetime=… y compara con las salientes a ese número posteriores;
  • SMS enviados: GET /v3/sms?number=34600123456&order=desc;
  • SMS recibidos de ese número: GET /v3/sms/replies?number=34600123456&order=desc (hoy no hay SMS de vuelta: sale vacía).

¿Con quién habla recepción?#

GET /v3/calls/live?extension=recepcion: si results es 0, la extensión está libre; si no, other_party es el número con el que habla y state dice si aún está sonando (ringing) o en conversación (talking). Para un panel con todas las extensiones, pide GET /v3/calls/live sin filtro y agrupa por party y por las patas de legs. Para mostrar la ficha del cliente cuando entra una llamada, busca por from las llamadas in en ringing.

La bandeja de llamadas perdidas#

A quién llamar: GET /v3/calls/missed, sin parámetros, da los números con perdidas pendientes de los últimos 7 días, uno por número, con cuántas veces llamó y cuándo.

  • Es una foto, no una sincronización. Un número sale de la lista en cuanto alguien le atiende, así que pídela entera cada vez (cada pocos minutos basta).
  • Para atender por orden de llegada, ordena por first_missed. Si llamó varias veces, ahí va la primera.
  • Para el histórico completo (perdidas devueltas o no, con su followup), sincroniza con el cursor y status=missed. El followup de una perdida puede cambiar después: si lo guardas, vuelve a pedir las que tengas pending.

Reintentos seguros#

Una red que corta puede dejarte sin saber si una petición llegó. Cómo reintentar sin duplicar un envío:

  1. Consultas (GET): reintenta sin más, firmando con un X-Timestamp nuevo.
  2. Envíos (POST /v3/sms, POST /v3/campaigns, POST /v3/numchecks, POST /v3/whatsapp/messages): manda siempre un client_id único por envío (por ejemplo, el id de tu registro). Si no recibes respuesta:
    • reenvía exactamente la misma petición (mismo cuerpo, mismo X-Timestamp y misma firma) dentro de los 5 minutos: con «Rechazar peticiones repetidas», si contesta 409 Duplicated request, la primera petición sí llegó;
    • en ese caso, o si dudas, busca el envío por tu referencia (GET /v3/sms/sends?client_id=… o GET /v3/sms?client_id=…; GET /v3/campaigns?client_id=…). Si existe, no lo vuelvas a enviar;
    • si no existe, envíalo de nuevo con un X-Timestamp nuevo.
  3. Cambios (PATCH, hangup): son repetibles: aplicar dos veces el mismo valor da changed: false, con un message que lo dice.
  4. Ante 429 o 500, espera con tiempos crecientes antes de reintentar; no reintentes en bucle. Los SDK ya lo hacen así: reintentan solos los 429 y, en GET, los 5xx y los fallos de red; un POST o un PATCH que falla por la red no lo repiten (no se sabe si llegó).

El paso 2 en código, con la función mundosms de Python de arriba:

Python
def enviar_sms_una_vez(datos):
    """datos lleva un client_id único (por ejemplo, el id de tu registro)."""
    try:
        return mundosms("POST", "/v3/sms", datos)
    except OSError:                                   # la red cortó: no sabemos si llegó
        http, r = mundosms("GET", "/v3/sms/sends", {"client_id": datos["client_id"]})
        if http == 200 and any("error" not in s for s in r["data"]["sms"]):
            return http, r                            # llegó: no lo repitas
        return mundosms("POST", "/v3/sms", datos)     # no llegó: ahora sí, con un X-Timestamp nuevo

Avisos a tu URL (url_callback)#

Algunas rutas aceptan una URL tuya (url_callback) a la que avisamos cuando algo termina, para que no tengas que preguntar. Así funcionan hoy:

  • Todos los avisos son un GET a tu URL con los datos en la query, añadidos a los parámetros que ya lleve.
  • No van firmados. Para comprobar que el aviso es nuestro, pon en tu URL un parámetro secreto que solo conozcáis tu sistema y nosotros (https://crm.ejemplo.com/avisos/sms?k=8f2c…) y compruébalo al recibirlo. Usa https://.
  • Contesta rápido, en menos de 5 segundos: guarda el aviso y procésalo después.
  • Trátalos como pistas, no como la verdad: si un aviso no llega o llega dos veces, la ruta de consulta de cada objeto siempre tiene el estado bueno.
  • Tamaño de la URL: hasta 150 caracteres en SMS y NumCheck, y hasta 250 en VozPush. Más larga, la petición da 400 Parameter url_callback not valid.
  • Solo a direcciones públicas, también al enviar: el nombre de tu URL tiene que resolver a direcciones IPv4 públicas cuando lo pides y cada vez que te avisamos, y una redirección solo se sigue (hasta 3) si lleva a otra dirección pública: si tu servidor solo tiene IPv6, o redirige a una dirección privada, el aviso no sale y cuenta como fallido.

Informe de entrega de un SMS (POST /v3/sms)#

Un aviso por destinatario, cuando el SMS termina: entregado o fallido. No hay avisos de estados intermedios. Si no pasas url_callback, se usa la URL de avisos de tu cuenta, si la tienes configurada.

HTTP
GET /avisos/sms?k=8f2c&smsid=cita-88123&status=0&msisdn=34600123456&date_received=2026-11-21%2010%3A15%3A02&date_now=2026-11-21%2010%3A15%3A04
User-Agent: MundoSMS-Callback
X-Webhook-Source: mundosms
Parámetro Qué es
smsid tu client_id, si lo mandaste; si no, nuestro id del envío
status 0 entregado, 2 fallido
msisdn el destinatario
date_received la hora de entrega que da el operador (AAAA-MM-DD hh:mm:ss, hora de Madrid); no va si el operador no la da
error_code casi nunca; Flood si lo frenó la protección contra envíos repetidos
date_now cuándo se mandó este aviso

Contesta con el texto OK: el código HTTP no cuenta. Si no llega OK, se reintenta cada 5 minutos como mínimo, unas 20 veces (algo más de hora y media), cada vez con un date_now nuevo. Espera como mucho 5 segundos.

Fin de una campaña de VozPush (POST /v3/campaigns)#

Un aviso cuando la campaña termina o se cancela, con el resultado de cada destino:

HTTP
GET /avisos/vozpush?k=8f2c&str=1%7C2%7C3.6%7C1%7C1%7C2026-11-21+10%3A31%3A07%7C45%7C0%7C45%7C0%7C0%0A%5B%5B%2234600123456%22%2C%22Finalizada%22%5D%5D%0A%5B%5D%0A%5B%5D&callid=recordatorio-1120
  • callid: tu client_id, si lo mandaste; si no, nuestro id de la campaña.
  • str: cuatro líneas.
  • Separados por |: terminada (1), estado (2 finalizada, 4 cancelada, 5 error), coste, contestadas, fallidas, la hora de la última actualización y los segundos totales, de funciones, a móvil, a fijo y a SIP.
  • En JSON, el estado de cada destino: [["34600123456","Finalizada"],["34911222333","No respondida"]].
  • En JSON, las teclas que marcó cada destino: [["34600123456","1|3"]].
  • En JSON, sus grabaciones.
  • La respuesta da igual y no se reintenta. Puede llegar dos veces: hazlo idempotente.
  • En una campaña grande, la URL lleva el resultado de todos los destinos y algún servidor o proxy puede rechazarla por larga. Si te pasa, usa el aviso solo como señal y pide el resultado con GET /v3/campaigns/{id}.

Con url_callback_single_failed, además, un aviso por cada destino que queda fallido del todo (ya sin reintentos):

HTTP
GET /avisos/fallidos?k=8f2c&callid=991250&destination=34600123456&status_lastcall=No+respondida

Aquí callid es siempre nuestro id de la campaña. status_lastcall es uno de: No respondida, Ocupado, Rechazada, No molestar, Desconectado, Contestador, Fax, Error, Cancelado, Desconocido.

Verificación de un número (POST /v3/callerid-validations)#

Es el mismo aviso que el fin de una campaña (la verificación es una llamada de VozPush), con callid = el vozpush_id que devolvió la petición. Llega cuando termina la llamada y no dice si el número quedó verificado. Para saberlo, vuelve a hacer POST /v3/callerid-validations con el número: si ya lo está, la respuesta lo dice y no se vuelve a llamar.

NumCheck (POST /v3/numchecks)#

Un aviso con el resultado:

HTTP
GET /avisos/numcheck?k=8f2c&hlrid=limpieza-nov&msisdn=34600123456&b_valid=1&result=limpieza-nov%7C34600123456%7C1%7CSuccess%7C0%7C%7C21407%7CES%7CSpain%7C…&date_now=2026-11-21%2010%3A20%3A01&date_received=2026-11-21%2010%3A20%3A01
  • hlrid: tu client_id, si lo mandaste; si no, nuestro id.
  • b_valid: 1 si el número existe y está activo.
  • result, separado por |: id|número|válido|estado|código de error|descripción del error|código de red|país (ISO)|país|operador|red|tipo de red|ubicación|portado|portado desde|portado desde (2). Con un número que no es válido, solo trae los primeros campos.
  • Contesta con el texto OK. No se reintenta.

SMS que llegan a uno de tus números (sms_url, PATCH /v3/numbers/{did})#

Hoy ningún número recibe SMS: no hay avisos de SMS entrantes. sms_url y sms_email se guardan, pero no se usan.

Lo que todavía no avisa#

  • Llamadas de click2dial (POST /v3/calls): url_callback se acepta, pero hoy no se envía ningún aviso. Para saber cómo acabó, consulta la llamada en GET /v3/calls.
  • Faxes que llegan a tu número (fax_url): el aviso lleva el fax dentro de la URL y la mayoría de servidores la rechazan por larga. No es fiable: recibe los faxes por correo (fax_email).
  • Llamadas que entran, se contestan o terminan: no hay avisos en tiempo real. Para la ficha del cliente, GET /v3/calls/live.

Logs API: tus peticiones de los últimos 30 días#

En el panel, en API y Soporte → Logs API, están las peticiones de tu cuenta a la API de los últimos 30 días, con lo que llegó, lo que respondimos y cuánto tardamos. Es lo primero que hay que mirar cuando algo «no funciona»: si la petición no está, no llegó a la API (o llegó con un token que no es de una clave tuya); si está, ves exactamente qué mandaste y qué te contestamos.

  • Cada respuesta lleva X-Request-Id: búscalo en Logs API (o pégalo en el enlace: APILogs.html#<X-Request-Id>).
  • Filtros: fechas, clave, API (REST, la anterior /APIv3/ o enlaces firmados), resultado (correctas o con error), código HTTP y X-Request-Id.
  • Detalle: la petición y la respuesta, y la misma petición como orden de curl (sin tus credenciales).
  • Lo que no se guarda: el token completo (solo su parte pública, sin la firma), la firma, la clave privada y las contraseñas.
  • La petición: entera hasta 64 KB; de un fichero en base64, su tamaño y su huella. Una petición más grande se guarda además entera y comprimida, ficheros incluidos, para poder reproducir el problema, y la puedes descargar desde el detalle. De las respuestas, hasta 2 KB si fue bien y hasta 16 KB si fue un error.
  • Solo lo ve tu cuenta, y nuestro soporte cuando nos lo pidas.
  • Las peticiones de las APIs anteriores (/APIv3/, y la /APIv2/ y la extranet con tu usuario y contraseña) salen marcadas como «API antigua»: si aparecen, tu integración todavía no ha migrado (Migrar desde /APIv3/). De esas, la contraseña nunca se guarda, y el curl que te proponemos la deja como TU_CONTRASEÑA.
  • Una petición aparece unos segundos después de hacerla.

SDK: un fichero en PHP, Python o Node.js#

Si no quieres escribir la firma, descarga el cliente de tu lenguaje y cópialo en tu proyecto. Es un solo fichero, sin dependencias, con el mismo uso en los tres:

Lenguaje Fichero Requisitos
PHP mundosms.php (guárdalo como mundosms.php) PHP 7.4 o superior con curl
Python mundosms.py Python 3.8 o superior
Node.js mundosms.js Node.js 18 o superior
Python
from mundosms import MundoSMS, MundoSMSError

api = MundoSMS("TU_TOKEN", "TU_CLAVE_PRIVADA")    # la clave privada, "" si tu clave no exige firma
r = api.post("/sms", {"to": "34600123456", "text": "Tu cita es mañana a las 10:00", "from": "MiClinica"})
print(r["data"]["id"])
for llamada in api.todos("/calls", {"from_datetime": "2026-11-01", "stop_at_ongoing": True}):
    print(llamada["type"], llamada["id"], llamada["state"])
try:
    api.patch("/extensions/recepcion", {"record_calls": True})
except MundoSMSError as e:
    print(e.http, e.status_code, e, e.detail)
  • get(ruta, filtros), post(ruta, datos), patch(ruta, datos) y delete(ruta, filtros), con la ruta sin /v3 ("/calls", "/numbers/34910123456"). Devuelven la respuesta entera (status, message, data).
  • todos(ruta, filtros) recorre todas las páginas de un listado (con next_cursor o next_from_id) y te da los elementos uno a uno.
  • Un error es una excepción MundoSMSError con el código HTTP (http), status_code, el mensaje y detail.
  • Firma cada petición con X-Timestamp en milisegundos, y reintenta solo lo que es seguro repetir (ver Reintentos seguros).
  • En PHP: require "mundosms.php"; $api = new MundoSMS("TOKEN", "CLAVE");, y foreach ($api->todos("/calls", […]) as $c). En Node.js: const { MundoSMS } = require("./mundosms");, y for await (const c of api.todos("/calls", {…})).

Buenas prácticas de seguridad#

  • Firma con ts siempre. Deja activadas «Firmar cada petición» y «Rechazar peticiones repetidas» en todas tus claves: sin firma, quien vea el token puede usarlo; con firma pero sin la segunda, una petición capturada se puede repetir durante 5 minutos.
  • Lista de IPs. Si tu sistema llama desde IPs fijas, ponlas en la clave: desde cualquier otra, IP not allowed.
  • Una clave por integración, con solo los permisos que necesita. Si una se filtra, se revoca esa y no las demás.
  • Rota las claves: crea la nueva, cámbiala en tu sistema y borra la vieja. Hazlo al menos una vez al año y siempre que alguien que la conocía deje de necesitarla.
  • La clave privada no sale de tu servidor: ni en el navegador de tus usuarios, ni en una app móvil, ni en el código de un repositorio. Guárdala como un secreto (variable de entorno, gestor de secretos).
  • El token, tampoco en la URL: siempre en la cabecera Authorization.
  • Caducidad: para pruebas, pon caducidad a la clave; para integraciones, déjala vacía pero vigila su uso en Logs API.
  • Lo que recibes en tus url_callback: compruébalo antes de fiarte, y no ejecutes nada solo porque llegue.
  • TLS: llama siempre a https:// y no desactives la comprobación del certificado.

Migrar desde /APIv3/#

Política de versiones#

  • La API REST (https://api.mundosms.es/v3/) es la API de MundoSMS. Dentro de /v3/ solo se añaden cosas (rutas, parámetros opcionales, campos en la respuesta, valores nuevos en los estados): escribe tu integración para que ignore campos y valores que no conozca.
  • Un cambio que rompa (quitar o renombrar un campo, cambiar un tipo) irá en una versión nueva (/v4/), con aviso previo y un tiempo de convivencia.
  • La API anterior, https://api.mundosms.es/APIv3/<método>, sigue funcionando para lo ya integrado, pero ya no se amplía: lo nuevo solo llega a la REST. Cuando dejemos de verla en uso, avisaremos con fecha antes de retirarla. Sus peticiones salen en Logs API como «API antigua».
  • Los enlaces que ya hemos enviado (grabaciones en HubSpot, correos de llamada perdida, QR de las apps) siguen valiendo.

Qué cambia#

Antes (/APIv3/) Ahora (REST, /v3/)
una dirección por método, todo por POST una ruta por recurso y su verbo (GET, POST, PATCH, DELETE)
la firma cubre el token y el cuerpo la firma cubre también el verbo, la ruta, la query y X-Timestamp: no sirve para otra petición
ts dentro del cuerpo JSON la cabecera X-Timestamp (segundos o milisegundos)
HTTP 200 siempre, sin Content-Type el código HTTP de cada caso (400, 401, 402, 403, 404, 405, 409, 429, 500) y application/json
status_code "1" para éxitos con matiz (sin resultados, ya estaba así, programado) "0", y el matiz en data (results: 0, changed: false, state: "scheduled")
«no existe» con status_code "3" HTTP 404 y "4"
"4" (Already sent, XML Error, Max retries) y "6" (Callerid not validated) "3" (409 o 400) y "7" (429)
message de éxito variado (IN_PROGRESS, File returned…) OK (N results en los listados)
details detail
fechas AAAA-MM-DD hh:mm:ss, "" sin fecha con milisegundos y su gemela _iso; null sin fecha
cantidades e ids como texto ("12.00", "123") números JSON
sí/no como "0"/"1" y prefijo b_ true/false sin prefijo (record_calls)
estados numéricos o en español palabras estables (answered, no_answer, delivered…)
ids que aceptaban tu referencia o la nuestra (sms_id, callid) id (el nuestro) y client_id (el tuyo), por separado
historiales sin paginación limit, cursor, order, has_more y next_cursor (llamadas, SMS, respuestas, números y diagramas; from_id y next_from_id siguen valiendo)
set_voipdids/set_voipextensions: un campo por petición (change_parameter/change_value) PATCH con los campos que cambian, todos de una vez o ninguno
WhatsApp con status: "ok" y su propio formato el contrato común (success, data, id, client_id, date_*)

Equivalencias de nombres#

/APIv3/ Ruta REST Nombres que cambian (antes → ahora)
list_voipcalls GET /v3/calls (y GET /v3/calls/{type}/{id}) callerid, callerid_text, destination, destination_type (1-9) → from, from_name, to, to_type (palabra); status (0-11), sip_originator, destination_pickup → state (palabra) y state_code, extension, pickup_extension; plan_id, bridgetype, xmlplan, arr_related → bundle_id, bridge_type, xml_plan (con include_xml), related (con include_related); showall → all_legs
list_voipmissedcalls GET /v3/calls/missed —
list_voiplivecalls GET /v3/calls/live type_id, caller, called, d_started, d_answered, d_bridged → id, from, to, date_start, date_answer, date_bridged; peer, peers, search, b_only_main → party, legs, extension, all_legs (al revés: all_legs: true = b_only_main: 0)
action_voiplivecalls POST /v3/calls/live/{type}/{id}/hangup callid → id, en la ruta; action ya no se manda
getrecording_voipcalls GET /v3/calls/{type}/{id}/recording id "in_123" → type + id en la ruta; name, type (MIME) → filename, content_type
click2dial POST /v3/calls destination, callerid_destination, callerid_extension, id_urlcallback → to, from, extension_caller_id, url_callback
get_voipdids GET /v3/numbers (y /{did}) b_calls, b_fax, b_sms, b_record_calls, xml, id_diagramflow → calls_enabled, fax_enabled, sms_enabled, record_calls, xml_plan, diagram_id; minutecall_cost, minutecallm_cost, date_expire: "Never" → minute_cost_landline, minute_cost_mobile, date_expire: null
set_voipdids PATCH /v3/numbers/{did} change_parameter + change_value → los campos que cambian, en el cuerpo
get_voipextensions GET /v3/extensions (y /{extension}) login, callerid, b_record_calls, show_status, status → extension, caller_id (+ caller_id_name, caller_id_number), record_calls, include_status, registration
new_voipextensions POST /v3/extensions callerid, callerid_num, callerid_text, b_record_calls, login → caller_id, caller_id_number, caller_id_name, record_calls, extension
set_voipextensions PATCH /v3/extensions/{extension} change_parameter + change_value → los campos que cambian, en el cuerpo
getdiagrams_voip GET /v3/diagrams (y /{id}) —
callerid_validation POST /v3/callerid-validations callerid, keycode, ntries, vozpushid → number, code, attempts, vozpush_id
upload_voicefile, get_voicefile, delete_voicefile POST /v3/voicefiles, GET y DELETE /v3/voicefiles/{id} name, type (MIME) → filename, content_type
sendcall POST /v3/campaigns destination, xmlplan, plan_id, sender, customid, date_start → to, xml_plan, diagram_id, from, client_id, date_scheduled; d_start/d_end, h_start/h_end, days_span, n_max_*, delay_nextcall → date_window_start/_end, time_window_start/_end, weekdays, max_*, retry_delay_min
getreport_call GET /v3/campaigns/{id} (o ?client_id=), POST …/pause, /resume, /cancel callid, destination, continue, end, calls_results, n_answered, n_failed → id, to, resume, cancel, results, answered_count, failed_count
getrecording_vozpush GET /v3/campaigns/{id}/calls/{to}/recording —
sendsms POST /v3/sms destination, message, sender, smsid/customid, send_date, callback, b_keep_sizesms → to, text, from, client_id, date_scheduled, url_callback, keep_sms_size; data.smsid → data.id (el nuestro) y data.client_id
quotesms POST /v3/sms/quote los de sendsms
sendsms_cert POST /v3/sms/certified los de sendsms, y cert_cif, cert_lang, cert_tomail → cert_tax_id, cert_language, cert_email
getreport GET /v3/sms/sends/{id} (o ?id=…, ?client_id=…) sms_id (nuestro o tuyo), dest_delivered, dest_failed (texto) → id o client_id, delivered, failed (listas)
scheduled_sendings POST /v3/sms/sends/{id}/send-now y /cancel sms_id, action 1/2 → id en la ruta; data.smsid, data.status → data.id, data.state
(nuevo) GET /v3/sms, GET /v3/sms/replies —
numcheck POST /v3/numchecks phones → number (uno); customid, data.hlrid → client_id, data.id
whatsapp_* /v3/whatsapp/… (WhatsApp) status: "ok" → success; message_id → id; client_ref → client_id; created, updated → date_created, date_updated (+ _iso)

Ojo con estos cambios:

  • Lo que identifica el recurso va en la ruta (/v3/numbers/{did}, /v3/sms/sends/{id}): ya no se manda en los datos.
  • En las rutas de SMS y de campañas, id es solo nuestro id, un número. Si tienes tu propia referencia, búscala en client_id.
  • GET /v3/calls ya no trae el plan XML ni las llamadas relacionadas si no los pides (include_xml, include_related).
  • En POST /v3/campaigns, date_start (cuándo lanzarla) no tiene alias: da 400 Parameter date_start not valid. Usa date_scheduled; los date_window_* son la ventana de días.

Cómo migrar#

  1. Usa tus claves de siempre: las mismas valen para la REST. Si tu clave no firmaba, aprovecha para que firme.
  2. Cambia cada llamada por su ruta (tabla anterior) y la firma por la nueva (La firma): o mejor, usa el SDK, que firma solo.
  3. Trata los códigos HTTP: muchas librerías (Guzzle, requests con raise_for_status, fetch con r.ok) tratan un 4xx o 5xx como excepción. El cuerpo sigue siendo JSON: léelo también en esos casos.
  4. Cambia los nombres de los campos que lees de la respuesta y los tipos: números y true/false.
  5. Prueba con una clave de solo lectura y el formulario de esta página antes de pasar los envíos, y comprueba en Logs API que ya no te sale ninguna petición «API antigua».

Historial de cambios#

2026-11-22#

  • Un solo cursor en todas las listas: todas devuelven next_cursor y aceptan cursor, así que una página se pide igual en cualquier lista. from_id y next_from_id siguen valiendo donde estaban.
  • Fechas ISO 8601 con zona también en lo que mandas (from_datetime, to_datetime), como ya pasaba en date_scheduled: puedes mandar tal cual una date_x_iso que te hayamos devuelto.
  • Documentación: el ejemplo de GET /v3/numbers trae el next_cursor que devuelve la API; el tope de client_id en WhatsApp (100); y que hoy ningún número recibe SMS (sms_url, sms_email y GET /v3/sms/replies).
  • Los avisos de VozPush también comprueban la dirección pública al enviar, como los de SMS y NumCheck.
  • Documentación: los ejemplos de PHP y Python mandan las listas de la query separadas por comas (antes, una lista daba 400); el ejemplo de SMS personalizados usa text; ISO 8601 con zona también en from_datetime/to_datetime; y «Reintentos seguros» con el ejemplo en código.
  • Documentación: los ejemplos de Node.js y Python ya no mandan los valores nulos como texto («null», «None»); el ejemplo de GET /v3/sms/replies usa el cursor; y la tabla de migración nombra cursor/next_cursor.
  • WhatsApp: date_scheduled para programar una campaña, como en SMS y VozPush (scheduled_at sigue valiendo), y la consulta devuelve date_scheduled y date_scheduled_iso.
  • Documentación: la regla de WhatsApp de «cada petición firmada vale una vez», dentro de la tabla de modos de firma; que getreport_call también pausa y cancela campañas; qué campos de GET /v3/calls salen con cada type; y un ejemplo del webhook de WhatsApp (lo que te llega cuando te escribe un cliente).

2026-11-21#

  • API REST en https://api.mundosms.es/v3/: una ruta por recurso, firma que cubre verbo, ruta, query, cuerpo y X-Timestamp, PATCH de varios campos a la vez y WhatsApp con el mismo contrato que el resto. Recoge todo lo del contrato del 20/11, que no llega a publicarse en otra dirección.
  • Logs API en el panel: tus peticiones de los últimos 30 días, con X-Request-Id en cada respuesta.
  • SDK de un fichero en PHP, Python y Node.js.
  • GET /v3/numbers y GET /v3/diagrams: con cursor (from_id, limit, has_more, next_from_id), en orden de id. Antes devolvían como mucho 100 números y 50 diagramas, sin forma de ver el resto.
  • Nueva sección «Uso responsable»: pide cada dato una vez y guárdalo en tu base de datos.

2026-11-20#

  • Contrato nuevo: códigos HTTP, status_code común con WhatsApp, fechas con milisegundos e ISO 8601, null en vez de "", números y true/false en JSON, estados en palabras, id y client_id separados y paginación con cursor.
  • Nuevos: los SMS enviados por destinatario y las respuestas a tus SMS.
  • Historial de llamadas: filtros number, status, extension, did, to_datetime, stop_at_ongoing, limit y order. En las entrantes, status va por quién atendió, con attended_by y followup en cada perdida. Sin type, todas las llamadas por hora de inicio con un solo cursor (next_cursor).
  • Nuevo: las perdidas por devolver, una por número.
  • Llamadas en curso: extension con other_party (con quién habla) y number.
  • Grabaciones en MP3 con format.
  • Página de referencia con el formulario «Pruébalo», la especificación OpenAPI y la colección de Postman.

¿Dudas con la integración? Escríbenos y te ayudamos. Para recibir en tu sistema los mensajes de WhatsApp, tienes el webhook de WhatsApp.