Inicio rápido - Notifique

De cero a tu primer SMS en la cola en unos pocos pasos. Empieza con sk_test_... en Sandbox.

En breve

Enviar texto corto (de 9 a 160 caracteres) a uno o varios números.
Consultar historial o un envío por id.
Cancelar mientras el estado sea QUEUED o SCHEDULED.

Contexto: Introducción. Alcances: Alcances de clave API.

Antes de empezar

Item	Obligatorio
Clave con `sms:send`	Sí
Números en formato internacional (sin `+`)	Sí
`sms:read` / `sms:cancel`	Solo si consultas o cancelas

URL base: https://api.notifique.dev. Reemplaza sk_live_xxxxx por tu clave (sk_test_... en sandbox).

1. Enviar SMS

to es siempre un array (hasta 500 destinatarios).

POST /v1/sms/messages
Content-Type: application/json
Authorization: Bearer sk_live_xxxxx

{
  "to": ["5511999999999", "5521988887777"],
  "type": "text",
  "payload": {
    "message": "Tu código es 482910. Válido por 10 minutos."
  }
}

Respuesta (202)

{
  "success": true,
  "data": {
    "status": "QUEUED",
    "count": 2,
    "messageIds": ["clxx123...", "clxx456..."],
  }
}

La respuesta incluye messageIds.

Menos de 9 caracteres en payload.message → 400 (SMS_MESSAGE_TOO_SHORT).

Enviar con plantilla

Si ya tienes una plantilla del workspace con SMS habilitado, usa type: "template", el mismo patrón que WhatsApp, Telegram y los demás canales:

{
  "to": ["5511999999999"],
  "type": "template",
  "payload": {
    "templateId": "ID_DE_LA_PLANTILLA",
    "variables": { "code": "482910", "name": "María" }
  }
}

La API resuelve el texto de la plantilla, sustituye variables y encola el SMS.

2. Listar historial

GET /v1/sms/messages?page=1&limit=20
Authorization: Bearer sk_live_xxxxx

{
  "success": true,
  "data": [
    {
      "smsId": "clxx123...",
      "to": "5511999999999",
      "message": "Tu código es 482910...",
      "status": "DELIVERED",
      "sentAt": "2025-02-20T14:00:00.000Z",
      "deliveredAt": "2025-02-20T14:00:30.000Z"
    }
  ],
  "pagination": { "total": 42, "page": 1, "limit": 20, "totalPages": 3 }
}

3. Consultar un envío

GET /v1/sms/messages/:id
Authorization: Bearer sk_live_xxxxx

Misma forma que un elemento de la lista. Requiere sms:read.

4. Programar y cancelar

Programar, incluye en el POST de envío:

{
  "to": ["5511999999999"],
  "type": "text",
  "payload": {
    "message": "Recordatorio mañana a las 9h."
  },
  "schedule": { "sendAt": "2025-03-01T09:00:00.000Z" }
}

Cancelar (QUEUED o SCHEDULED):

POST /v1/sms/messages/:id/cancel
Authorization: Bearer sk_live_xxxxx

Los créditos programados regresan al workspace. Alcance: sms:cancel.

5. Elegir el tipo de envío

options.speed define la ruta en el operador y cambia el precio. En el panel: SMS → Nuevo SMS → Tipo de envío (SMS Full, SMS Standard, SMS Slow).

Valor	En el panel	Para qué sirve	Créditos	Pago por uso
`full`	SMS Full	OTP, alerta urgente	120	R$ 0,15
`standard`	SMS Standard	Predeterminado (omitir el campo)	100	R$ 0,12
`slow`	SMS Slow	Campaña sin prisa	70	R$ 0,09

{
  "to": ["5511999999999"],
  "type": "text",
  "payload": { "message": "Solo hoy: 20% en toda la tienda." },
  "options": { "speed": "slow" }
}

OTP o código de verificación — usa full:

{
  "to": ["5511999999999"],
  "type": "text",
  "payload": { "message": "Tu código es 482910. Válido por 10 minutos." },
  "options": { "speed": "full" }
}

Número propio: con from (línea contratada y activa), el cliente ve tu número. El precio varía por país (smsOwnNumber en GET /v1/pricing) — options.speed no aplica.

speed no es priority. options.speed elige la ruta y cambia el valor cobrado. options.priority (high, normal, low) solo define el orden en la cola interna de Notifique y no altera el precio ni la ruta en el operador.

Un valor fuera de la lista devuelve 400 (options.speed must be full, standard, slow).

6. Evitar duplicados

Header Idempotency-Key en el POST. Los reintentos dentro de 24 h no crean envíos duplicados. Ver Seguridad y confiabilidad.

7. Webhooks (opcional)

Configura sms.sent, sms.delivered, sms.failed y MO (sms.received, sms.replied) para seguimiento sin polling. Guía: Eventos de webhook.

8. Localización y variables

localization (off | manual | ai) + i18n traducen payload.message por destinatario.
variables en la raíz sustituyen {{placeholders}} en texto libre.
La respuesta 202 puede incluir data.localization, data.sandbox y data.smsSkippedRecipients.

Detalles: Introducción.

Todos los tipos de envío

En la referencia de la API (pestaña SMS), abre Enviar SMS (POST /v1/sms/messages) y usa los ejemplos del playground:

Ejemplo	Qué demuestra
Texto	Envío con `options.priority` y webhook por envío
Plantilla	`type: template` con variables
Full (OTP / urgente)	`options.speed: full`
Slow (campaña)	`options.speed: slow`
Número propio	Campo `from` (ruta y precio distintos)

Sin speed en el cuerpo, el cobro usa standard.

Próximos pasos

Introducción: cuándo usar y ciclo de estados
Alcances: permisos de la clave
Eventos de webhook: estado en tiempo real
Respuestas de error: códigos HTTP y code

​En breve

​Antes de empezar

​1. Enviar SMS

​Enviar con plantilla

​2. Listar historial

​3. Consultar un envío

​4. Programar y cancelar

​5. Elegir el tipo de envío

​6. Evitar duplicados

​7. Webhooks (opcional)

​8. Localización y variables

​Todos los tipos de envío

​Próximos pasos

En breve

Antes de empezar

1. Enviar SMS

Enviar con plantilla

2. Listar historial

3. Consultar un envío

4. Programar y cancelar

5. Elegir el tipo de envío

6. Evitar duplicados

7. Webhooks (opcional)

8. Localización y variables

Todos los tipos de envío

Próximos pasos