Ir al contenido

Envío de SMS a teléfonos chilenos

Mandar un mensaje de texto a un celular chileno desde tu sistema (un código de verificación, un aviso de despacho, un recordatorio) y saber si llegó. El envío es asíncrono: la respuesta confirma que el mensaje quedó en cola y su estado de entrega se consulta después.

Esta ficha no cubre WhatsApp ni los correos: son productos aparte.

  • Una llave de prueba conectada al proyecto. Si keys/redcumbre-prueba.json no existe, parte por el arranque o corre redcumbre init. No hace falta ningún emisor.

  • Rol FULL-API, que es el de la llave del proyecto.

  • En el modo de prueba no se exige tener el servicio de SMS contratado; en producción sí (ver el final). Qué cambia entre los modos: Modo de prueba y producción. Forma de los errores y límites: Reglas comunes.

  • El tipo de ruta (routeType) de cada mensaje, que fija su prioridad:

    routeTypePara quéPrioridad
    otpCódigos de verificaciónMáxima
    premiumMensajes prioritarios de negocioAlta
    transactionalAvisos de una transacción o eventoMedia
    marketingCampañas promocionales; el destinatario debe haber aceptado recibirlasBaja
    wholesaleEnvíos masivos de alto volumenMínima
  1. Arma el cuerpo. Guárdalo como sms-prueba.json. El número puede ir como +56912345678, 56912345678 o 912345678; la plataforma lo normaliza a +56XXXXXXXXX.

    {
    "to": "+56912345678",
    "body": "Hola, tu pedido #1234 fue despachado.",
    "routeType": "transactional",
    "metadata": { "pedido": "1234" },
    "idempotencyKey": "pedido-1234-despacho"
    }

    body admite hasta 1.600 caracteres. metadata es un objeto libre para que correlaciones el mensaje con tu sistema. idempotencyKey (hasta 128 caracteres) hace que repetir el envío, en la misma empresa y el mismo modo, devuelva el mismo mensaje sin volver a encolarlo ni enviarlo; sin clave, cada llamada manda un SMS.

  2. Envía el SMS de prueba. Comando:

    Ventana de terminal
    redcumbre api enviarSms --cuerpo @sms-prueba.json --json

    Resultado esperado: código de salida 0 y respuesta 201, sin esperar la entrega:

    {
    "messageId": "cmovnx2op0001sezxd0srby0g",
    "status": "queued",
    "segmentCount": 1,
    "encoding": "gsm7",
    "sandbox": true,
    "cobro": { "modo": "prueba", "mensaje": "En modo de prueba no se cobra." }
    }

    En el modo de prueba el mensaje no sale a ningún proveedor ni a ningún teléfono: queda registrado con su contenido, marcado como de prueba, y cuenta uno en el tope diario de SMS de prueba (200). Guarda el messageId.

  3. Comprueba el estado de entrega. Comando, repetido con espera:

    Ventana de terminal
    redcumbre api obtenerMensajeSms --param id=<messageId> --json

    Resultado esperado: el estado cambia solo, de queued a sent a los 15 segundos y a delivered a los 30. Los estados terminales son delivered, undelivered, failed, expired y rejected; submitted y sent no lo son. El detalle trae además los segmentos, la ruta y los intentos de entrega.

  4. Provoca una entrega fallida. Para programar contra el caso malo, envía el mismo cuerpo al teléfono de entrega fallida del catálogo de prueba, +56222222244 (el del RUT 44444444-4; redcumbre escenarios --json lo lista con el resto del catálogo), con otra idempotencyKey. Resultado esperado: el mensaje pasa por sent y termina en undelivered.

  5. Mira lo que habría salido. Comando:

    Ventana de terminal
    redcumbre bandeja --canal sms --json

    Resultado esperado: una lista con el mensaje, su destinatario y su contenido. Es la prueba de que el SMS se redactó como esperabas sin haberlo enviado.

  6. Lista y concilia. Comandos:

    Ventana de terminal
    redcumbre api listarMensajesSms --param status=delivered --param limit=20 --json
    redcumbre api consultarEstadisticasSms --param dateFrom=2026-01-01 --param dateTo=2026-01-31 --json

    Resultado esperado: el primero lista sólo los SMS de prueba, paginados (filtros status, routeType, toNumber, dateFrom, dateTo, search, limit hasta 300, offset); el segundo, los totales por estado y por ruta en el rango, útiles para conciliar lo enviado contra lo cobrado. La paginación se explica en Reglas comunes.

  • El envío respondió 201 con status: "queued" y un messageId. Esto no es una entrega: queued sólo dice que quedó en cola.
  • obtenerMensajeSms llegó a delivered (en prueba, tras unos 30 segundos), y a undelivered para el teléfono de entrega fallida.
  • El mensaje aparece en redcumbre bandeja --canal sms.
  • No hay evento de webhook para SMS: el estado se consulta con obtenerMensajeSms o listarMensajesSms. En producción, no des por entregado un SMS que sigue en sent o submitted: espera su estado terminal (un mensaje sin confirmación de entrega a la hora queda expired).
Si vesSignificaQué haces
400 con un mensaje sobre toEl teléfono no es chileno o está mal formado (+56XXXXXXXXX, 56XXXXXXXXX o 9XXXXXXXX)Corrige el número; no se encoló nada
400 por body vacío o routeType inválidoFalta el texto o la ruta no es una de las cincoCorrige el cuerpo
400 con MODO_PRUEBA_TOPE_DIARIOSuperaste los 200 SMS de prueba del díaEspera hasta las 00:00 de Chile. redcumbre estado dice cuánto queda
Rechazo por política de contenido (Content policy rejected: …)El texto o la ruta no cumplen la política de contenido de la plataformaCambia el texto o la ruta; el mensaje dice el motivo. No reintentes igual
429 con OTP_RATE_LIMITEDYa enviaste un otp a ese número hace menos de 5 minutos (1 por número cada 5 minutos)Espera. No lo reintentes en bucle: pide a la persona que use el código que ya recibió
402 con METRIC_NOT_IN_PLANEl plan de la empresa no incluye SMSEs del plan: lo cambia quien administra la empresa. No reintentes
403 «servicio SMS no habilitado» (producción)La empresa no tiene el servicio contratadoQuien administra la empresa lo activa. No es un fallo de la llave
401La llave es inválida, expiró o fue revocadaredcumbre doctor revisa la sesión y las llaves
503 con API_KEY_VERIFICATION_UNAVAILABLENo se pudo verificar la llave, que no fue rechazadaReintenta tras Retry-After. No la rotes
Estado undeliveredNo se pudo entregar (número inválido, apagado, sin cobertura)No reenvíes sin razón: confirma el número
Estado failedFalló el envío por parte del proveedorReintenta una vez con una idempotencyKey nueva; la misma devolvería el mismo mensaje fallido
Estado rejectedRechazado por la política de contenidoCambia el texto
Estado expiredSin confirmación de entrega después de 1 horaTrátalo como no confirmado

En producción el SMS sale al teléfono de una persona y se mide por segmento y lo que cuesta depende de tu plan (redcumbre tarifas enviarSms --produccion). Un mensaje de hasta 160 caracteres con el alfabeto básico de SMS (encoding: "gsm7") es 1 segmento; si se parte, cada segmento lleva 153. Si el texto incluye un solo carácter fuera de ese alfabeto, como un emoji o ciertas vocales con tilde, todo el mensaje pasa a ucs2: 70 caracteres por segmento (67 si se parte), y un mensaje largo puede duplicar su costo. Mira encoding y segmentCount en la respuesta del envío de prueba antes de fijar el texto. El cobro se registra cuando el mensaje se despacha, no al encolarlo.

  1. Servicio contratado. El servicio de SMS tiene que estar activo en la empresa y el plan tiene que incluir los segmentos de SMS. redcumbre pasar-a-produccion --servicios sms revisa que todo esté en orden, dice qué falta y dónde configurarlo, y recién entonces crea la llave de producción, que confirma una persona escribiendo el identificador de la empresa. Esa llave nunca se muestra ni se pega en el chat o el repositorio: queda en keys/redcumbre-produccion.json.

  2. Texto y ruta. Revisa cuántos segmentos tiene cada plantilla antes de lanzarla (segmentCount en la respuesta). Una campaña marketing necesita que cada destinatario haya aceptado recibirla; ese consentimiento lo guardas tú.

  3. Códigos de verificación. Un otp por número cada 5 minutos es el límite: diseña el reenvío de códigos con esa espera, no con reintentos.

  4. Primer envío de producción. Comando, con la confirmación explícita de producción:

    Ventana de terminal
    redcumbre api enviarSms --produccion --confirmar <identificador-de-la-empresa> --cuerpo @sms.json --json

    Resultado esperado: 201 con status: "queued", sandbox: false y un bloque cobro con modo: "produccion" que informa los segmentos previstos y lo que queda del plan. Después, obtenerMensajeSms debe llegar a delivered. redcumbre consumo --produccion muestra lo consumido.

  5. Números de prueba. Los números del catálogo de prueba (como +56222222244) no sirven para ensayar en producción: allá cada número es el teléfono de una persona.

Más sobre qué cambia entre modos: Modo de prueba y producción.