Autenticación
Credenciales o tokens gestionados de forma segura, con rotación, scopes y separación entre entornos cuando el proveedor lo soporte.
Guía técnica · API RCS
API RCS: arquitectura de integración para RCS for Business
Una integración RCS empresarial combina identidad del agente, envío de mensajes, contenido enriquecido, eventos y reglas de canal. Esta página describe una arquitectura de referencia; los ejemplos son conceptuales y no representan una API pública concreta de 402T Labs.
Modelo técnico
Componentes que conviene separar
La integración suele distinguir gestión de credenciales/agente, API de mensajería, recepción de eventos y capa de orquestación multicanal.
Agente RCS
Identidad empresarial que representa a la marca y condiciona configuración, pruebas y lanzamiento.
Mensajería
Operaciones para enviar texto, medios, rich cards, carruseles y sugerencias.
Eventos
Respuestas del usuario, estados de entrega/lectura y otros eventos disponibles.
Capability checks
Comprobación previa de disponibilidad RCS para decidir canal.
Fallback
Reglas de continuidad hacia SMS u otro canal cuando RCS no sea viable.
Envío
Construye mensajes ricos sin acoplar tu negocio al formato
Es útil separar el evento de negocio —por ejemplo “pedido listo”— del formato final del canal. La capa de mensajería transforma ese evento en texto SMS, rich card RCS u otra representación.
✓Texto. Mensajes simples y compatibles.
✓Rich cards. Título, descripción, medios y acciones.
✓Carruseles. Varias tarjetas dentro de una experiencia navegable.
✓Suggested replies/actions. Respuestas guiadas y acciones admitidas por la plataforma.
ejemplo conceptualno es un endpoint de 402T
POST /messages // ejemplo conceptual
{
"recipient": "+34...",
"agent": "marca-ejemplo",
"content": {
"type": "rich_card",
"title": "Pedido preparado",
"actions": ["Ver pedido", "Soporte"]
},
"client_reference": "order-8472"
}Eventos y webhooks
Trata la recepción de eventos como parte crítica de la integración
Los webhooks o mecanismos equivalentes deben procesarse de forma autenticada, idempotente y observable. Un mismo evento puede reintentarse y no debería provocar acciones duplicadas.
✓Validación. Verifica autenticidad y origen conforme al proveedor.
✓Idempotencia. Deduplica eventos y operaciones de negocio.
✓Correlación. Conserva identificadores de mensaje y referencia de cliente.
✓Reintentos. Diseña colas y manejo de fallos transitorios.
webhook conceptualejemplo
{
"event_id": "evt_...",
"message_id": "msg_...",
"type": "user_response",
"payload": {
"suggestion": "Ver pedido"
}
}
// Persistir event_id antes de ejecutar
// efectos de negocio evita duplicados.Estados y observabilidad
Lo importante no termina cuando aceptan el mensaje
Una plataforma empresarial necesita diferenciar aceptación de API, estado del canal, entrega, lectura cuando exista, interacción y error final.
Logs estructurados
Identificadores, agente, destinatario anonimizado, canal seleccionado y resultado.
Métricas
Volumen, latencia, errores, fallback y ratio de usuarios alcanzables por RCS.
Trazas
Correlación desde el evento de negocio hasta la entrega o fallback.
Errores
Clasificación entre errores permanentes, transitorios, validación, capacidad y política.
Alertas
Umbrales de error, latencia o caída de capacidad que requieran acción.
Auditoría
Registro suficiente para explicar qué canal se eligió y por qué.
Capability check + fallback
La selección de canal debe ser una decisión explícita
Antes de enviar una experiencia RCS, la aplicación puede comprobar si el destinatario es alcanzable por ese canal. Si no lo es —o si la política de negocio lo determina— se puede seleccionar SMS como alternativa.
EventoPedido, OTP, alerta
→
Capability + reglasRCS disponible?
→
RCS / SMSCanal resultante
Arquitectura multicanal
Evita que cada canal replique la lógica de negocio
Una capa de abstracción puede recibir una intención de comunicación, consultar preferencias/capacidades, seleccionar canal, renderizar contenido y registrar resultado. Así RCS y SMS comparten contexto sin forzar que sean técnicamente idénticos.
Plantillas por canal
Contenido adaptado a las posibilidades de cada tecnología.
Políticas
Reglas por caso de uso, urgencia, consentimiento y capacidad.
Fallback controlado
Evita duplicidades: un fallback debe conocer el estado del intento anterior.
Preferencias
Respeta las reglas de consentimiento y opt-out aplicables al caso.
Errores desacoplados
Mapea errores específicos del proveedor a estados internos consistentes.
Observabilidad común
Métricas comparables entre canales para operación y negocio.