ITA – RCS REST API / Protocollo HTTP

Cos’è RCS (per chi parte da zero) #

RCS è l’evoluzione dei messaggi sullo smartphone. A differenza degli SMS, consente contenuti multimediali, pulsanti di Call to Action (CTA), e una conversazione bidirezionale con un mittente verificato chiamato RCS Agent.

Perché RCS #

Brand visibile: nome e icone del RCS Agent.
Contenuti ricchi: testo, immagini, card e carousel.
Pulsanti (Suggestions/CTA): link, chiamate, risposte guidate.
Conversazione: gestisci le risposte dell’utente.

Quando usarlo #

Notifiche “ricche” (con immagini e pulsanti).
Promozioni e carrelli (card/carousel).
Assistenza clienti conversazionale.

Requisiti utente: smartphone e app messaggi compatibili con RCS; connessione internet attiva.

Come usare questa guida #

Chi: pensata anche per lettori non tecnici.
Come: esempi brevi, JSON minimali, box “Nota/Avvertenza”.
Collection Postman: importa la collection ufficiale per provare subito gli endpoint.

Guida ai JSON dei Template (documento separato) #

Questa documentazione non replica la descrizione completa dei body JSON dei template RCS. Per struttura, campi obbligatori/opzionali, esempi completi (TEXT, CARD, CAROUSEL), Suggestions/CTA, gestione Media, Placeholder e Fallback SMS fai riferimento al Crea un template RCS

Ogni volta che trovi “body: vedi guida-template-rcs” definisci il JSON seguendo quella guida e incollalo nell’endpoint indicato (POST https://lora-api.agiletelecom.com/rcs/templates o POST https://lora-api.agiletelecom.com/rcs/send per l’invio libero).

Autenticazione e sicurezza #

Protocollo – HTTPS obbligatorio
Auth – API Key in header (es. X-Api-Key)

Concetti RCS essenziali #

Tipi di messaggio supportati da RCS #

TEXT: messaggio di testo.
CARD: singola scheda con immagine/testo/CTA.
CAROUSEL: più card scorrevoli.

Suggestions (CTA) #

Pulsanti azione: reply, url, dial, coordinates, location, calendar.

Media #

Le card supportano immagini. Fornisci URL pubblici e validi per tutto l’invio. Imposta correttamente il height.

Placeholder #

Se usi variabili (es. {name}), fornisci i valori nell’invio. In mancanza, la variabile apparirà “non sostituita”.

Fallback SMS: opzionale. Se il contatto non è raggiungibile via RCS, puoi inviare un SMS sostitutivo (il sender deve essere sempre autorizzato, puoi richiederlo gratuitamente in piattaforma).

Quickstart #

Elenca gli Agent RCS con GET https://lora-api.agiletelecom.com/rcs/agents e recupera agentId.
Invia da template con POST https://lora-api.agiletelecom.com/rcs/send indicando templateId, destination, agentId, eventuali placeholders.
Ricevi gli esiti tramite webhook di Delivery/Read e gestisci le risposte (Inbound).

GET https://lora-api.agiletelecom.com/rcs/agents
Authorization: X-Api-Key: <API_KEY>

La risposta contiene l’elenco degli agent configurati per il tuo account.

Template RCS (CRUD) #

La struttura completa dei body JSON per i template (TEXT, CARD, CAROUSEL, Suggestions, Media, Placeholder, Fallback) è descritta in guida-template-rcs.

Lista #

La lista è fornita in modalità paginata, si può scegliere quanti record visualizzare per pagina variando il valore di limit e quale pagina visualizzare variando il valore di page.

GET https://lora-api.agiletelecom.com/rcs/templates?limit=10&page=1
Authorization: X-Api-Key: <API_KEY>

Dettaglio #

Restituisce il singolo template con l’id specificato nella path.

GET https://lora-api.agiletelecom.com/rcs/templates/:id
Authorization: X-Api-Key: <API_KEY>

Creazione #

Permette di creare un nuovo template da utilizzare successivamente per la spedizione.

POST https://lora-api.agiletelecom.com/rcs/templates
Authorization: X-Api-Key: <API_KEY>
Content-Type: application/json

// body: vedi guida-template-rcs

Modifica #

Permette di modificare un template.

PUT https://lora-api.agiletelecom.com/rcs/templates/:id
Authorization: X-Api-Key: <API_KEY>
Content-Type: application/json

// body: vedi guida-template-rcs

Cancellazione #

Permette di cancellare un template.

DELETE https://lora-api.agiletelecom.com/rcs/templates/:id
Authorization: X-Api-Key: <API_KEY>

Invio dei messaggi #

Invio da template #

Usa messageId servirà per associare i rapporti di consegna (delivery) e gli eventi di lettura che possono essere cosegnati via webhook. scheduledDate è opzionale ma utile se si vuole programmare l’invio nel futuro.

POST https://lora-api.agiletelecom.com/rcs/send
Authorization: X-Api-Key: <API_KEY>
Content-Type: application/json

{
  "templateId": "tpl_123",
  "destination": "+391234567890",
  "agentId": "agent_abc",
  "messageId": "ext-unique-id-001",
  "placeholders": {"name": "Anna"},
  "simulation": false,
  "scheduledDate": "2026-01-12T10:30:00Z"
}

Invio libero (senza template) #

Permette di definire un messaggio definendo un template “al volo” che non sarà memorizzato ma utilizzato solo per il singolo invio.

POST https://lora-api.agiletelecom.com/rcs/send
Authorization: X-Api-Key: <API_KEY>
Content-Type: application/json

{
  "agentId": "agent_abc",
  "destination": "+391234567890",
  "messageId": "ext-unique-id-002",
  "body": << vedi guida-template-rcs >>
}

Schedulazioni & Simulazione #

scheduledDate: formato ISO-8601; il fuso orario va gestito dal chiamante.
simulation: modalità prova; le risposte indicano l’esito di accettazione della piattaforma ma non verrà effettuato alcun invio reale.

Fallback SMS #

Da configurare nel template o nel body libero. Richiede un sender SMS autorizzato. L’autorizzazione può essere richiesta in piattaforma gratuitamente.

Eventi asincroni: Delivery & Read #

Gli esiti finali non arrivano nella risposta immediata all’invio, ma tramite webhook verso l’endpoint configurabile in piattaforma. La risposta all’invio indica solo la presa in carico mentre l’evento di consegna e/o lettura può essere istantaneo o richiedere anche alcune ore poichè dipente della rete, del telefono e dall’utente stesso

Al fine di facilitare la lettura degli eventi di consegna e lettura si è cercato di uniformare il più possibile il loro formato:

Delivery #

{
  "channel": "RCS",
  "eventType": "DELIVERY",
  "messageId": "ext-unique-id-001",
  "destination": "+391234567890",
  "statusCode": "DELIVERED",
  "description": "Message delivered",
  "timestamp": "2025-11-12T10:30:10Z"
}

Read #

{
  "channel": "RCS",
  "eventType": "READ",
  "messageId": "ext-unique-id-001",
  "destination": "+391234567890",
  "timestamp": "2025-11-12T10:32:45Z"
}

Si eseguono fino a cinque retry intervallati da qualche minuto sul tuo webhook: se non rispondi correttamente, dopo il quinto retry la piattaforma interrompe i tentativi ritentare.

Messaggi in entrata (Inbound) e Media #

Le risposte dell’utente e i contenuti multimediali arrivano al tuo endpoint Inbound.

Come per le notifiche di consegna e lettura anche per i messaggi ri risposta si è cercato di uniformare il più possibile il formato. La sorgente (source) è il numero di telefono del utente che risponde mentre la destinazione (destination) è l’agente RCS che riceve il messaggio di risposta.

Inbound testo #

Contiene il testo ed eventuali emoticons inserite dall’utente.

{
  "channel": "RCS",
  "messageType": "TEXT",
  "source": "+391234567890",
  "destination": "agent_abc",
  "receivedDate": "2025-11-12T10:35:20Z",
  "text": "Sì, sono interessata"
}

Inbound con media #

Contiene un a chiave (mediaKey) utile a recuerare l’immagine inviata dall’utente.

{
  "channel": "RCS",
  "messageType": "IMAGE",
  "source": "+391234567890",
  "destination": "agent_abc",
  "receivedDate": "2025-11-12T10:36:05Z",
  "mediaKey": "rcs-media-001"
}

Recupero media #

Il valore della chiave (mediaKey) è quello presente nel messaggio di Inbound con media.

GET https://lora-api.agiletelecom.com/files/{mediaKey}?expireMinutes=15
Authorization: X-Api-Key: <API_KEY>

La risposta fornisce un URL pubblico e temporaneo per il download del file.

Modelli rapidi (snippet operativi) #

Creazione template #

POST https://lora-api.agiletelecom.com/rcs/templates
// body: vedi guida-template-rcs

Invio da template #

POST https://lora-api.agiletelecom.com/rcs/send
{
  "templateId": "tpl_123",
  "destination": "+391234567890",
  "agentId": "agent_abc",
  "messageId": "ext-unique-id-003"
}

Invio libero #

POST https://lora-api.agiletelecom.com/rcs/send
{
  "agentId": "agent_abc",
  "destination": "+391234567890",
  "messageId": "ext-unique-id-004",
  "body": << vedi guida-template-rcs >>
}

Best practice & checklist #

Placeholder: fornisci sempre i valori richiesti; in caso controrio non avverà la sostituzione.
Media: usa URL pubblici e stabili fino al termine dell’invio della campagna; imposta sempre un valore di height coerente.
Suggestions: rispetta i campi previsti per ogni tipo.
Idempotenza: usa sempre messageId univoci.
Errori: gestisci 4xx (input) e 5xx (temporanei) con retry esponenziale dove sensato

Import Collection Postman & configurazione variabili #

Step 1 — Importa la Collection #

Apri Postman → Import.
Seleziona il file della collection:
AgileTelecom RCS API.postman_collection.json
Conferma con Import. Comparirà la collezione “AgileTelecom RCS API”.

La collection contiene già le richieste per: Agents, Template (CRUD), Invio, Webhook di esempio (lato utente), Download media.

Step 2 — Imposta le variabili di Collection #

Nell’albero a sinistra, fai clic sulla collezione AgileTelecom RCS API.
Apri la tab Variables (variabili di collezione) e compila i campi seguenti:

      BASE_URL     https://lora-api.agiletelecom.com 
      (verrà usata in tutte le richieste come {{BASE_URL}})
    
      API_KEY     
      La tua chiave API 
      (usata negli header delle richieste) generabile dalla piattaforma
    
      DESTINATION     Numero di telefono destinatario, es. +391234567890
    
      AGENT_ID     ID del tuo RCS Agent 
      (puoi ottenerlo con GET {{BASE_URL}}/api/message-server/rcs/agents)
    
      TEMPLATE_ID_TEXT     ID di un template di tipo TEXT già creato
    
      TEMPLATE_ID_CARD     ID di un template di tipo CARD già creato
    
      SCHEDULED_DATE     Data/ora per invii schedulati, es. 2026–01–30 18:50:00.000+0000
    
      MESSAGE_ID     Identificativo univoco per idempotenza del messaggio, es. uuid-1
    
      MEDIA_KEY     Valore per il download di media in inbound 
      (usato da GET {{BASE_URL}}/api/files/:mediaKey) per recuperare i media dell’inbound

Queste variabili sono tutte definite come variabili di Collection nella Postman Collection e sono già referenziate nelle richieste tramite {{NOME_VARIABILE}}.

Step 3 — Esegui le richieste #

Agents: GET {{BASE_URL}}/api/message-server/rcs/agents → recupera gli agentId.
Template (CRUD):
- Lista: GET {{BASE_URL}}/api/message-server/rcs/templates?limit=10&page=0
- Dettaglio: GET {{BASE_URL}}/api/message-server/rcs/templates/:id
- Creazione: POST {{BASE_URL}}/api/message-server/rcs/templates
- Modifica: PUT {{BASE_URL}}/api/message-server/rcs/templates/:id
- Cancellazione: DELETE {{BASE_URL}}/api/message-server/rcs/templates/:id
Invio:
- Da template: POST {{BASE_URL}}/api/message-server/rcs/send (usa {{TEMPLATE_ID_TEXT}} o {{TEMPLATE_ID_CARD}}, {{DESTINATION}}, {{AGENT_ID}}, {{MESSAGE_ID}}).
- Libero: POST {{BASE_URL}}/api/message-server/rcs/send con body completo (vedi “Guida Template” integrata).
Media: GET {{BASE_URL}}/api/files/:mediaKey?expireMinutes=180 (usa {{MEDIA_KEY}}).

// Esempio: invio da template (usa le variabili di Collection)
POST {{BASE_URL}}/api/message-server/rcs/send
X-Api-Key: {{API_KEY}}
Content-Type: application/json

{{
  "templateId": "{{TEMPLATE_ID_TEXT}}",
  "destination": "{{DESTINATION}}",
  "agentId": "{{AGENT_ID}}",
  "messageId": "{{MESSAGE_ID}}",
  "placeholders": {{"name": "Anna"}}
}}

Attenzione: #

Se dopo l’import trovi BASE_URL con un valore diverso (es. interno/di test), sostituiscilo con https://lora-api.agiletelecom.com nella tab Variables della collection.
Ricordati l’header X-Api-Key: {{API_KEY}} nelle richieste che lo richiedono.

Riferimenti API (indice rapido) #

Agents: GET https://lora-api.agiletelecom.com/rcs/agents
Templates:
- GET https://lora-api.agiletelecom.com/rcs/templates
- GET https://lora-api.agiletelecom.com/rcs/templates/:id
- POST https://lora-api.agiletelecom.com/rcs/templates → body: vedi guida-template-rcs
- PUT https://lora-api.agiletelecom.com/rcs/templates/:id → body: vedi guida-template-rcs
- DELETE https://lora-api.agiletelecom.com/rcs/templates/:id
Invio: POST https://lora-api.agiletelecom.com/rcs/send (da template o libero) → per il body libero: vedi guida-template-rcs
Webhook (verso cliente): Delivery/Read, Inbound (payload lato cliente definibile nella piattaforma web)
Media: GET https://lora-api.agiletelecom.com/files/:mediaKey?expireMinutes=...

FAQ #

Vedo { }name{ } nel messaggio ricevuto. Perché? #

Manca il valore del placeholder in invio. Fornisci placeholders o rimuovi la variabile.

L’immagine non si carica. #

Verifica che l’URL sia pubblico e raggiungibile e che l’height sia impostato correttamente.

La risposta all’invio dice solo “accepted”. L’invio è andato a buon fine? #

“Accepted” indica che la piattaforma ha accettato il messaggio. L’esito finale arriva via webhook (Delivery/Read).

Il fallback SMS fallisce. #

Assicurati che il sender SMS sia autorizzato o disabilita il fallback.

Come verifico se un destinatario è raggiungibile RCS? #

In assenza di un endpoint di verifica, usa il fallback SMS e osserva gli esiti Delivery RCS.

Cos’è RCS (per chi parte da zero) #

Perché RCS #

Quando usarlo #

Come usare questa guida #

Guida ai JSON dei Template (documento separato) #

Autenticazione e sicurezza #

Autenticazione e sicurezza #

Concetti RCS essenziali #

Tipi di messaggio supportati da RCS #

Suggestions (CTA) #

Media #

Placeholder #

Quickstart #

Template RCS (CRUD) #

Lista #

Dettaglio #

Creazione #

Modifica #

Cancellazione #

Invio dei messaggi #

Invio da template #

Invio libero (senza template) #

Schedulazioni & Simulazione #

Fallback SMS #

Eventi asincroni: Delivery & Read #

Delivery #

Read #

Messaggi in entrata (Inbound) e Media #

Inbound testo #

Inbound con media #

Recupero media #

Modelli rapidi (snippet operativi) #

Creazione template #

Invio da template #

Invio libero #

Best practice & checklist #

Import Collection Postman & configurazione variabili #

Step 1 — Importa la Collection #

Step 2 — Imposta le variabili di Collection #

Step 3 — Esegui le richieste #

Attenzione: #

Riferimenti API (indice rapido) #

FAQ #

Vedo { }name{ } nel messaggio ricevuto. Perché? #

L’immagine non si carica. #

La risposta all’invio dice solo “accepted”. L’invio è andato a buon fine? #

Il fallback SMS fallisce. #

Come verifico se un destinatario è raggiungibile RCS? #

What are your Feelings

Products

Industries

Developers

How we work

Get in touch