Passa al contenuto principale

UC-005 — Invio Multi-Canale con Fallback Automatico

CampoValore
IDUC-005
ObiettivoInviare un messaggio su WhatsApp con fallback automatico a RCS e SMS
CanaleWhatsApp → RCS → SMS
Complessità⭐⭐ Intermedio
Tempo stimato15 minuti
API coinvoltePOST /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.

:::info 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​

CampoTipoObbligatorioDescrizione
destinationstringSiNumero in formato internazionale (es. +393401234567)
phoneNumberIdintegerSiID del numero WhatsApp Business mittente
templateobjectSi*Template approvato da Meta (*alternativo a body)
placeholdersobjectNoValori da sostituire nel template
fallbackRcs.agentIdintegerSiID agente RCS mittente
fallbackRcs.templateIdintegerSi*Template RCS (*alternativo a body)
fallbackSms.senderstringSiMittente SMS (alfanumerico o numerico)
fallbackSms.textstringSiTesto del messaggio SMS di fallback

Step 2 — Invia il messaggio​

Invoca l'endpoint WhatsApp con la fallback chain completa.

curl -X POST https://lora-api.agiletelecom.com/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​

Dopo qualche secondo, interroga lo stato di consegna per scoprire quale canale ha effettivamente recapitato il messaggio.

curl -X GET "https://lora-api.agiletelecom.com/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": "Message delivered to handset",
  "sendDate": "2026-04-09T10:15:00+02:00",
  "deliveryDate": "2026-04-09T10:15:04+02:00",
  "readDate": null
}

Il campo channel indica quale canale ha effettivamente consegnato il messaggio.

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://lora-api.agiletelecom.com/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​

SituazioneAzione
Tutti i canali rifiutanoVerifica il numero destinatario e riprova
Solo SMS fallisceControlla il sender ID e il testo (lunghezza, caratteri speciali)
WhatsApp rifiutato, RCS/SMS okIl destinatario potrebbe non avere WhatsApp — il fallback funziona correttamente
Errore 422Template non approvato o phoneNumberId non valido
Errore 429Rate limit superato — attendi e riprova

Risultato atteso​

StepAzioneRisultato
1Componi body con fallbackRcs + fallbackSmsCatena di fallback configurata
2POST /whatsapp/sendmessageId restituito, almeno un canale accepted: true
3GET /messages/status/{id}channel indica il canale che ha consegnato

Prossimi passi​