API RCS

RCS (Rich Communication Services) è la prossima generazione della messaggistica SMS. Invia messaggi con immagini, pulsanti cliccabili, card interattive e carousel per creare esperienze di messaggistica coinvolgenti e branded.

L'API RCS di Agile Telecom supporta messaggi rich completi con fallback SMS automatico su dispositivi non supportati.

Panoramica

RCS è supportato su Android nativamente e su alcuni client iOS tramite app SMS di terze parti. Se un destinatario non supporta RCS, il messaggio ricade automaticamente su SMS di testo semplice.

Usa RCS per:

• Messaggistica branded con il tuo logo e colori
• Cataloghi prodotto con immagini e prezzi
• Prenotazione appuntamenti con pulsanti di azione
• Sondaggi e feedback con pulsanti a risposta rapida
• Notifiche interattive con chiamate all'azione

Invia un Messaggio RCS

Endpoint: POST /api/message-server/rcs/send

Autenticazione

Usa API Key nell'header X-Api-Key (consigliato) o Basic Auth.

Richiesta di Base

{
  "destination": "+393471234567",
  "sender": "YourCompany",
  "body": "Welcome to RCS messaging!",
  "fallback": "This message requires RCS support"
}

Risposta di Successo

{
  "messageId": "abc-123-def-456",
  "status": "accepted",
  "channel": "RCS"
}

Tipi di Messaggi RCS

Testo Semplice

Il tipo di messaggio RCS più semplice.

{
  "destination": "+393471234567",
  "sender": "YourCompany",
  "body": "Hello! This is an RCS message.",
  "fallback": "Hello! This is an RCS message."
}

Messaggio con Card

Una card con immagine, titolo, descrizione e pulsanti di azione.

{
  "destination": "+393471234567",
  "sender": "YourCompany",
  "body": "Check out our new product!",
  "card": {
    "image": "https://example.com/product.jpg",
    "title": "New Product Launch",
    "description": "Discover our latest innovation",
    "buttons": [
      {
        "label": "View Details",
        "action": "https://example.com/product"
      },
      {
        "label": "Buy Now",
        "action": "https://example.com/buy"
      }
    ]
  },
  "fallback": "Check out our new product at example.com"
}

Carousel (Più Card)

Una sequenza di card scorrevoli.

{
  "destination": "+393471234567",
  "sender": "YourCompany",
  "body": "Browse our products",
  "carousel": [
    {
      "image": "https://example.com/product1.jpg",
      "title": "Product 1",
      "description": "Description of product 1",
      "buttons": [
        {
          "label": "View",
          "action": "https://example.com/product1"
        }
      ]
    },
    {
      "image": "https://example.com/product2.jpg",
      "title": "Product 2",
      "description": "Description of product 2",
      "buttons": [
        {
          "label": "View",
          "action": "https://example.com/product2"
        }
      ]
    }
  ],
  "fallback": "Browse our products at example.com"
}

Campi Pulsante

Ogni pulsante in una card o carousel deve avere:

Campo	Tipo	Obbligatorio	Descrizione
label	stringa	Sì	Testo del pulsante (max 25 caratteri)
action	stringa (URL)	Sì	URL a cui reindirizzare quando si fa clic

Limiti

• Max 3 pulsanti per card
• Max 10 card per carousel
• Label: max 25 caratteri
• Titolo: max 40 caratteri
• Descrizione: max 120 caratteri

Webhook di Consegna

Quando configuri un URL webhook nel portale, riceverai notifiche di consegna RCS:

{
  "channel": "RCS",
  "eventType": "DELIVERY",
  "messageId": "abc-123-def-456",
  "destination": "+393471234567",
  "statusCode": 3,
  "description": "delivered",
  "eventDate": "2025-11-24T16:10:21Z"
}

Codici di Stato RCS

Codice	Stato	Significato
1	Accettato	Messaggio in coda per consegna
2	Rifiutato	Validazione fallita prima dell'invio
3	Consegnato	Confermato consegnato al dispositivo
4	Scaduto	Finestra di consegna trascorsa
5	Fallback SMS	Inviato come SMS perché RCS non è supportato
6	Non Consegnabile	Errore permanente di consegna

Best Practice

• Sempre fornisci un fallback SMS per dispositivi non supportati
• Mantieni i pulsanti brevi e actionabili
• Usa immagini di alta qualità (consigliato: 1200x627 pixel)
• Testa su diversi dispositivi Android per una corretta visualizzazione
• Non abuse di messaggi RCS — usali per comunicazioni importanti e branded

Supporto

Per assistenza tecnica, contatta help@agiletelecom.com.

Qual è il Prossimo?

• Template RCS — crea template riutilizzabili per messaggi RCS
• API REST SMS — fallback SMS standard
• Inbound SMS — ricevi messaggi in risposta