Referencia de API

SMS y verificación

Envía un SMS suelto o verifica un número con un código de un solo uso, sin pasar por el Flow Studio y sin contratar un proveedor de SMS.

Son los mismos servicios que usa el nodo Waiify del Flow Studio, así que puedes combinarlos: enviar el código desde un flujo y verificarlo desde tu backend, o al revés.

Todos los endpoints se autentican con tu API key y consumen créditos del workspace.

El WORKSPACE_ID de los ejemplos lo copias en Configuración → Desarrolladores, en la tarjeta ID del workspace — ver Obtener el WORKSPACE_ID.

Enviar un SMS

POST /workspaces/:workspaceId/messaging/sms

Cuerpo

Campo	Tipo	Descripción
`to`	`string`	Obligatorio. Número de destino. Se acepta con `+`, con `00` o en formato local.
`message`	`string`	Obligatorio. Texto del SMS. Máximo 1.530 caracteres.
`defaultCountryCode`	`string`	Prefijo país a aplicar si `to` viene en formato local. Por defecto `52`.

Respuesta

Campo	Descripción
`to`	Número normalizado a E.164 sin el `+`.
`country`	País del destino en ISO alpha-2, o `null` si el prefijo no permite determinarlo (el `+1` lo comparten cuatro países).
`segments`	Segmentos en que se dividió el mensaje. Cada uno se cobra como un SMS.
`credits`	Créditos consumidos.
`messageId`	Identificador del envío en el proveedor.

Cuidado con los segmentos

Un SMS cabe en 160 caracteres. Una sola tilde, una ñ o un emoji cambian la codificación y bajan ese límite a 70, así que un texto de 100 caracteres con acentos cuesta el doble que sin ellos. El campo segments de la respuesta te dice exactamente cuántos se cobraron.

curl -X POST "https://api.waiify.com/api/workspaces/$WORKSPACE_ID/messaging/sms" \
  -H "Authorization: Bearer $WAIIFY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "to": "+573001234567",
    "message": "Tu pedido va en camino."
  }'

{
  "success": true,
  "data": {
    "to": "573001234567",
    "country": "CO",
    "segments": 1,
    "credits": 7,
    "messageId": "1234567"
  }
}

Enviar un código de verificación

POST /workspaces/:workspaceId/messaging/otp/send

Genera un código de un solo uso y lo envía por SMS. El código se guarda cifrado, vence solo y se invalida al pedir uno nuevo para el mismo número.

Cuerpo

Campo	Tipo	Descripción
`to`	`string`	Obligatorio. Número al que enviar el código.
`template`	`string`	Texto del SMS. Debe contener `{{code}}`. Admite también `{{minutes}}`. Si lo omites se usa el mensaje por defecto de Waiify.
`defaultCountryCode`	`string`	Prefijo país si `to` viene en formato local.

Respuesta

Campo	Descripción
`to`	Número normalizado. Guárdalo: es el que hay que enviar al verificar.
`expiresAt`	Fecha ISO en que vence el código.
`resendAvailableInSeconds`	Segundos que hay que esperar para poder reenviarlo. Úsalo para el contador de tu pantalla.

Límites

Para protegerte (y protegernos) del fraude de bombeo de SMS hay tres topes. Al superar cualquiera la respuesta es 429:

1 código cada 60 segundos por número.
5 códigos por hora por número.
200 códigos al día por workspace.

curl -X POST "https://api.waiify.com/api/workspaces/$WORKSPACE_ID/messaging/otp/send" \
  -H "Authorization: Bearer $WAIIFY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "to": "+573001234567",
    "template": "Tu código es {{code}}. Vence en {{minutes}} minutos."
  }'

{
  "success": true,
  "data": {
    "to": "573001234567",
    "expiresAt": "2026-08-20T15:40:00.000Z",
    "resendAvailableInSeconds": 60
  }
}

Verificar un código

POST /workspaces/:workspaceId/messaging/otp/verify

Cuerpo

Campo	Tipo	Descripción
`to`	`string`	Obligatorio. El mismo número al que se envió el código.
`code`	`string`	Obligatorio. El código que escribió el usuario.
`defaultCountryCode`	`string`	Prefijo país si `to` viene en formato local.

Respuesta

Responde 200 tanto si el código es correcto como si no: un código equivocado es un resultado previsto, no un error de la petición. Ramifica con valid.

Campo	Descripción
`valid`	`true` si el código es correcto y no ha vencido.
`reason`	Por qué no es válido: `not_found`, `expired`, `too_many_attempts` o `mismatch`. `null` si `valid` es `true`.
`attemptsLeft`	Intentos que le quedan al código antes de quedar inutilizado.

Un código correcto solo vale una vez: al canjearlo queda consumido, y un segundo intento con el mismo código responde valid: false con reason: "not_found".

Tras 3 intentos fallidos el código queda inutilizado aunque no haya vencido, y hay que pedir uno nuevo.

curl -X POST "https://api.waiify.com/api/workspaces/$WORKSPACE_ID/messaging/otp/verify" \
  -H "Authorization: Bearer $WAIIFY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "to": "573001234567",
    "code": "482915"
  }'

{
  "success": true,
  "data": {
    "valid": true,
    "reason": null,
    "attemptsLeft": 3
  }
}

{
  "success": true,
  "data": {
    "valid": false,
    "reason": "mismatch",
    "attemptsLeft": 2
  }
}

Errores

Además de los errores generales:

Código	Cuándo
`400`	Número inválido, mensaje vacío, plantilla sin `{{code}}` o un campo desconocido en el cuerpo.
`402`	El workspace no tiene créditos suficientes para el envío.
`429`	Se superó uno de los topes de códigos, o el límite de peticiones por minuto.
`502`	El proveedor de SMS rechazó el envío por una causa nuestra. Reintentable.

El límite de peticiones se aplica por workspace, no por IP: 120 envíos por minuto y 600 verificaciones por minuto.