Envío de SMS a teléfonos chilenos
Qué resuelve
Sección titulada «Qué resuelve»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.
Qué necesitas antes
Sección titulada «Qué necesitas antes»-
Una llave de prueba conectada al proyecto. Si
keys/redcumbre-prueba.jsonno existe, parte por el arranque o correredcumbre 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ón Máxima premiumMensajes prioritarios de negocio Alta transactionalAvisos de una transacción o evento Media marketingCampañas promocionales; el destinatario debe haber aceptado recibirlas Baja wholesaleEnvíos masivos de alto volumen Mínima
-
Arma el cuerpo. Guárdalo como
sms-prueba.json. El número puede ir como+56912345678,56912345678o912345678; la plataforma lo normaliza a+56XXXXXXXXX.{"to": "+56912345678","body": "Hola, tu pedido #1234 fue despachado.","routeType": "transactional","metadata": { "pedido": "1234" },"idempotencyKey": "pedido-1234-despacho"}bodyadmite hasta 1.600 caracteres.metadataes 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. -
Envía el SMS de prueba. Comando:
Ventana de terminal redcumbre api enviarSms --cuerpo @sms-prueba.json --jsonResultado 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. -
Comprueba el estado de entrega. Comando, repetido con espera:
Ventana de terminal redcumbre api obtenerMensajeSms --param id=<messageId> --jsonResultado esperado: el estado cambia solo, de
queuedasenta los 15 segundos y adelivereda los 30. Los estados terminales sondelivered,undelivered,failed,expiredyrejected;submittedysentno lo son. El detalle trae además los segmentos, la ruta y los intentos de entrega. -
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 RUT44444444-4;redcumbre escenarios --jsonlo lista con el resto del catálogo), con otraidempotencyKey. Resultado esperado: el mensaje pasa porsenty termina enundelivered. -
Mira lo que habría salido. Comando:
Ventana de terminal redcumbre bandeja --canal sms --jsonResultado 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.
-
Lista y concilia. Comandos:
Ventana de terminal redcumbre api listarMensajesSms --param status=delivered --param limit=20 --jsonredcumbre api consultarEstadisticasSms --param dateFrom=2026-01-01 --param dateTo=2026-01-31 --jsonResultado esperado: el primero lista sólo los SMS de prueba, paginados (filtros
status,routeType,toNumber,dateFrom,dateTo,search,limithasta 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.
Cómo saber que funcionó
Sección titulada «Cómo saber que funcionó»- El envío respondió
201constatus: "queued"y unmessageId. Esto no es una entrega:queuedsólo dice que quedó en cola. obtenerMensajeSmsllegó adelivered(en prueba, tras unos 30 segundos), y aundeliveredpara 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
obtenerMensajeSmsolistarMensajesSms. En producción, no des por entregado un SMS que sigue ensentosubmitted: espera su estado terminal (un mensaje sin confirmación de entrega a la hora quedaexpired).
Qué puede fallar
Sección titulada «Qué puede fallar»| Si ves | Significa | Qué haces |
|---|---|---|
400 con un mensaje sobre to | El 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álido | Falta el texto o la ruta no es una de las cinco | Corrige el cuerpo |
400 con MODO_PRUEBA_TOPE_DIARIO | Superaste los 200 SMS de prueba del día | Espera 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 plataforma | Cambia el texto o la ruta; el mensaje dice el motivo. No reintentes igual |
429 con OTP_RATE_LIMITED | Ya 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_PLAN | El plan de la empresa no incluye SMS | Es del plan: lo cambia quien administra la empresa. No reintentes |
403 «servicio SMS no habilitado» (producción) | La empresa no tiene el servicio contratado | Quien administra la empresa lo activa. No es un fallo de la llave |
401 | La llave es inválida, expiró o fue revocada | redcumbre doctor revisa la sesión y las llaves |
503 con API_KEY_VERIFICATION_UNAVAILABLE | No se pudo verificar la llave, que no fue rechazada | Reintenta tras Retry-After. No la rotes |
Estado undelivered | No se pudo entregar (número inválido, apagado, sin cobertura) | No reenvíes sin razón: confirma el número |
Estado failed | Falló el envío por parte del proveedor | Reintenta una vez con una idempotencyKey nueva; la misma devolvería el mismo mensaje fallido |
Estado rejected | Rechazado por la política de contenido | Cambia el texto |
Estado expired | Sin confirmación de entrega después de 1 hora | Trátalo como no confirmado |
Antes de pasar a producción
Sección titulada «Antes de pasar a producción»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.
-
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 smsrevisa 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 enkeys/redcumbre-produccion.json. -
Texto y ruta. Revisa cuántos segmentos tiene cada plantilla antes de lanzarla (
segmentCounten la respuesta). Una campañamarketingnecesita que cada destinatario haya aceptado recibirla; ese consentimiento lo guardas tú. -
Códigos de verificación. Un
otppor número cada 5 minutos es el límite: diseña el reenvío de códigos con esa espera, no con reintentos. -
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 --jsonResultado esperado:
201constatus: "queued",sandbox: falsey un bloquecobroconmodo: "produccion"que informa los segmentos previstos y lo que queda del plan. Después,obtenerMensajeSmsdebe llegar adelivered.redcumbre consumo --produccionmuestra lo consumido. -
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.