UC-005 — Invio Multi-Canale con Fallback Automatico

Campo	Valore
ID	UC-005
Obiettivo	Inviare un messaggio su WhatsApp con fallback automatico a RCS e SMS
Canale	WhatsApp → RCS → SMS
Complessità	⭐⭐ Intermedio
Tempo stimato	15 minuti
API coinvolte	POST /api/message-server/whatsapp/send, GET /api/partner-gateway/v1/messages/status/{customerMessageId}

Scenari reali

• Banca Adriatica — Notifica transazione: La banca notifica al correntista una transazione sospetta. Priorita WhatsApp per il messaggio ricco con bottoni di conferma/blocco, fallback SMS per garantire la ricezione anche se il cliente non usa WhatsApp.
• TelcoMobile — Billing reminder: Promemoria scadenza fattura con link al pagamento. WhatsApp per il documento allegato, SMS come rete di sicurezza.
• FarmaExpress — Ordine pronto: La farmacia online avvisa che l'ordine e pronto al ritiro. WhatsApp con mappa del punto di ritiro, SMS con indirizzo testuale in caso di fallback.

Flusso del fallback

Il diagramma illustra la catena di fallback: il sistema tenta prima WhatsApp, poi RCS se disponibile, infine SMS come ultima risorsa.

Step 1 — Componi il messaggio con fallback chain

Il body della richiesta include il messaggio principale (WhatsApp) e due oggetti di fallback: fallbackRcs per RCS e fallbackSms per SMS.

Regola importante

Se specifichi fallbackRcs, devi obbligatoriamente includere anche fallbackSms. Puoi invece usare solo fallbackSms senza RCS per un fallback diretto WhatsApp → SMS.

Struttura del body

Campo	Tipo	Obbligatorio	Descrizione
destination	string	Si	Numero in formato internazionale (es. +393401234567)
phoneNumberId	integer	Si	ID del numero WhatsApp Business mittente
template	object	Si*	Template approvato da Meta (*alternativo a body)
placeholders	object	No	Valori da sostituire nel template
fallbackRcs.agentId	integer	Si	ID agente RCS mittente
fallbackRcs.templateId	integer	Si*	Template RCS (*alternativo a body)
fallbackSms.sender	string	Si	Mittente SMS (alfanumerico o numerico)
fallbackSms.text	string	Si	Testo del messaggio SMS di fallback

Step 2 — Invia il messaggio

Invoca l'endpoint WhatsApp con la fallback chain completa.

curl -X POST https://api.qlara.ai/api/message-server/whatsapp/send \
  -H "Content-Type: application/json" \
  -H "X-Api-Key: YOUR_API_KEY" \
  -d '{
    "destination": "+393401234567",
    "phoneNumberId": 5,
    "template": {
      "id": 42
    },
    "placeholders": {
      "nome": "Giulia",
      "importo": "1.250,00",
      "data": "09/04/2026"
    },
    "enableNotification": true,
    "messageId": "txn-notifica-20260409-001",
    "fallbackRcs": {
      "agentId": 1,
      "templateId": 10
    },
    "fallbackSms": {
      "sender": "BancaAdri",
      "text": "Gentile Giulia, e stata registrata una transazione di EUR 1.250,00 in data 09/04/2026. Se non riconosci questa operazione, chiama il numero verde 800.123.456."
    }
  }'

Response — WhatsApp accettato

{
  "messageId": "txn-notifica-20260409-001",
  "simulation": false,
  "results": {
    "whatsapp": {
      "accepted": true
    },
    "rcs": null,
    "sms": null
  }
}

Quando WhatsApp accetta il messaggio, i campi rcs e sms restano null perché il fallback non si e attivato.

Response — Fallback attivato fino a SMS

{
  "messageId": "txn-notifica-20260409-001",
  "simulation": false,
  "results": {
    "whatsapp": {
      "accepted": false
    },
    "rcs": {
      "accepted": false,
      "reasons": ["AGENT_NOT_REACHABLE"]
    },
    "sms": {
      "accepted": true,
      "unicode": false,
      "parts": 2,
      "reasons": []
    }
  }
}

Dietro le quinte — Come funziona la catena di fallback

1. Tentativo WhatsApp: Il messaggio viene inoltrato a Meta tramite WhatsApp Business API. Se il numero destinatario e registrato su WhatsApp e il template e approvato, il messaggio viene accettato.
2. Fallback RCS: Se WhatsApp non riesce (numero non registrato, template rifiutato, errore di rete), il sistema tenta automaticamente RCS usando agentId e templateId forniti.
3. Fallback SMS: Se anche RCS fallisce (dispositivo non compatibile, agente non raggiungibile), il sistema invia un SMS con il sender e text specificati.

Ogni livello e indipendente: puoi ricevere callback di delivery separate per il canale che ha effettivamente consegnato. Il messageId resta lo stesso lungo tutta la chain, permettendo la correlazione end-to-end.

Step 3 — Verifica quale canale ha consegnato

La response di invio ti dice quale canale ha accettato il messaggio: nell'esempio di fallback qui sopra, results.sms.accepted è true. Dopo qualche secondo, interroga lo stato di consegna su quel canale (il parametro channel è obbligatorio).

curl -X GET "https://api.qlara.ai/api/partner-gateway/v1/messages/status/txn-notifica-20260409-001?channel=SMS" \
  -H "X-Api-Key: YOUR_API_KEY"

Response — Consegnato via SMS

{
  "customerMessageId": "txn-notifica-20260409-001",
  "channel": "SMS",
  "destination": "+393401234567",
  "deliveryStatus": "DELIVERED",
  "deliveryStatusDescription": "delivered",
  "sendDate": "2026-04-09T10:15:00+02:00",
  "deliveryDate": "2026-04-09T10:15:04+02:00",
  "readDate": null
}

Il campo channel riporta il canale che hai interrogato: da solo non ti dice quale canale ha consegnato. Fai riferimento al canale che ha accettato il messaggio nella response di invio, oppure al campo channel dell'evento webhook di consegna.

Variante — Fallback diretto WhatsApp → SMS (senza RCS)

Se non hai un agente RCS configurato, puoi saltare il livello intermedio omettendo fallbackRcs:

curl -X POST https://api.qlara.ai/api/message-server/whatsapp/send \
  -H "Content-Type: application/json" \
  -H "X-Api-Key: YOUR_API_KEY" \
  -d '{
    "destination": "+393489876543",
    "phoneNumberId": 5,
    "template": {
      "id": 55
    },
    "placeholders": {
      "cliente": "Marco Bianchi",
      "scadenza": "15/04/2026",
      "importo": "89,90"
    },
    "fallbackSms": {
      "sender": "TelcoMob",
      "text": "Gentile Marco Bianchi, la sua fattura di EUR 89,90 scade il 15/04/2026. Acceda all area clienti per il pagamento."
    }
  }'

{
  "messageId": "d3f8a1b2-c4e5-6789-abcd-ef0123456789",
  "simulation": false,
  "results": {
    "whatsapp": {
      "accepted": true
    },
    "rcs": null,
    "sms": {
      "accepted": true,
      "unicode": false,
      "parts": 1,
      "reasons": []
    }
  }
}

Errori comuni

Tutti i canali falliscono

Se nessun canale riesce ad accettare il messaggio, la response indica accepted: false per ogni livello:

{
  "messageId": "txn-notifica-20260409-002",
  "simulation": false,
  "results": {
    "whatsapp": {
      "accepted": false
    },
    "rcs": {
      "accepted": false,
      "reasons": ["AGENT_NOT_REACHABLE"]
    },
    "sms": {
      "accepted": false,
      "reasons": ["INVALID_DESTINATION"]
    }
  }
}

Tabella azioni correttive

Situazione	Azione
Tutti i canali rifiutano	Verifica il numero destinatario e riprova
Solo SMS fallisce	Controlla il sender ID e il testo (lunghezza, caratteri speciali)
WhatsApp rifiutato, RCS/SMS ok	Il destinatario potrebbe non avere WhatsApp — il fallback funziona correttamente
Errore 422	Template non approvato o phoneNumberId non valido
Errore 429	Rate limit superato — attendi e riprova

Risultato atteso

Step	Azione	Risultato
1	Componi body con fallbackRcs + fallbackSms	Catena di fallback configurata
2	POST /whatsapp/send	messageId restituito, almeno un canale accepted: true
3	GET /messages/status/{id}?channel=SMS	deliveryStatus: "DELIVERED" sul canale che ha accettato il messaggio

Prossimi passi

• UC-008 — Tracking Consegna con Webhooks: Ricevi aggiornamenti in tempo reale su quale canale ha consegnato
• Guida WhatsApp: Approfondisci template, media e la finestra delle 24 ore
• Panoramica canali: Confronta SMS, RCS e WhatsApp per scegliere la strategia giusta