🌐 English: Step-by-step guide — authentication, first RCS message, SMS fallback, delivery webhooks, and a full Node.js example.

Requisitos previos

Antes de empezar necesitas:

  • Una cuenta en SMS.es con RCS habilitado (créala en sms.es)
  • Tu clave API (en el panel de control, bajo Configuración → API)
  • Un ID de remitente RCS verificado (nombre de marca y logo, aprobado por SMS.es)
  • Un número de teléfono de prueba con un dispositivo Android que tenga Google Mensajes
Consejo: La API RCS usa llamadas REST estándar por HTTPS con cuerpos JSON. Si has trabajado con APIs como Twilio o Vonage, la estructura te resultará inmediatamente familiar.

Paso 1 — Autenticación

Todas las peticiones a la API se autentican con un Bearer token en el encabezado Authorization. Tu clave API es el token — nunca la expongas en código del lado cliente.

# Todas las peticiones usan este encabezado Authorization: Bearer TU_CLAVE_API Content-Type: application/json

Paso 2 — Envía tu primer mensaje RCS

Un mensaje de texto RCS básico con sugerencias de respuesta rápida se ve así:

curl -X POST https://api.sms.es/v1/rcs/messages \ -H "Authorization: Bearer TU_CLAVE_API" \ -H "Content-Type: application/json" \ -d '{ "to": "+34600000000", "from": "TuMarca", "rcs": { "text": "Tu pedido #4821 ha sido enviado. Entrega estimada: mañana.", "suggestions": [ { "type": "reply", "label": "Rastrear paquete" }, { "type": "url", "label": "Ver pedido", "url": "https://ejemplo.com/pedidos/4821" } ] } }'

Una respuesta exitosa devuelve el ID del mensaje y el estado inicial:

{ "messageId": "rcs_01JK2X...", "status": "queued", "channel": "rcs", "to": "+34600000000" }
Interfaz RCS con tarjeta enriquecida y botones de acción

Paso 3 — Envía una tarjeta enriquecida (Rich Card)

Las rich cards son el formato RCS más impactante visualmente — imagen, título, descripción y botones de acción en un único mensaje:

{ "to": "+34600000000", "from": "TuMarca", "rcs": { "card": { "title": "Colección Verano — Hasta 40% de Descuento", "description": "Tiempo limitado. Compra antes de que se agote.", "media_url": "https://ejemplo.com/images/verano-banner.jpg", "media_height": "TALL", "buttons": [ { "type": "url", "label": "Comprar Ahora", "url": "https://ejemplo.com/verano" }, { "type": "reply", "label": "Recordarme más tarde" } ] } } }

Paso 4 — Configura el fallback a SMS

No todos los dispositivos son compatibles con RCS. Añadir un objeto fallback indica a la API qué enviar si la entrega RCS no es posible. Se recomienda encarecidamente en todos los mensajes de producción.

{ "to": "+34600000000", "from": "TuMarca", "rcs": { "text": "Tu código es 847291. Válido 10 minutos." }, "fallback": { "sms": { "text": "[TuMarca] Tu código es 847291. Válido 10 minutos." } } }

La API intenta RCS primero. Si falla o el dispositivo no es compatible, hace fallback a SMS automáticamente — todo de forma transparente, sin código extra por tu parte.

Paso 5 — Configura webhooks para eventos de entrega

Para recibir acuses de entrega, confirmaciones de lectura y respuestas del usuario, configura un endpoint webhook en tu panel de control de SMS.es o por API:

# Ejemplo de payload webhook — mensaje leído { "event": "message.read", "messageId": "rcs_01JK2X...", "to": "+34600000000", "channel": "rcs" } # El usuario tocó un botón de sugerencia { "event": "suggestion.tapped", "suggestion": "Rastrear paquete", "from": "+34600000000" }

Ejemplo completo en Node.js

const sendRCS = async (telefono, pedido) => { const respuesta = await fetch('https://api.sms.es/v1/rcs/messages', { method: 'POST', headers: { 'Authorization': `Bearer ${process.env.RCS_API_KEY}`, 'Content-Type': 'application/json' }, body: JSON.stringify({ to: telefono, from: 'MiMarca', rcs: { card: { title: `Pedido #${pedido.id} Enviado`, description: `Entrega estimada: ${pedido.fechaEntrega}`, media_url: pedido.imagenProducto, buttons: [ { type: 'url', label: 'Rastrear pedido', url: pedido.urlSeguimiento }, { type: 'reply', label: 'Contactar soporte' } ] } }, fallback: { sms: { text: `Pedido #${pedido.id} enviado. Rastrea en: ${pedido.urlSeguimiento}` } } }) }); const { messageId, status } = await respuesta.json(); console.log(`Enviado ${messageId} — estado: ${status}`); };
Límites de tasa: La API permite hasta 100 peticiones/segundo en los planes Business y Enterprise. Para envíos masivos, usa el endpoint batch (/v1/rcs/messages/batch) que acepta hasta 1.000 mensajes por petición.

¡Listo!

Con estos cinco pasos tienes una integración RCS lista para producción: peticiones autenticadas, mensajes con rich card, fallback a SMS y webhooks de entrega. Desde aquí puedes explorar carruseles, compartir ubicación, adjuntos y flujos de conversación bidireccional en la documentación completa de la API.

Requisitos previos

Antes de empezar necesitas:

  • Una cuenta en SMS.es con RCS habilitado (créala en sms.es)
  • Tu clave API (en el panel de control, bajo Configuración → API)
  • Un ID de remitente RCS verificado (nombre de marca y logo, aprobado por SMS.es)
  • Un número de teléfono de prueba con un dispositivo Android que tenga Google Mensajes
Consejo: La API RCS usa llamadas REST estándar por HTTPS con cuerpos JSON. Si has trabajado con APIs como Twilio o Vonage, la estructura te resultará inmediatamente familiar.

Paso 1 — Autenticación

Todas las peticiones a la API se autentican con un Bearer token en el encabezado Authorization. Tu clave API es el token — nunca la expongas en código del lado cliente.

# Todas las peticiones usan este encabezado Authorization: Bearer TU_CLAVE_API Content-Type: application/json

Paso 2 — Envía tu primer mensaje RCS

Un mensaje de texto RCS básico con sugerencias de respuesta rápida se ve así:

curl -X POST https://api.sms.es/v1/rcs/messages \ -H "Authorization: Bearer TU_CLAVE_API" \ -H "Content-Type: application/json" \ -d '{ "to": "+34600000000", "from": "TuMarca", "rcs": { "text": "Tu pedido #4821 ha sido enviado. Entrega estimada: mañana.", "suggestions": [ { "type": "reply", "label": "Rastrear paquete" }, { "type": "url", "label": "Ver pedido", "url": "https://ejemplo.com/pedidos/4821" } ] } }'

Una respuesta exitosa devuelve el ID del mensaje y el estado inicial:

{ "messageId": "rcs_01JK2X...", "status": "queued", "channel": "rcs", "to": "+34600000000" }
Interfaz RCS con tarjeta enriquecida y botones de acción

Paso 3 — Envía una tarjeta enriquecida (Rich Card)

Las rich cards son el formato RCS más impactante visualmente — imagen, título, descripción y botones de acción en un único mensaje:

{ "to": "+34600000000", "from": "TuMarca", "rcs": { "card": { "title": "Colección Verano — Hasta 40% de Descuento", "description": "Tiempo limitado. Compra antes de que se agote.", "media_url": "https://ejemplo.com/images/verano-banner.jpg", "media_height": "TALL", "buttons": [ { "type": "url", "label": "Comprar Ahora", "url": "https://ejemplo.com/verano" }, { "type": "reply", "label": "Recordarme más tarde" } ] } } }

Paso 4 — Configura el fallback a SMS

No todos los dispositivos son compatibles con RCS. Añadir un objeto fallback indica a la API qué enviar si la entrega RCS no es posible. Se recomienda encarecidamente en todos los mensajes de producción.

{ "to": "+34600000000", "from": "TuMarca", "rcs": { "text": "Tu código es 847291. Válido 10 minutos." }, "fallback": { "sms": { "text": "[TuMarca] Tu código es 847291. Válido 10 minutos." } } }

La API intenta RCS primero. Si falla o el dispositivo no es compatible, hace fallback a SMS automáticamente — todo de forma transparente, sin código extra por tu parte.

Paso 5 — Configura webhooks para eventos de entrega

Para recibir acuses de entrega, confirmaciones de lectura y respuestas del usuario, configura un endpoint webhook en tu panel de control de SMS.es o por API:

# Ejemplo de payload webhook — mensaje leído { "event": "message.read", "messageId": "rcs_01JK2X...", "to": "+34600000000", "channel": "rcs" } # El usuario tocó un botón de sugerencia { "event": "suggestion.tapped", "suggestion": "Rastrear paquete", "from": "+34600000000" }

Ejemplo completo en Node.js

const sendRCS = async (telefono, pedido) => { const respuesta = await fetch('https://api.sms.es/v1/rcs/messages', { method: 'POST', headers: { 'Authorization': `Bearer ${process.env.RCS_API_KEY}`, 'Content-Type': 'application/json' }, body: JSON.stringify({ to: telefono, from: 'MiMarca', rcs: { card: { title: `Pedido #${pedido.id} Enviado`, description: `Entrega estimada: ${pedido.fechaEntrega}`, media_url: pedido.imagenProducto, buttons: [ { type: 'url', label: 'Rastrear pedido', url: pedido.urlSeguimiento }, { type: 'reply', label: 'Contactar soporte' } ] } }, fallback: { sms: { text: `Pedido #${pedido.id} enviado. Rastrea en: ${pedido.urlSeguimiento}` } } }) }); const { messageId, status } = await respuesta.json(); console.log(`Enviado ${messageId} — estado: ${status}`); };
Límites de tasa: La API permite hasta 100 peticiones/segundo en los planes Business y Enterprise. Para envíos masivos, usa el endpoint batch (/v1/rcs/messages/batch) que acepta hasta 1.000 mensajes por petición.

¡Listo!

Con estos cinco pasos tienes una integración RCS lista para producción: peticiones autenticadas, mensajes con rich card, fallback a SMS y webhooks de entrega. Desde aquí puedes explorar carruseles, compartir ubicación, adjuntos y flujos de conversación bidireccional en la documentación completa de la API.