UC-002 — Invio RCS Rich Card

Campo	Valore
ID	UC-002
Obiettivo	Inviare una rich card RCS con media, testo e azioni interattive
Canale	RCS
Complessità	Base
Tempo stimato	15 minuti
API coinvolte	POST /api/message-server/rcs/send, GET /api/partner-gateway/v1/messages/status/{customerMessageId}

Scenari reali

• Retail — Promozione prodotto: ElettroShop invia una rich card con foto del prodotto, prezzo scontato e bottone "Acquista ora" che porta direttamente alla pagina dell'offerta.
• Ristorante — Menu visuale: Trattoria Da Mario invia la specialita del giorno con foto del piatto, descrizione e bottone per prenotare un tavolo.
• Real estate — Annuncio immobile: Immobiliare Rossi invia una card con foto dell'appartamento, dettagli e bottoni per chiamare l'agente o aprire la mappa.

Flusso del messaggio

A differenza di un SMS, la rich card RCS consente di inviare contenuti multimediali con bottoni interattivi direttamente nella conversazione nativa del telefono, senza bisogno di app esterne.

Step 1 — Prepara la media URL

L'immagine della rich card deve essere accessibile tramite URL pubblico HTTPS. Formati supportati: JPEG, PNG. Dimensione consigliata: almeno 1440px di larghezza per una resa ottimale.

:::tip Requisiti media L'URL deve essere raggiungibile pubblicamente (no localhost, no VPN). Usa un CDN o un object storage (S3, GCS) per garantire disponibilita e performance. :::

Step 2 — Invia la Rich Card

Invoca l'endpoint RCS con type: "CARD" e il contenuto della card nel campo body.

curl -X POST https://lora-api.agiletelecom.com/api/message-server/rcs/send \
  -H "Content-Type: application/json" \
  -H "X-Api-Key: YOUR_API_KEY" \
  -d '{
    "destination": "+393401234567",
    "agentId": 10,
    "body": {
      "type": "CARD",
      "body": {
        "title": "Samsung Galaxy S26 Ultra",
        "description": "Offerta esclusiva ElettroShop! Solo per oggi: Galaxy S26 Ultra a 899 EUR invece di 1.199 EUR. Spedizione gratuita e reso entro 30 giorni.",
        "mediaUrl": "https://cdn.elettroshop.it/products/galaxy-s26-ultra.jpg",
        "suggestions": [
          {
            "type": "URL",
            "text": "Acquista ora",
            "value": "https://elettroshop.it/galaxy-s26-ultra?promo=RCS2026"
          },
          {
            "type": "REPLY",
            "text": "Maggiori info",
            "value": "INFO_GALAXY_S26"
          },
          {
            "type": "DIAL",
            "text": "Chiama negozio",
            "value": "+390212345678"
          }
        ]
      }
    },
    "enableNotification": true
  }'

Response — Messaggio accettato

{
  "messageId": "e76614d1-4ac1-4d94-89f0-d07f1b5a190c",
  "simulation": false,
  "results": {
    "rcs": {
      "accepted": true,
      "reasons": []
    },
    "sms": null
  }
}

Dietro le quinte — Struttura della Rich Card

La rich card RCS e composta da:

• title (obbligatorio): Titolo principale della card, visibile in grassetto.
• description (opzionale): Testo descrittivo sotto il titolo.
• mediaUrl (opzionale): URL dell'immagine o video visualizzato in cima alla card.
• suggestions (opzionale): Lista di bottoni interattivi. Tipi supportati:
  • URL — Apre un link nel browser
  • REPLY — Invia una risposta predefinita (il value e il payload ricevuto via webhook INBOUND)
  • DIAL — Avvia una chiamata telefonica al numero specificato

Il gateway verifica la raggiungibilita della mediaUrl al momento dell'invio. Se l'immagine non e accessibile, il messaggio viene comunque inviato ma senza media.

Tipi di suggestions disponibili

Tipo	Comportamento	Esempio value
URL	Apre il browser	https://esempio.it/pagina
REPLY	Invia risposta al bot	INFO_PRODOTTO_42
DIAL	Avvia chiamata	+390212345678

Step 3 — Verifica consegna

curl -X GET "https://lora-api.agiletelecom.com/api/partner-gateway/v1/messages/status/e76614d1-4ac1-4d94-89f0-d07f1b5a190c?channel=RCS" \
  -H "X-Api-Key: YOUR_API_KEY"

Response — Consegnato

{
  "customerMessageId": "e76614d1-4ac1-4d94-89f0-d07f1b5a190c",
  "channel": "RCS",
  "destination": "+393401234567",
  "deliveryStatus": "DELIVERED",
  "deliveryStatusDescription": "Message delivered",
  "sendDate": "2026-04-09T11:30:00+02:00",
  "deliveryDate": "2026-04-09T11:30:02+02:00",
  "readDate": "2026-04-09T11:31:15+02:00"
}

:::info Read receipt A differenza dell'SMS, RCS supporta le conferme di lettura (readDate). Il webhook READ viene inviato quando l'utente visualizza il messaggio. :::

Dietro le quinte — Webhook di consegna e lettura RCS

Per RCS ricevi due tipi di callback:

DELIVERY — Il messaggio e stato recapitato:

{
  "channel": "RCS",
  "eventType": "DELIVERY",
  "messageId": "e76614d1-4ac1-4d94-89f0-d07f1b5a190c",
  "destination": "+393401234567",
  "statusCode": 3,
  "description": "delivered",
  "eventDate": "2026-04-09T11:30:02Z"
}

READ — L'utente ha visualizzato il messaggio:

{
  "channel": "RCS",
  "eventType": "READ",
  "messageId": "e76614d1-4ac1-4d94-89f0-d07f1b5a190c",
  "destination": "+393401234567",
  "eventDate": "2026-04-09T11:31:15Z"
}

INBOUND — L'utente ha premuto un bottone REPLY:

{
  "channel": "RCS",
  "eventType": "INBOUND",
  "messageId": "inbound-msg-001",
  "source": "+393401234567",
  "destination": "+393209998877",
  "receivedDate": "2026-04-09T11:32:00Z",
  "messageType": "TEXT",
  "text": "INFO_GALAXY_S26"
}

Configura il tuo endpoint nella guida Webhook.

Configurazione Fallback SMS

Se il destinatario non supporta RCS, puoi attivare il fallback automatico su SMS impostando maxSmsParts:

curl -X POST https://lora-api.agiletelecom.com/api/message-server/rcs/send \
  -H "Content-Type: application/json" \
  -H "X-Api-Key: YOUR_API_KEY" \
  -d '{
    "destination": "+393401234567",
    "agentId": 10,
    "body": {
      "type": "CARD",
      "body": {
        "title": "Offerta ElettroShop",
        "description": "Galaxy S26 Ultra a 899 EUR. Spedizione gratuita!",
        "mediaUrl": "https://cdn.elettroshop.it/products/galaxy-s26-ultra.jpg",
        "suggestions": [
          {
            "type": "URL",
            "text": "Acquista ora",
            "value": "https://elettroshop.it/galaxy-s26-ultra"
          }
        ]
      }
    },
    "maxSmsParts": 3,
    "enableNotification": true
  }'

Response — Fallback SMS attivato

{
  "messageId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "simulation": false,
  "results": {
    "rcs": {
      "accepted": false,
      "reasons": ["RCS not available"]
    },
    "sms": {
      "accepted": true,
      "unicode": false,
      "parts": 1,
      "reasons": []
    }
  }
}

:::warning Fallback e contenuto Quando il fallback SMS si attiva, il contenuto della rich card (immagini, bottoni) viene perso. Il gateway invia solo il testo. Per un'esperienza migliore, valuta di configurare anche un testo di fallback personalizzato. :::

Errori comuni

agentId non valido

{
  "status": "fail",
  "data": {
    "agentId": "Agent not found or not associated with your account"
  }
}

Soluzione: Verifica l'agentId nel pannello RCS della piattaforma. Ogni account ha un agente RCS associato.

Media URL non raggiungibile

Il messaggio viene accettato (accepted: true) ma la card arriva senza immagine. Verifica che l'URL sia:

• HTTPS (non HTTP)
• Pubblicamente accessibile
• Un formato immagine valido (JPEG, PNG)

Risultato atteso

Step	Azione	Risultato
1	Prepara media URL	Immagine accessibile via HTTPS
2	POST /rcs/send (type: CARD)	messageId restituito, accepted: true
3	GET /messages/status/{id}	deliveryStatus: "DELIVERED", readDate presente

Prossimi passi

• UC-001 — Invio SMS Singolo: Scenario base con canale SMS
• UC-003 — Invio WhatsApp Template: Messaggi WhatsApp con template approvati
• UC-004 — Verifica Delivery Status: Polling batch e confronto webhook
• Guida RCS: Documentazione completa del canale RCS
• Guida Template RCS: Crea e gestisci template RCS