Developers

Build with the Inalambria APIs

REST APIs for SMS, RCS, WhatsApp and Email, plus SMPP connections and file-based sending. Token authentication, JSON payloads and status notifications delivered to your own infrastructure.

Overview

Each service has its own host:

ServiceHost
SMS, RCS, token and monitoringhttps://rest.inalambria.com
WhatsApphttps://multichannel.inalambria.com
Emailhttps://emailrest.inalambria.com
SMPPsmsc.inalambria.com · smscssl.inalambria.com

Requirements: a sending account configured by Inalambria, authentication credentials and an HTTPS connection. Some services (RCS, notifications, monitoring, files) must be enabled first.

This page summarizes the official reference. For full details on each endpoint see docs.inalambria.com .

Quickstart

  1. 1

    Request your account

    Inalambria configures your sending account and gives you a username and password.

  2. 2

    Get a token

    POST /token with Basic Authentication and grant_type: password.

  3. 3

    Send your first SMS

    POST /mtmessage with the Bearer Token. Keep the TransactionNumber.

  4. 4

    Receive statuses

    Enable the account webhook or the per-request callback.

# 1. Request a token (Basic Authentication with your credentials)
TOKEN=$(curl -s -X POST https://rest.inalambria.com/token \
  -u "$INALAMBRIA_USER:$INALAMBRIA_PASSWORD" \
  -H "Content-Type: application/json" \
  -d '{"grant_type": "password"}' | jq -r '.access_token')

# 2. Send an SMS (Colombia: 12 digits, 57 + mobile)
curl -X POST https://rest.inalambria.com/mtmessage \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "Type": 1,
    "MessageText": "Your order PEDIDO-4471 is on its way",
    "Devices": "573001234567",
    "CustomMessageId": "PEDIDO-4471"
  }'

Authentication

  • Token: POST /token with Basic Authentication (Base64 username and password) and the body {"grant_type": "password"}. The response includes access_token, expires_in, refresh_token and token_type.
  • By default a token lasts 4 hours and each account has 1 active token: requesting a new one expires the previous one. Both can be extended on request.
  • To renew it without credentials, send {"grant_type": "refresh_token", "refresh_token": "..."}.
  • SMS and RCS use Authorization: Bearer <token> (recommended) or Basic. WhatsApp uses Basic. Email uses the x-api-key header.
  • Requests from unauthorized IP addresses receive 403.

SMS: POST /mtmessage

FieldDescription
Type*1 bulk (same text), 2 personalized (MessagePattern + MessageData), 3 template (TemplateId + MessageData).
DevicesRecipients separated by a hyphen: 573XXXXXXXXX-573YYYYYYYYY.
MessageTextMessage text (bulk mode).
ChannelSMS (default) or RCS.
DateMessageScheduling: yyyy-MM-dd HH:mm:ss.
FlashSMS1 for a flash SMS.
UrlLong URL to shorten and insert in the message.
HasMore / TransactionNumberSplit sends under a single transaction number.
CustomMessageId / CallbackDataYour own data, returned in the status notification.

Response: TransactionNumber (28 digits), Status (0 accepted, 1 rejected) and MessageText with the rejection reason.

Format: Colombian numbers with 12 digits (57 + mobile) and E.164 elsewhere. There is no character limit, but staying under 500 is recommended.

RCS

RCS uses the same /mtmessage endpoint with "Channel": "RCS". The account and RCS agent must be configured first.

# RCS: same endpoint with "Channel": "RCS" (requires prior account set-up)
curl -X POST https://rest.inalambria.com/mtmessage \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "Type": 1,
    "Channel": "RCS",
    "MessageText": "Your order PEDIDO-4471 arrives today between 2 and 5 pm",
    "Devices": "573001234567"
  }'

Batch: POST /mtmessage/massive

Several messages, each with its own destinations list, in a single request. Each message supports flash, shortCode, notifyUrl, notifyContentType and callbackData (text); at the root, bulkId groups the campaign.

# Batch: several messages and recipients in one request, with per-request notification
curl -X POST https://rest.inalambria.com/mtmessage/massive \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "bulkId": "CAMPANA-001",
    "messages": [
      {
        "destinations": [
          { "to": "573001234567", "messageId": "1" },
          { "to": "573007654321", "messageId": "2" }
        ],
        "text": "Your installment is due on December 5",
        "notifyUrl": "https://tu-servidor.example/inalambria/estado?token=TU_TOKEN",
        "callbackData": "{\"campana\": \"cobro-dic\"}"
      }
    ]
  }'

Two-way SMS: POST /momessage

Send from your assigned short code (ShortCode) to receive replies. Returns Id, Message (OK or ERROR) and Status. User replies can also be received over SMPP (Receiver mode).

# Two-way: send from your assigned short code
curl -X POST https://rest.inalambria.com/momessage \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "MessageText": "Confirm your Thursday appointment? Reply 1 for Yes, 2 for No",
    "PhoneNumber": "573001234567",
    "ShortCode": "12345"
  }'

Status notifications

ModeUseYour endpoint’s auth
Account webhookWith /mtmessage. The URL is configured on your account (activation can take up to 10 minutes).Basic or token in the URL
Per-request callbackWith /mtmessage/massive. The URL travels in notifyUrl.Token in the URL
  • Both are enabled by writing to support with the sending accounts and the receiving URL.
  • One request per message arrives (results has a single element) when the operator accepts or rejects it; smsCount shows the segments.
  • Reply 2xx. Only 503 triggers retries: up to 5, after 10, 20, 30, 40 and 50 seconds. Any other code or no response is not retried.
  • Be idempotent on transactionNumber + to and don’t assume ordering.
  • status.name is DELIVERED_TO_HANDSET on success and NO_SUCCESS on failure.
// Delivery status receiver (Node.js)
import http from 'node:http';

const seen = new Set();

http.createServer((req, res) => {
  if (req.method !== 'POST' || !req.url.startsWith('/inalambria/estado')) {
    res.writeHead(404).end();
    return;
  }
  let body = '';
  req.on('data', (chunk) => (body += chunk));
  req.on('end', () => {
    // Acknowledge with 2xx right away; reply 503 only if you want a retry.
    res.writeHead(200).end();
    const [result] = JSON.parse(body).results; // always a single element
    const key = `${result.transactionNumber}:${result.to}`;
    if (seen.has(key)) return; // idempotency
    seen.add(key);
    console.log(result.messageId, result.status.name, result.smsCount);
  });
}).listen(8080);

WhatsApp

Send Meta-approved templates with source, destination, templateId and parameters (in the template’s exact order). A 200 confirms receipt and creates a transaction number, not final delivery.

# WhatsApp with an approved Meta template (Basic Authentication)
curl -X POST https://multichannel.inalambria.com/MultiChannelInput/SendMessageMetaWhatsApp \
  -u "$INALAMBRIA_USER:$INALAMBRIA_PASSWORD" \
  -H "Content-Type: application/json" \
  -d '{
    "source": "573000000000",
    "destination": "573000000001",
    "templateId": "ID_PLANTILLA",
    "parameters": ["Ana", "PEDIDO-4471"]
  }'

Email

  • from must belong to a sender domain verified for your account.
  • Use templateId (see GET /email/v1/templates) or html with subject. {{variable}} placeholders are filled from fields.
  • Up to 50 recipients per request; base64 attachments (up to 10 files and 8 MB; the full request cannot exceed 20 MB).
# Email with a stored template (x-api-key header)
curl -X POST https://emailrest.inalambria.com/email/v1/deliver \
  -H "x-api-key: $INALAMBRIA_EMAIL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "from": "notificaciones@tu-dominio-verificado.example",
    "fromName": "Your company",
    "templateId": "TEMPLATE_ID_ASIGNADO",
    "payload": [
      { "recipient": "usuario@example.com", "fields": { "nombre": "Ana" } }
    ]
  }'
# Returns 202: check overallStatus, errors and each recipient status.

Verify (OTP)

Inalambria Verify verifies your users’ phone numbers or email addresses with two HTTP calls. Verify handles the code, delivery, attempts, expiry and limits. It sends the code over WhatsApp, SMS or Email with an automatic cascade, and only approved verifications are billed.

StepEndpointResult
1. Send the codePOST https://verify.inalambria.com/v1/verifications201 with the id and status: "pending", without waiting for delivery.
2. Check the codePOST https://verify.inalambria.com/v1/verifications/{id}/check200 with approved, pending (wrong code) or max_attempts_reached.

This section is synced with the Verify documentation on every site release. Documentation updated October 29, 2026. The guides are in Spanish.

Get started

Guía rápidaDe cero a tu primera verificación en dos llamadas. No hay que crear aplicaciones ni plantillas antes del primer envío.

Antes de empezar

Necesitas una clave de API y un backend desde donde llamar. La clave viaja en cada petición como Authorization: Bearer <clave> y nunca debe llegar al navegador ni a una app móvil.

Atención. Una clave live_ envía mensajes reales y factura las verificaciones aprobadas. Para probar las llamadas sin enviar nada, usa una clave test_ con los destinatarios del entorno de pruebas: una clave test_ rechaza los números reales.

Tu cuenta ya trae una política por defecto (longitud del código, vigencia, intentos y cascada de canales), así que el primer envío no requiere configurar nada.

Nota. Los mensajes de error de la API (detail y hint) pueden mejorar con el tiempo. Decide con el code numérico, nunca con el texto.

1. Envía el código

Indica el destinatario: un teléfono en formato E.164 o, si el correo está configurado para tu aplicación, una dirección de correo. Opcionalmente, la cascada de canales en orden de preferencia.

Nota. Si WhatsApp todavía no está habilitado para tu aplicación, ese paso se salta al instante y el código sale por el siguiente canal de la cascada, SMS en el ejemplo. Con ["whatsapp"] solo, la verificación termina en failed. No tienes que cambiar nada en tu integración. Detalles en Cascada de canales.

cURL
curl https://verify-api.inalambria.com/v1/verifications \
  -H "Authorization: Bearer $VERIFY_API_KEY" \
  -H "Idempotency-Key: signup-8812" \
  --json '{ "to": "+573001234567", "channels": ["whatsapp", "sms"] }'
Node.js
const response = await fetch('https://verify-api.inalambria.com/v1/verifications', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.VERIFY_API_KEY}`,
    'Content-Type': 'application/json',
    'Idempotency-Key': 'signup-8812',
  },
  body: JSON.stringify({ to: '+573001234567', channels: ['whatsapp', 'sms'] }),
});
const verification = await response.json();
Python
verification = requests.post(
    "https://verify-api.inalambria.com/v1/verifications",
    headers={
        "Authorization": f"Bearer {os.environ['VERIFY_API_KEY']}",
        "Idempotency-Key": "signup-8812",
    },
    json={"to": "+573001234567", "channels": ["whatsapp", "sms"]},
).json()

La respuesta llega en cuanto la verificación existe; no espera a que el mensaje se entregue.

201 Created
{
  "id": "ver_01J9XQ4M7K2VBN3P",
  "status": "pending",
  "to": "+57******4567",
  "channel": "whatsapp",
  "attempts_remaining": 3,
  "expires_at": "2026-09-29T14:37:05.000Z",
  "resend_available_at": "2026-09-29T14:33:05.000Z",
  "created_at": "2026-09-29T14:32:05.000Z"
}
CampoQué significa
idIdentificador de la verificación. Lo necesitas para comprobar el código.
toEl destinatario, siempre enmascarado. El código nunca viaja en la respuesta.
channelEl primer canal de la cascada. En un 200, el paso en curso.
attempts_remainingCuántas comprobaciones más admite. Un código incorrecto gasta una; uno correcto, no.
expires_atDespués de este momento el código deja de valer.
resend_available_atDesde cuándo una nueva llamada reenvía el código.

Los enteros opcionales expires_in (60–1800 s), code_length (4–10) y max_attempts (1–10) sobrescriben la política de tu aplicación solo para esta verificación; brand (hasta 64 caracteres) y client_reference (hasta 128) viajan con ella. El detalle está en la referencia.

2. Comprueba el código

Envía lo que escribió tu usuario, con el id del paso anterior.

cURL
curl https://verify-api.inalambria.com/v1/verifications/ver_01J9XQ4M7K2VBN3P/check \
  -H "Authorization: Bearer $VERIFY_API_KEY" \
  --json '{ "code": "418302" }'
Node.js
const response = await fetch(
  `https://verify-api.inalambria.com/v1/verifications/${verification.id}/check`,
  {
    method: 'POST',
    headers: {
      Authorization: `Bearer ${process.env.VERIFY_API_KEY}`,
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({ code: codeFromUser }),
  },
);
const result = await response.json();
Python
result = requests.post(
    f"https://verify-api.inalambria.com/v1/verifications/{verification['id']}/check",
    headers={"Authorization": f"Bearer {os.environ['VERIFY_API_KEY']}"},
    json={"code": code_from_user},
).json()
200 OK
{
  "id": "ver_01J9XQ4M7K2VBN3P",
  "status": "approved",
  "attempts_remaining": 3,
  "verified_at": "2026-09-29T14:32:41.000Z",
  "channel_used": "whatsapp"
}

verified_at y channel_used solo aparecen cuando la verificación se aprueba.

3. Actúa según el resultado

Un código incorrecto no es un error HTTP: responde 200 y el resultado viaja en status. Los 4xx quedan para peticiones que no se pudieron atender.

RespuestaQué pasóQué hacer
200 approvedCódigo correcto.Continúa el flujo de tu usuario.
200 pendingCódigo incorrecto; quedan intentos.Pide el código otra vez. attempts_remaining bajó en uno.
200 max_attempts_reachedSe agotaron los intentos.Crea una verificación nueva si quieres reintentar.
409 · 30002La verificación ya terminó: aprobada, expirada, fallida o sin intentos.No reintentes esa verificación.
404 · 30001El id no existe o pertenece a otra cuenta, aplicación o entorno.Revisa que usas el id de la respuesta de creación.
400 · 20002El código no tiene el formato esperado, o no es una cadena JSON.No se gasta un intento: valida la longitud en tu formulario.

Envía code como cadena. Los espacios alrededor y las mayúsculas no importan; los espacios en medio, sí. Envía también una Idempotency-Key en esta llamada: si se pierde la respuesta de un código correcto, reintentar con la misma clave devuelve el approved original; sin ella, el reintento responde 409.

Node.js
switch (result.status) {
  case 'approved':
    return markPhoneAsVerified(user);
  case 'pending':
    return askAgain({ attemptsLeft: result.attempts_remaining });
  case 'max_attempts_reached':
    return offerNewCode();
}

Reenviar el código

No hay un endpoint de reenvío: volver a crear la verificación es el reenvío. Si ya hay una activa para ese destinatario, recibes la misma con 200, nunca un 409.

  • Antes de resend_available_at, no se envía nada nuevo: te devolvemos la verificación en curso.
  • Después, se reenvía el mismo código por el canal en curso y el plazo de reenvío vuelve a empezar. expires_at no se mueve. El reenvío vuelve a pasar por los límites, así que puede responder 429 o 403; la verificación en curso queda intacta.
  • Por correo, si el envío anterior fue incierto, no se reenvía nada: te devolvemos la verificación en curso. Detalles en Cascada de canales.
  • Mientras hay una verificación activa, las opciones de la nueva llamada (channels, expires_in, code_length, max_attempts, brand, client_reference) se ignoran, aunque se siguen validando. Cuando termina, la siguiente llamada crea una verificación nueva con un código nuevo.
  • Usa una Idempotency-Key nueva en cada «Reenviar»: la misma clave repite la primera respuesta y no envía nada. Más en Reintentos seguros.

Así un usuario que pulsa «Reenviar» dos veces no dispara dos mensajes ni recibe dos códigos distintos.

View this guide on docs.inalambria.com

AutenticaciónCada petición lleva tu clave de API en el encabezado Authorization. Una clave live envía mensajes reales; una clave test usa el entorno de pruebas.

La clave en cada petición

Encabezado
Authorization: Bearer test_akey_01J9XQ4M7K2VBN3PWD5Q8R7T6C_4F9…

La API solo acepta el esquema Bearer. Cualquier otra forma responde 401 con el código 10001.

Importante. La clave va solo en tu backend. Nunca la incluyas en el código de un navegador ni de una app móvil: quien la tenga puede enviar códigos a tu nombre.

Formato de la clave

Una clave se lee entorno_akey_identificador_secreto: tres partes, y el identificador lleva su propio prefijo akey_.

ParteEjemploQué es
Entornolive o testProducción o pruebas.
Identificadorakey_01J9XQ4M7K2VBN3PWD5Q8R7T6CIdentifica la clave. Aparece en registros y soporte.
Secreto52 caracteres en mayúsculasDistingue mayúsculas de minúsculas. Nunca se muestra dos veces.

Pruebas y producción

Las claves test_ y live_ usan la misma API, pero viven en dos entornos separados.

  • Una clave live_ envía mensajes reales y sus verificaciones aprobadas se facturan.
  • Una clave test_ no envía nada: solo acepta los destinatarios fijos del entorno de pruebas, el código es siempre el mismo y nada se factura.
  • Una verificación creada en un entorno no existe para el otro: comprobarla con una clave del otro entorno responde 404 con 30001.

Obtener y revocar claves

Hoy las claves las emite el equipo de Inalambria. El secreto se entrega una sola vez; guárdalo en tu gestor de secretos.

Cuando una clave se revoca, las peticiones responden 401 con 10002. Puede seguir aceptándose durante unos segundos (siempre menos de un minuto) mientras expira su caché.

Errores de autenticación

CódigoHTTPCuándo
10001401La clave falta, está mal formada o no existe.
10002401La clave fue revocada.
10003403La clave está restringida a ciertas direcciones IP y la petición llegó desde otra.
10010403Al crear una verificación: la aplicación no tiene Verify habilitado.
40003429Demasiados fallos de autenticación desde tu IP.

Nota. Los fallos de autenticación repetidos desde una misma IP activan un bloqueo temporal: por defecto, 20 fallos en 60 segundos. Mientras dura, toda petición desde esa IP responde 429 con un Retry-After que dice cuántos segundos esperar.

View this guide on docs.inalambria.com

Entorno de pruebasPrueba tu integración con una clave test_ sin enviar un solo mensaje. Destinatarios fijos, un código fijo y la misma API que producción.

Qué es el entorno de pruebas

Una clave test_ habla con la misma API que una clave live_, pero nada sale de la plataforma: no se envía ningún WhatsApp, SMS ni correo, y nada se factura. En lugar de un número real usas los destinatarios de abajo, y el código es siempre el mismo.

Todo lo demás funciona como en producción: las respuestas, la cascada de canales, los intentos, el vencimiento, los límites, la Idempotency-Key y los webhooks.

Destinatarios de prueba

Con una clave test_ solo se aceptan estos destinatarios. Cualquier otro responde 400 con 20002 (sandbox_recipient_not_allowed). El mismo código rechaza estos destinatarios cuando la clave es live_.

TeléfonoCorreoQué pasa con cada envío
+12025550101success@sandbox.invalidSe acepta en todos los canales. Unos segundos después el sandbox lo reporta como entregado.
+12025550102definitive@sandbox.invalidSe rechaza en WhatsApp y correo. Se acepta en SMS y luego se reporta como entregado.
+12025550103transient@sandbox.invalidFalla en todos los canales.
+12025550104timeout@sandbox.invalidSe acepta en todos los canales. Nunca se reporta nada: el envío queda sin confirmar hasta que la verificación expira.
+12025550105—Se acepta y se reporta como entregado. Su SIM cambió hoy: sirve para probar la protección contra SIM swap.
+12025550106delivery_failed@sandbox.invalidSe acepta en todos los canales y luego se reporta como fallo definitivo: la cascada pasa al siguiente paso de inmediato.
+12025550107delivery_transient@sandbox.invalidSe acepta en todos los canales y luego se reporta como fallo transitorio: la cascada espera el tiempo del canal antes de avanzar.

Para la verificación, «aceptado» y «rechazado» significan lo mismo que en producción:

  • Un envío aceptado espera el tiempo del canal y luego pasa al siguiente paso. A menos que un reporte de entrega diga otra cosa (más abajo), la verificación sigue pending hasta que tu usuario comprueba el código o vence.
  • Un envío rechazado pasa al siguiente paso al instante. Cuando todos los pasos se rechazan, la verificación termina en failed y el webhook verification.failed trae reason: "cascade_exhausted".

Dos ejemplos con channels: ["whatsapp", "sms"]:

DestinatarioQué pasa
+12025550102WhatsApp se rechaza al instante y el paso de SMS se acepta. Al aprobar, channel_used es sms.
+12025550103Los dos pasos fallan y la verificación termina en failed enseguida.

El código

El entorno de pruebas no sortea un código: es siempre el comienzo de una secuencia fija, cortada a la longitud del código.

Tipo de códigoSecuenciaCon 6 caracteres
numeric2345678923234567
alphanumericABCDEFGHJKABCDEF

Un código numérico de 4 dígitos es 2345; uno de 8, 23456789. Compruébalo como cualquier otro: el correcto responde approved y uno incorrecto gasta un intento. Una verificación live_ nunca recibe este valor ni lo acepta, así que un código aprendido en pruebas no sirve en producción.

Canales

Con una clave test_ los tres canales están disponibles sin configurar nada: ni plantilla ni remitente de WhatsApp, ni plantilla de correo. La cascada, la espera por canal y los campos channel y channel_used se comportan como en producción.

Lo que el entorno de pruebas no simula:

  • El mensaje. Nadie recibe nada: no hay texto que leer.

Cómo llegar a cada estado

Todos los estados que tu integración debe manejar se pueden alcanzar con los destinatarios de arriba y la misma API. Ninguno necesita un número especial fuera de la tabla.

Quieres verHaz esto
approvedCrea con +12025550101 y comprueba el código fijo.
Un código incorrectoComprueba cualquier otro código: la verificación sigue pending y gasta un intento.
max_attempts_reachedSigue comprobando códigos incorrectos hasta agotar los intentos.
expiredCrea con "expires_in": 60 y espera un minuto sin comprobar.
Salto al siguiente canalCrea con +12025550102 y channels: ["whatsapp", "sms"].
failed (cascade_exhausted)Crea con +12025550103.
Aceptado pero nunca confirmadoCrea con +12025550104 y no compruebes: nunca llega un reporte y queda pending hasta que expira.
verification.channel.deliveredCrea con +12025550101: el webhook llega unos tres segundos después del envío.
Un fallo de entrega tras la aceptaciónCrea con +12025550106 (verification.channel.failed, la cascada avanza ya) o +12025550107 (el mismo evento, la cascada espera).
Rechazo por SIM swapCrea con +12025550105 con una aplicación que bloquea cambios recientes.
Destinatario no permitidoUsa cualquier otro destinatario: 400 con 20002.

Separado de producción

El entorno de pruebas y producción son dos mundos separados bajo la misma cuenta.

En el entorno de pruebas
VerificacionesUna creada con clave test_ solo se puede comprobar con una clave test_ de la misma aplicación. Con cualquier otra clave responde 404 con 30001, como si no existiera.
LímitesAplican los mismos límites por destinatario y por aplicación, con contadores propios: el tráfico de pruebas nunca consume tu cupo de producción.
Idempotency-KeyLas claves son por entorno: una clave usada en pruebas queda libre en producción.
WebhooksUn endpoint pertenece a un solo entorno. Los eventos de pruebas solo llegan a endpoints registrados para test, y cada evento dice cuál es en data.environment.
FacturaciónNada se factura. Una verificación approved de pruebas nunca produce un evento facturable.

Pruébalo desde la consola

La consola tiene una pantalla Sandbox que ejecuta estas llamadas contra la API real, para que explores cada parámetro sin escribir código.

  • Pega una clave. Pega una clave test_ cada vez: la consola nunca la guarda y solo muestra sus últimos cuatro caracteres. Una clave live_ también sirve, con un aviso de costo y una confirmación en cada envío.
  • Elige un escenario. Cada destinatario reservado de arriba es una tarjeta que rellena la petición; el formulario de parámetros y el JSON se mantienen sincronizados, y una lista de disparadores de error provoca a propósito los errores documentados.
  • Síguela. Tras una llamada, la pantalla sigue la verificación: intentos restantes, tiempo que queda, canal actual, las entregas de webhook (con reenvío para administradores) y si es facturable. Cada intercambio se ve como petición y respuesta crudas o como vista legible, con sus equivalentes en cURL y Node.js.

Pueden usarla administradores y desarrolladores. La pantalla lee a un ritmo limitado y se frena sola cuando llega al límite.

Una prueba completa

cURL
# 1. Crear: no se envía nada.
curl https://verify-api.inalambria.com/v1/verifications \
  -H "Authorization: Bearer $VERIFY_TEST_API_KEY" \
  -H "Idempotency-Key: sandbox-run-1" \
  --json '{ "to": "+12025550101", "channels": ["whatsapp", "sms"] }'

# 2. Comprobar el código fijo con el id de la respuesta.
curl https://verify-api.inalambria.com/v1/verifications/ver_01J9XQ4M7K2VBN3P/check \
  -H "Authorization: Bearer $VERIFY_TEST_API_KEY" \
  --json '{ "code": "234567" }'

La segunda llamada responde 200 con status: "approved". Repite la primera con +12025550103 para ver una verificación failed y su webhook.

View this guide on docs.inalambria.com

Concepts

Ciclo de una verificaciónUna verificación nace pendiente y siempre termina sola en un estado final. No hay que cerrarla ni cancelarla.

De pendiente a un estado final

Toda verificación empieza en pending y termina exactamente una vez. Nadie tiene que cerrarla: si el usuario nunca escribe el código, vence sola al llegar a expires_at.

EstadoQué significaFinalSe factura
pendingActiva, esperando el código.NoNo
approvedEl usuario escribió el código correcto.SíSí, solo con clave live_
expiredVenció sin una comprobación correcta.SíNo
max_attempts_reachedSe agotaron los intentos.SíNo
failedTodos los canales de la cascada fallaron de forma definitiva.SíNo

Solo approved se factura. Un código que no llegó, un usuario que no terminó o un intento bloqueado no te cuestan nada.

Nota. El contrato reserva además canceled y blocked, pero hoy ninguna verificación llega a ellos: no hay cancelación por API y los bloqueos antifraude rechazan la petición antes de crear la verificación.

Cómo avanza

  1. Crear (POST /v1/verifications): nace en pending y empieza la cascada de canales.
  2. Comprobar (POST /v1/verifications/{id}/check):
    • código correcto → approved;
    • incorrecto con intentos → sigue pending, con un intento menos;
    • incorrecto en el último intento → max_attempts_reached.
  3. Vencer: al llegar a expires_at sin aprobación, pasa a expired. Una comprobación en ese momento o después responde 409 con 30002, igual que cualquier comprobación sobre una verificación que ya terminó.
  4. Fallar: si cada canal de la cascada falla de forma definitiva antes de vencer, pasa a failed. Si un canal aceptó el mensaje pero no sabemos si llegó, o un envío de correo fue incierto, la verificación sigue pending hasta vencer.

Parámetros que controlan el ciclo

Cada aplicación tiene su política. Puedes sobrescribirla por petición al crear la verificación:

CampoRangoError si está fuera de rango
expires_in60–1800 segundos20007
code_length4–10 caracteres20009
max_attempts1–10 intentos20011
channelshasta 4 pasos20006

El tiempo de espera por canal y el plazo de reenvío son ajustes de la aplicación, no de la petición.

Cómo te enteras del resultado

  • En la respuesta de comprobación, si el usuario escribe el código en tu app.
  • Por webhook, para los finales que ocurren sin una llamada tuya: expired y failed.
  • Por cada paso de canal, si te suscribes a los eventos verification.channel.*: si cada envío fue aceptado, rechazado o entregado.

No hay un endpoint para consultar el estado de una verificación: el resultado llega solo.

View this guide on docs.inalambria.com

Cascada de canalesDeclaras el orden de los canales en la petición. Si un canal no entrega a tiempo, el mismo código sigue por el siguiente.

Cómo funciona

La cascada es la lista channels de la petición, en orden de preferencia. Verify envía el código por el primer canal y, si no hay aprobación dentro de su tiempo de espera, pasa al siguiente.

Petición
{ "to": "+573001234567", "channels": ["whatsapp", "sms"] }
  • El código es uno solo. Cada paso lleva el mismo código, así que tu usuario puede escribir el primero que le llegue.
  • Si omites channels (o envías []), se usan los canales encendidos de tu aplicación, en su orden: un teléfono toma WhatsApp y SMS, y un correo, el correo. Por defecto están todos encendidos, con sms → whatsapp para teléfonos.
  • Solo canales encendidos. Una petición puede pedir otro orden o menos canales, pero no uno que tu aplicación tiene apagado: responde 403 con 10013.
  • Hasta 4 pasos. Una cascada más larga responde 20006.
  • El canal debe servir al destinatario: whatsapp y sms para teléfonos, email para correos. Otra combinación responde 20005.
  • Un canal puede repetirse (["sms", "sms"]): el mismo código se envía otra vez por ese canal tras su tiempo de espera. Los nombres van en minúsculas; cualquier otra cosa responde 20005.

Los canales de tu aplicación

En la consola, en Aplicación → Política de verificación, eliges el orden de WhatsApp y SMS y qué canales quedan encendidos. Al menos uno tiene que quedar encendido, y los cambios rigen desde la siguiente verificación.

  • Con el correo apagado, Verify rechaza las verificaciones a correos con 403 y 10013.
  • Con WhatsApp y SMS apagados, rechaza las de teléfonos de la misma forma.
  • Un rechazo así no crea la verificación y no se factura.

Canales disponibles

CanalEstadoDestinatario
whatsappDisponible cuando está habilitado para tu aplicaciónTeléfono
smsDisponibleTeléfono
emailDisponible cuando está habilitado para tu aplicaciónCorreo

WhatsApp necesita dos cosas que configura el equipo de Inalambria: una plantilla de autenticación aprobada por Meta y un remitente de WhatsApp asignado a tu aplicación. Mientras falte alguna, el paso de WhatsApp se salta al instante y la cascada sigue por SMS: tu integración no cambia.

El correo también lo configura el equipo de Inalambria: el envío de correo activado en la plataforma, una plantilla de correo de tu cuenta en la plataforma de correo de Inalambria, con el campo que lleva el código, y una dirección remitente asignada a tu aplicación.

Nota. Con una clave test_ los tres canales están disponibles sin configurar nada, y no se envía nada. Mira el entorno de pruebas.

Atención. Un correo tiene un solo canal posible, email, así que no hay respaldo. Si el correo no está configurado para tu aplicación, la verificación termina en failed al instante.

Cuándo pasa al siguiente canal

Qué pasó con el pasoQué hace la cascada
El canal no está habilitado o el proveedor rechazó el envíoPasa al siguiente al instante.
No se pudo contactar al proveedor (SMS, WhatsApp)Cuenta como paso fallido: pasa al siguiente al instante. El correo se trata como incierto, más abajo.
El proveedor aceptó el mensajeEspera el tiempo del canal (por defecto 120 segundos) y, si no hubo aprobación, pasa al siguiente.
El usuario escribió el código correctoTermina: approved.

Que WhatsApp acepte un mensaje no confirma que llegó: WhatsApp no nos reporta la entrega. Por eso la cascada espera el tiempo del canal antes de probar por SMS, en lugar de saltar enseguida.

Cada paso espera el tiempo del canal antes de que empiece el siguiente, y un paso que empezaría después de expires_at nunca corre: deja expires_in más largo que (pasos − 1) × el tiempo del canal, o los últimos canales nunca se prueban.

Correo: cuando el envío es incierto

Que el proveedor de correo acepte un mensaje solo significa que lo puso en cola; tampoco nos reporta la entrega. A veces su respuesta ni siquiera dice eso: un tiempo de espera agotado, una conexión cortada, un error del servidor o una respuesta incompleta. En esos casos el correo pudo haber salido o no, así que Verify no lo vuelve a enviar:

  • La verificación sigue pending con el mismo código. Tu usuario todavía puede escribirlo, hasta expires_at.
  • Crear la verificación de nuevo la devuelve con 200 y no envía nada, aunque ya haya pasado resend_available_at. No consume límites y resend_available_at no se mueve.
  • Ese envío no puede hacerla terminar en failed: salvo que tu usuario la apruebe o agote los intentos, termina en expired.

Qué canal ves en cada respuesta

  • channel, en la creación: el primer paso de la cascada, aunque ese canal termine saltándose. En un 200 (reutilizada o reenviada), el paso en curso en ese momento.
  • channel_used, en la aprobación: el paso que estaba en curso cuando tu usuario escribió el código.

Como todos los pasos llevan el mismo código, channel_used no garantiza que ese fuera el mensaje que tu usuario leyó.

El texto del mensaje

El SMS lo puedes escribir tú, en la consola, en Aplicación → Mensaje SMS. Lleva {{code}} una vez, donde va el código, y si quieres {{minutes}}, los minutos que dura; ningún otro marcador, hasta 300 caracteres. Mientras no escribas uno, sale el de la plataforma:

SMS
Tu codigo de verificacion es 418302. Vence en 5 minutos. No lo compartas con nadie.

Los minutos son el expires_in de la verificación, redondeado hacia arriba, no el tiempo que queda cuando sale ese mensaje en particular.

Sin tildes, en un SMS caben 160 caracteres. Una letra como «ó» o un emoji cambian la codificación y caben 70, así que un mensaje largo puede ocupar dos SMS. La consola muestra cuántos ocupa mientras lo escribes.

En WhatsApp se usa la plantilla de autenticación aprobada por Meta, igual para todas las cuentas. El campo brand aún no aparece en el texto de ningún canal.

El correo usa la plantilla de tu cuenta en la plataforma de correo de Inalambria. Verify solo completa el código: todo lo demás del mensaje sale de esa plantilla.

Cuándo falla

Una verificación termina en failed solo si cada paso falla de forma definitiva: el proveedor lo rechazó o no se pudo contactar, el canal no está disponible o configurado, o el operador confirmó que no se entregó. El correo es la excepción: un envío incierto nunca cuenta como fallo.

Si un canal aceptó el mensaje pero nadie confirmó la entrega, o el envío de correo fue incierto, no cuenta como fallo: la verificación sigue pending hasta vencer.

View this guide on docs.inalambria.com

Límites y antifraudeVerify frena el abuso antes de gastar un mensaje. Los límites vienen activos y lo que se bloquea no se factura.

Qué se revisa antes de enviar

Cada vez que una petición va a enviar un mensaje, al crear o al reenviar, Verify revisa estos controles en orden. Si alguno se activa, no se envía nada y la petición no se factura.

ControlHTTPCódigo
País del destinatario no habilitado (solo teléfonos)40340012
Destinatario bloqueado: número o dirección exactos, o prefijo del número40340011
Demasiadas verificaciones para el mismo destinatario42940001
Demasiadas verificaciones para la aplicación42940002
La SIM del número cambió hace poco, si activaste la protección contra SIM swap (solo teléfonos)40340014

Devolver una verificación que sigue activa, sin enviar nada nuevo, no consume los límites. Por eso un usuario impaciente que pulsa «Reenviar» no agota su cupo. La única excepción son dos creaciones simultáneas para el mismo destinatario: las dos cuentan.

Los contadores son por entorno: lo que envías con una clave test_ nunca cuenta contra tu cupo de producción, aunque en el entorno de pruebas aplican los mismos límites y bloqueos.

Límites por destinatario y por aplicación

  • Por destinatario: cuenta cuántos códigos se envían a un mismo número o dirección de correo en ventanas de tiempo, verificaciones nuevas y reenvíos por igual. Por ejemplo, 5 por hora y 20 por día. El conteo es compartido por todas las aplicaciones de tu cuenta.
  • Por aplicación: un tope global opcional para toda tu aplicación.

Hoy los valores son los mismos para todas las cuentas. Pide los vigentes a tu contacto de Inalambria si necesitas planear picos de tráfico.

Atención. Las respuestas 429 con 40001 y 40002 no incluyen Retry-After. No reintentes en bucle: muestra a tu usuario que espere y reintenta con retroceso exponencial, con una Idempotency-Key nueva: la misma clave repite el 429 guardado.

Fallos de autenticación por IP

Además, los fallos de autenticación repetidos desde una IP (por defecto, 20 en 60 segundos) bloquean esa IP durante un tiempo. Mientras dura, toda petición responde 429 con 40003 y un Retry-After en segundos.

Límite por clave

Una clave también puede llevar su propio límite de peticiones por minuto. Cuando se agota, las peticiones hechas con esa clave responden 429 con 40005 y un Retry-After en segundos; las demás claves de la misma cuenta no se ven afectadas.

Buenas prácticas

  • Valida el número en tu formulario antes de llamar: evitas un 400 20003 y le das a tu usuario el error en el momento.
  • No expongas la creación de verificaciones sin control. Pon un captcha o un límite propio por sesión delante del botón «Enviar código».
  • Guarda el X-Request-Id de las respuestas 4xx: es lo primero que pedirá soporte.

View this guide on docs.inalambria.com

Protección contra SIM swapVerify puede negarse a enviar el código a un número cuya SIM cambió hace poco. Se activa por aplicación desde la consola.

Qué es un SIM swap

Para quedarse con los códigos de alguien, un atacante convence al operador de pasar el número de esa persona a una SIM nueva. Desde ese momento, los SMS y los WhatsApp dirigidos a esa persona llegan al teléfono del atacante.

Con la protección activada, Verify consulta cuándo cambió por última vez la SIM del número antes de enviar el código. Si cambió dentro del plazo que elegiste, no envía nada y responde con un error.

Cómo activarla

En la consola, en Aplicación → Protección contra SIM swap, elige el plazo: 1 día, 3 días o 7 días. Con Desactivada queda apagada, que es como viene. Solo un administrador puede cambiarla, y el cambio rige desde la siguiente verificación.

Qué cuenta como «dentro del plazo»

El operador informa la fecha del cambio, no la hora. Por eso el plazo cuenta días de calendario e incluye el día del borde:

PlazoSe bloquea un cambio de
1 díahoy o ayer
3 díashoy o los 3 días anteriores
7 díashoy o los 7 días anteriores

Con un plazo de 1 día también se bloquea un cambio hecho ayer a las 23:59. Ningún cambio de las últimas 24 horas pasa.

A qué se aplica

  • Solo a teléfonos, por SMS y por WhatsApp. Un correo no tiene SIM y se envía sin esta revisión.
  • Al crear y al reenviar, cada vez que se va a enviar un código nuevo. Devolver una verificación que sigue activa no envía nada y no vuelve a consultar. Comprobar un código tampoco consulta.
  • Después de los límites: una petición que ya frenó un límite no llega a consultar el cambio de SIM.

La respuesta

Cuando la SIM cambió dentro del plazo, la verificación no se crea y la petición responde 403 con 40014:

403 Forbidden
{
  "type": "https://docs.inalambria.com/verify/errors/40014",
  "title": "sim_swap_recent",
  "status": 403,
  "detail": "La SIM del número cambió hace poco y la aplicación no envía códigos en ese caso.",
  "code": 40014,
  "hint": "Verificá la identidad de la persona por otro medio antes de volver a intentarlo.",
  "request_id": "req_01J9XQ4M7KZ3T8V2W6N5P0QRST"
}

Una petición rechazada así no se factura. Reintentarla da el mismo resultado mientras dure el plazo: pide a tu usuario que confirme su identidad por otra vía, por ejemplo verificando su correo.

Si en ese momento no se puede consultar el cambio de SIM, Verify envía el código igual y deja constancia en sus registros.

Probarla en el entorno de pruebas

Con una clave test_, el último cambio de SIM de cada destinatario de prueba es fijo:

TeléfonoÚltimo cambio de SIMCon la protección activada
+12025550105HoySe rechaza con 40014, con cualquier plazo.
+120255501011 de enero de 2020Se envía.
+12025550102Sin registroSe envía.
+12025550103Fuera de coberturaSe envía.
+12025550104La consulta fallaSe envía.

Consultar el cambio de SIM por tu cuenta

POST /v1/tools/sim-swap dice cuándo cambió por última vez la SIM de un número, sin crear una verificación. Sirve para revisarlo en otros momentos, como antes de un cambio de contraseña o de una transferencia.

cURL
curl https://verify-api.inalambria.com/v1/tools/sim-swap \
  -H "Authorization: Bearer $VERIFY_API_KEY" \
  --json '{ "to": "+573001234567" }'
Node.js
const response = await fetch('https://verify-api.inalambria.com/v1/tools/sim-swap', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.VERIFY_API_KEY}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({ to: '+573001234567' }),
});
const simSwap = await response.json();
Python
sim_swap = requests.post(
    "https://verify-api.inalambria.com/v1/tools/sim-swap",
    headers={"Authorization": f"Bearer {os.environ['VERIFY_API_KEY']}"},
    json={"to": "+573001234567"},
).json()
200 OK
{
  "status": "swap_detected",
  "last_swap_date": "2026-10-25",
  "days_since_swap": 3
}
statusQué significa
swap_detectedHay un cambio registrado: last_swap_date trae su fecha y days_since_swap, los días desde entonces.
unknownEl operador no tiene un cambio registrado para el número.
out_of_coverageEl operador o el país del número no entrega este dato.

Con unknown y out_of_coverage, last_swap_date y days_since_swap vienen en null. Con una clave test_ responde lo que dice la tabla de la sección anterior.

Los errores propios de esta consulta:

HTTPCódigoCuándo
40310010La consulta no está habilitada para tu aplicación. Pídela a tu contacto de Inalambria.
42940006Tu aplicación pasó de 60 consultas en un minuto.
50350011No se pudo consultar al operador. Reintenta en unos minutos.

View this guide on docs.inalambria.com

PrivacidadEl código nunca existe en claro fuera del mensaje que recibe tu usuario, y los destinatarios siempre vuelven enmascarados.

El código nunca en claro

El código de verificación solo existe en claro en el mensaje que recibe tu usuario.

  • La API nunca lo devuelve. No hay respuesta, campo ni webhook que lo incluya.
  • Nunca se guarda ni se registra en claro. Se guarda con hash, para comprobarlo, y cifrado, para poder reenviar el mismo código. Nunca aparece en registros ni en trazas.
  • Ninguna herramienta lo muestra, tampoco las del equipo de soporte.

Destinatarios enmascarados

Cada vez que un destinatario aparece en una respuesta o en un registro, aparece enmascarado.

TipoEnviadoDevuelto
Teléfono+573001234567+57******4567
Correojuanita@ejemplo.comj*****a@ejemplo.com

Del teléfono se conservan los tres primeros caracteres (+ y dos dígitos) y los últimos cuatro. Del correo, la primera y la última letra del usuario, y el dominio completo.

Mensajes de error que no repiten tus datos

El detail de cada error es un texto fijo: nunca interpola lo que enviaste. Un número mal formado responde «El número indicado no es un número móvil válido en formato E.164», sin repetir el número.

Qué conviene guardar de tu lado

  • El id de la verificación, para relacionarla con tu usuario.
  • El X-Request-Id de cada respuesta, para soporte.
  • Si lo necesitas, una client_reference propia (hasta 128 caracteres) que viaja en los webhooks. No pongas datos personales en ella.

View this guide on docs.inalambria.com

Integration

Reintentos segurosCon Idempotency-Key puedes repetir cualquier POST sin miedo a crear una segunda verificación ni a enviar un segundo código.

Por qué hace falta

Una red inestable puede cortar la respuesta aunque la petición sí llegó. Si reintentas a ciegas, podrías crear dos verificaciones. Con Idempotency-Key, el reintento devuelve exactamente la misma respuesta que la primera vez.

Encabezado
Idempotency-Key: signup-8812-attempt-1

Funciona en los dos endpoints. Es opcional, pero recomendado en toda llamada que tu código pueda repetir.

Cómo se comporta

SituaciónRespuesta
Primera vez con esa claveSe procesa normalmente y se guarda la respuesta.
Misma clave, mismo cuerpoSe devuelve la respuesta guardada: el mismo estado HTTP y el mismo cuerpo. No se envía nada de nuevo.
Misma clave, cuerpo distinto422 con 20010. La clave ya está atada a otra petición.
Misma clave, la primera petición sigue en curso409 con 20010 y un Retry-After. Espera y repite.
  • La clave vale 24 horas y es por cuenta y por entorno: dos cuentas pueden usar la misma sin chocar, y también tus claves test_ y live_.
  • Admite de 1 a 255 caracteres. Fuera de ese rango responde 400 con 20002.
  • «Mismo cuerpo» significa el mismo método, la misma ruta y los mismos bytes del cuerpo.
  • Las respuestas 2xx y 4xx se guardan, 429 incluido: para reintentar tras un límite, usa una clave nueva. Un 5xx no se guarda: puedes reintentar con la misma clave y la petición se procesa de nuevo.
  • La clave es compartida por los dos endpoints: no reutilices una clave de creación en /check.

Cómo elegir la clave

Usa algo que identifique la intención, no el intento: el mismo valor en cada reintento de la misma acción, y un valor nuevo para cada acción nueva. Un «Reenviar» es una acción nueva y necesita otra clave (por ejemplo signup-8812-send-2): reutilizar la clave de creación repite la primera respuesta y no envía nada. En /check, usa una clave por cada código que escriba tu usuario.

Node.js
// Una clave por intento de registro, reutilizada en cada reintento de red.
const key = `signup-${signupId}`;

for (let attempt = 0; attempt < 3; attempt++) {
  const response = await fetch(url, {
    method: 'POST',
    headers: { ...headers, 'Idempotency-Key': key },
    body,
  });
  if (response.status < 500) return response;
  await sleep(2 ** attempt * 500);
}

Consejo. Sin Idempotency-Key, Verify igual te protege del doble clic: volver a crear una verificación para un destinatario que ya tiene una activa te devuelve esa misma, con 200. La clave de idempotencia cubre además el caso de la red: la respuesta perdida.

View this guide on docs.inalambria.com

ErroresCada error dice qué pasó, con un código estable para tu código y un mensaje para las personas. Este catálogo se genera desde el de la API.

Formato

Todo 4xx y 5xx responde con application/problem+json (RFC 9457):

400 Bad Request
{
  "type": "https://docs.inalambria.com/verify/errors/20003",
  "title": "invalid_phone_number",
  "status": 400,
  "detail": "El número indicado no es un número móvil válido en formato E.164.",
  "code": 20003,
  "field": "to",
  "hint": "Incluye el indicativo de país precedido de '+'. Para Colombia: +57 seguido de 10 dígitos.",
  "request_id": "req_01J9XQ4M7KZ3T8V2W6N5P0QRST"
}
CampoPara qué sirve
codeDecide con este. Es estable: no cambia entre versiones.
titleEl nombre del error, legible y estable. Algunos códigos agrupan casos relacionados; title y field los distinguen.
detailQué pasó, en español. Puede mejorar con el tiempo: no lo compares como texto.
hintQué hacer, cuando hay una acción clara.
fieldEl campo de la petición que lo causó, cuando aplica.
request_idEl mismo valor que el encabezado X-Request-Id. Inclúyelo al pedir soporte.
typeEnlace a la entrada de este catálogo.

Las respuestas que se producen antes de que tu petición llegue a la API, como 404 por una ruta desconocida, 405, 413 por un cuerpo mayor de 16 KiB o 415 por un Content-Type que no es JSON, no traen code: para esas decide con status.

Consejo. Un código incorrecto no es un error: responde 200 con status: "pending". Los errores quedan para peticiones que no se pudieron atender.

Qué reintentar

  • 5xx: sí, con la misma Idempotency-Key y retroceso exponencial.
  • 429: sí, después de esperar y con una Idempotency-Key nueva. Respeta Retry-After cuando viene.
  • 409 con 20010: sí, después del Retry-After; la primera petición sigue en curso.
  • Cualquier otro 4xx: no. Corrige la petición: repetirla dará el mismo resultado.

Autenticación (10000–10999)

La clave de API o el producto de la aplicación.

10001

HTTP 401

  • invalid_api_key — La clave de API es inválida. Verificá que la clave enviada en el encabezado Authorization sea correcta y esté vigente.
10002

HTTP 401

  • revoked_api_key — La clave de API fue revocada. Emití una nueva clave desde la consola; esta ya no puede usarse.
10003

HTTP 403

  • api_key_ip_not_allowed — La clave de API no puede usarse desde esta dirección IP. Revisá las direcciones IP permitidas de la clave en la consola.
10010

HTTP 403

  • product_not_enabled — La aplicación no tiene este producto habilitado. Contactá a soporte para habilitar el producto en esta aplicación.
10011

HTTP 401

  • api_key_not_found — La clave de API indicada no existe o no pertenece a esta cuenta.
10013

HTTP 403

  • channel_not_enabled — La aplicación tiene apagado el canal que hace falta para esta verificación. Revisá los canales encendidos de la aplicación en la consola de Verify.

Petición inválida (20000–20999)

El cuerpo o los encabezados no cumplen el contrato. Corrige la petición antes de reintentar.

20001

HTTP 400

  • malformed_json — El cuerpo de la petición no es un JSON válido. Verificá que el cuerpo enviado sea JSON bien formado.
20002

HTTP 400

  • sandbox_recipient_not_allowed — El destinatario no está permitido para el entorno autenticado. Utilice destinos documentados de prueba únicamente con claves test.
  • missing_field — Falta un campo requerido en la petición.
  • invalid_request_field — Un campo de la petición tiene un tipo inválido.
  • idempotency_key_invalid — La cabecera Idempotency-Key es inválida. Debe tener entre 1 y 255 caracteres.
  • malformed_code — El código enviado no tiene el formato esperado.
  • resend_cooldown_out_of_range — La configuración de reenvío de la aplicación está fuera de rango.
  • channel_timeout_out_of_range — El tiempo de espera del canal configurado está fuera de rango.
20003

HTTP 400

  • invalid_phone_number — El número indicado no es un número móvil válido en formato E.164. Incluye el indicativo de país precedido de '+'. Para Colombia: +57 seguido de 10 dígitos.
20004

HTTP 400

  • invalid_email — La dirección de correo indicada no es válida.
20005

HTTP 400

  • channel_incompatible_with_recipient — El canal indicado no es compatible con el tipo de destinatario. Los canales whatsapp/sms requieren un teléfono; email requiere una dirección de correo.
20006

HTTP 400

  • cascade_too_long — La cascada de canales tiene más pasos de los permitidos.
20007

HTTP 400

  • ttl_out_of_range — El tiempo de expiración solicitado está fuera de rango.
20009

HTTP 400

  • code_length_out_of_range — La longitud de código solicitada está fuera de rango.
20010

HTTP 422, 409

  • idempotency_key_reuse — La clave de idempotencia ya fue usada con un cuerpo distinto.
  • idempotency_request_in_flight — Ya hay una petición en curso con esta clave de idempotencia. Reintentá luego del tiempo indicado en Retry-After.
20011

HTTP 400

  • max_attempts_out_of_range — La cantidad máxima de intentos solicitada está fuera de rango.
20012

HTTP 400

  • code_type_invalid — El tipo de código configurado no es válido.
20013

HTTP 400

  • brand_invalid — El nombre de marca indicado no es válido. Debe tener hasta 64 caracteres y no contener caracteres de control.
20014

HTTP 400

  • client_reference_invalid — La referencia de cliente indicada no es válida. Debe tener hasta 128 caracteres y no contener caracteres de control.

Estado de la verificación (30000–30999)

La verificación no existe o ya terminó.

30001

HTTP 404

  • verification_not_found — La verificación indicada no existe.
30002

HTTP 409

  • verification_terminal — La verificación ya alcanzó un estado final y no acepta más intentos.

Límites y antifraude (40000–40999)

La petición es válida pero no se atiende. El tráfico bloqueado no se factura.

40001

HTTP 429

  • recipient_rate_limit_exceeded — Se superó el límite de solicitudes para este destinatario.
40002

HTTP 429

  • application_rate_limit_exceeded — Se superó el límite de solicitudes para esta aplicación.
40003

HTTP 429

  • ip_rate_limit_exceeded — Se superó el límite de solicitudes para esta dirección IP.
40004

HTTP 429 · Aún no se emite

  • custom_key_rate_limit_exceeded — Se superó el límite de solicitudes para esta clave personalizada.
40005

HTTP 429

  • api_key_rate_limit_exceeded — Se superó el límite de solicitudes por minuto de esta clave de API. Esperá el tiempo indicado en Retry-After antes de reintentar.
40006

HTTP 429

  • sim_swap_rate_limit_exceeded — La aplicación superó su límite de consultas de SIM swap por minuto. Esperá un minuto antes de volver a consultar.
40010

HTTP 403 · Aún no se emite

  • anti_fraud_blocked — La solicitud fue bloqueada por el motor antifraude.
40011

HTTP 403

  • recipient_blocked — El destinatario está en la lista de bloqueo.
40012

HTTP 403

  • country_not_enabled — El país del destinatario no está habilitado para esta aplicación.
40013

HTTP 403 · Aún no se emite

  • preflight_denied — La solicitud fue denegada por la validación previa al envío.
40014

HTTP 403

  • sim_swap_recent — La SIM del número cambió hace poco y la aplicación no envía códigos en ese caso. Verificá la identidad de la persona por otro medio antes de volver a intentarlo.

Plataforma (50000–50999)

Algo falló de nuestro lado. Reintenta con la misma Idempotency-Key.

50010

HTTP 500

  • internal_error — Ocurrió un error interno. Intentá nuevamente más tarde.
50011

HTTP 503

  • sim_swap_provider_unavailable — No se pudo consultar el cambio de SIM con el proveedor. Intentá nuevamente en unos minutos.

View this guide on docs.inalambria.com

WebhooksVerify avisa a tu backend cuando una verificación termina, y cómo fue cada paso de canal. Cada evento va firmado con Standard Webhooks y se reintenta hasta dos días.

Para qué sirven

La respuesta de comprobación te dice si el código es correcto. Pero hay finales que ocurren sin una llamada tuya: la verificación vence o se agotan los canales. El webhook te avisa de esos finales. Si quieres, también te cuenta cómo fue cada paso de canal por el camino.

Eventos

EventoCuándo
verification.approvedEl usuario escribió el código correcto.
verification.expiredVenció sin una comprobación correcta.
verification.failedTerminó sin aprobarse. data.reason dice por qué: max_attempts_reached o cascade_exhausted.
verification.channel.sentUn canal aceptó el mensaje.
verification.channel.deliveredEl operador confirmó la entrega. Hoy solo lo reporta SMS.
verification.channel.failedUn canal rechazó el envío, o el operador reportó que no pudo entregarlo.

Recibes exactamente uno de los tres primeros por verificación, cuando llega a su estado final. Los eventos de canal llegan mientras está en curso, uno por envío; un endpoint suscrito a todos los tipos de evento los recibe todos.

Qué recibes

Un POST a tu URL con este cuerpo:

Cuerpo
{
  "id": "evt_01M2K81GC7W06ZRKDS9K21QNDJ",
  "type": "verification.failed",
  "occurred_at": "2026-09-29T14:37:05.000Z",
  "sequence": null,
  "data": {
    "verification_id": "ver_01J9XQ4M7K2VBN3P",
    "application_id": "app_01J9XQ2B8Y6T4R1M0K9H7G5F3D",
    "environment": "live",
    "status": "max_attempts_reached",
    "reason": "max_attempts_reached",
    "client_reference": "signup-8812"
  }
}

reason solo aparece en verification.failed. client_reference es el valor que enviaste al crear la verificación.

En los eventos de canal, data describe el envío:

Cuerpo · evento de canal
{
  "id": "evt_01M2K81GC7W06ZRKDS9K21QNDK",
  "type": "verification.channel.failed",
  "occurred_at": "2026-09-29T14:32:06.000Z",
  "sequence": null,
  "data": {
    "verification_id": "ver_01J9XQ4M7K2VBN3P",
    "application_id": "app_01J9XQ2B8Y6T4R1M0K9H7G5F3D",
    "environment": "live",
    "attempt_id": "atm_01J9XQ4M8A1B2C3D4E5F6G7H8J",
    "channel": "whatsapp",
    "step": 0,
    "attempt": 0,
    "send_state": "rejected_definitive"
  }
}
CampoQué significa
channel, stepEl canal y su posición en la cascada, empezando en 0.
attempt0 en el primer envío de ese paso; cada reenvío suma uno.
send_stateEn channel.sent, siempre accepted. En channel.failed, por qué falló el envío: rejected_definitive, unavailable_transient, channel_unavailable o denied.
delivery_stateSolo cuando el operador reportó: delivered en channel.delivered; failed_definitive o failed_transient en channel.failed.

Un channel.failed no significa que la verificación falló: la cascada puede seguir por el siguiente canal. Por correo, un envío incierto también llega como unavailable_transient mientras la verificación sigue pending. client_reference solo viaja en los eventos finales.

Con estos encabezados:

Encabezados
content-type: application/json
webhook-id: evt_01M2K81GC7W06ZRKDS9K21QNDJ
webhook-timestamp: 1790693825
webhook-signature: v1,g0hM9SsE+OTHF9QDLvhRAmMOCQ8Qm9ZQnJwoUCP0+Tk=

Verificar la firma

La firma sigue Standard Webhooks: un HMAC-SHA256 en base64 sobre webhook-id.webhook-timestamp.cuerpo. La clave es el secreto sin el prefijo whsec_, decodificado de base64.

Node.js
import { createHmac, timingSafeEqual } from 'node:crypto';

export function isValidWebhook(rawBody: string, headers: Headers, secret: string): boolean {
  const id = headers.get('webhook-id');
  const timestamp = headers.get('webhook-timestamp');
  const signatures = headers.get('webhook-signature');
  if (!id || !timestamp || !signatures) return false;

  // Rechaza eventos de hace más de 5 minutos: frena reenvíos maliciosos.
  if (Math.abs(Date.now() / 1000 - Number(timestamp)) > 300) return false;

  const key = Buffer.from(secret.replace(/^whsec_/, ''), 'base64');
  const expected = createHmac('sha256', key).update(`${id}.${timestamp}.${rawBody}`).digest();

  // Durante una rotación llegan dos firmas separadas por un espacio.
  return signatures.split(' ').some((candidate) => {
    const [version, signature] = candidate.split(',');
    if (version !== 'v1' || !signature) return false;
    const received = Buffer.from(signature, 'base64');
    return received.length === expected.length && timingSafeEqual(received, expected);
  });
}
Python
# pip install standardwebhooks
from standardwebhooks.webhooks import Webhook

webhook = Webhook(os.environ["VERIFY_WEBHOOK_SECRET"])  # whsec_…

# Lanza una excepción si la firma o la marca de tiempo no son válidas.
event = webhook.verify(raw_body, request.headers)

Atención. Verifica la firma sobre el cuerpo crudo, tal como llegó. Si tu framework ya lo convirtió a JSON y lo vuelves a serializar, la firma no coincidirá.

Responder y reintentos

  • Responde con un 2xx en menos de 5 segundos. Si tienes trabajo pesado, encólalo y responde enseguida.
  • Un 408, 425, 429, un 5xx, un timeout o un error de red, DNS o TLS se reintenta hasta 7 veces: 1 min, 5 min, 30 min, 2 h, 6 h, 12 h y 24 h después del intento anterior, con una variación de ±20 %, unas 45 horas en total. Después, el evento se descarta. Si respondes Retry-After, podemos adelantar el reintento, nunca atrasarlo.
  • Cualquier otro 3xx o 4xx detiene los reintentos. Las redirecciones no se siguen.
  • Un mismo evento puede llegar más de una vez: descarta los repetidos por su webhook-id.
  • Los eventos pueden llegar desordenados: usa occurred_at. sequence está reservado y por ahora es null.
  • Si tu endpoint sigue fallando, las entregas hacia él se pausan un rato, hasta una hora, y se reanudan solas.
  • Tu URL debe resolver a una dirección pública; una dirección privada o de loopback se rechaza sin reintentos.

Registrar tu endpoint

Hoy el equipo de Inalambria registra tu URL: debe ser https, y se registra para un solo entorno, live o test. La misma URL puede registrarse una vez por entorno, cada una con su propio secreto. Un endpoint test solo recibe eventos del entorno de pruebas, y cada evento dice su entorno en data.environment. También puedes elegir qué tipos de evento recibe; si no eliges, recibe todos, eventos de canal incluidos.

Al registrarla recibes el secreto whsec_… una sola vez; guárdalo en tu gestor de secretos.

Cuando el secreto rota, durante 24 horas cada evento llega firmado con el secreto nuevo y con el anterior. El código de arriba acepta cualquiera de las dos.

View this guide on docs.inalambria.com

Learn about Inalambria Verify for your business

SMPP and files

ConnectionHostPort
SMPP without SSLsmsc.inalambria.com5020
SMPP with SSL/TLSsmscssl.inalambria.com6011
Inbound messages (MO), Receiver modesmscmo.inalambria.com6900

Bind modes: Transceiver, Transmitter or Receiver, using the System ID and password Inalambria provides.

SMS by file: drop a .txt file (personalized: number and message per line; or bulk: one message for many numbers) in a configured SFTP site or S3 bucket, and the sends are generated within minutes.

Monitoring

  • GET /platformmonitory: operator status, whether they act as alternates and their delivery time, as close to real time as possible.
  • GET /bireports/effectivitybyclient: processing times by status (last 15 minutes).
  • GET /bireports/msgmtclient: messages processed by operator and status (last 15 minutes).

Value-added services: they must be enabled first.

Response codes

CodeMeaning
200Received and processing (or token issued).
202Email: request registered; check each recipient’s status.
400Invalid payload structure.
401Unauthorized: check your credentials.
403Insufficient permissions, for example an IP that is not allowed.
500Internal error: retry in a few minutes or contact support.

Service catalog

ServiceEndpointHostAuthReference
Request tokenPOST /tokenrest.inalambria.comBasicView
One-way SMS / RCSPOST /mtmessagerest.inalambria.comBearerView
Batch SMSPOST /mtmessage/massiverest.inalambria.comBearerView
Two-way SMSPOST /momessagerest.inalambria.comBearerView
Account webhookInalambria → your server—Basic or URL tokenView
Per-request callbackInalambria → your server—URL tokenView
WhatsAppPOST /MultiChannelInput/SendMessageMetaWhatsAppmultichannel.inalambria.comBasicView
Send EmailPOST /email/v1/deliveremailrest.inalambria.comx-api-keyView
Email templatesGET /email/v1/templatesemailrest.inalambria.comx-api-keyView
Verify: send codePOST /v1/verificationsverify.inalambria.comBearerView
Verify: check codePOST /v1/verifications/{id}/checkverify.inalambria.comBearerView
Operator monitoringGET /platformmonitoryrest.inalambria.comBearerView
Effectiveness monitoringGET /bireports/effectivitybyclientrest.inalambria.comBearerView
Message status monitoringGET /bireports/msgmtclientrest.inalambria.comBearerView
SMS by fileSFTP / Amazon S3——View
SMPPsmsc.inalambria.com:5020 / :6011 (TLS)System IDView

Inalambria Express API

For small businesses and developers who want to start without a contract, the Inalambria Express API (OpenAPI 3.1, Bearer Token) offers:

  • SMS to one or many recipients
  • Batches with different messages for different groups
  • Personalized messages with templates and variables
  • Usage history, credit balance and budget
  • Async job and queue tracking

api.inalambria.express/docs · GitHub

Technical support

Email soporte@inalambria.com or open a request in the support form choosing “REST API” as the product.

Ready to communicate better with your customers?

Tell us about your needs and we’ll design the right solution with you, backed by more than 23 years of experience in Colombia.