Guida all'integrazione API
Messaggistica WhatsApp per comunicazioni pre e post appuntamento

1.Concetti generali

L'integrazione avviene tramite una singola API REST. Il gestionale invia una richiesta HTTP ogni volta che deve essere inviato un messaggio WhatsApp a un paziente/cliente; IntelFriends si occupa della consegna effettiva tramite l'infrastruttura WhatsApp Business.

• Protocollo: HTTPS esclusivamente (richieste in chiaro su HTTP vengono rifiutate).
• Formato dati: JSON, sia in richiesta che in risposta.
• Modello: asincrono — la richiesta viene accettata e messa in coda; l'invio effettivo avviene a breve giro, non in tempo reale all'interno della stessa risposta HTTP.
• Ogni gestionale partner riceve credenziali dedicate, distinte da quelle di altri gestionali.

2.Autenticazione

Ogni richiesta deve includere una API key nell'header HTTP Authorization, in formato Bearer token:

Authorization: Bearer if_live_xxxxxxxxxxxxxxxxxxxx

La API key identifica univocamente il gestionale partner: non è necessario indicare il nome del gestionale nel corpo della richiesta. La chiave viene fornita da IntelFriends al momento dell'attivazione dell'integrazione ed è revocabile e rinnovabile su richiesta in caso di necessità (es. sospetta compromissione).

3.Identificazione del cliente finale

Ogni richiesta deve indicare a quale cliente finale (es. studio medico/dentistico) si riferisce il messaggio, tramite il campo client_ref.

• client_ref è l'identificativo che il gestionale già utilizza internamente per quel cliente — non è necessario adottare un nuovo sistema di codici.
• IntelFriends mantiene una mappatura tra (gestionale, client_ref) e la configurazione tecnica necessaria all'invio (numero WhatsApp associato, ecc.).
• Se un client_ref non risulta configurato lato IntelFriends, la richiesta viene rifiutata con codice 404 — non viene creato automaticamente.

4.Invio di un messaggio

Endpoint

POST https://api.intelfriends.com/v1/messages

Esempio di richiesta

{
  "client_ref": "STUDIO_ROSSI_MILANO",
  "recipient": "+393331234567",
  "template": "promemoria_richiesta_conferma",
  "variables": {
    "nome_cognome": "Mario Rossi",
    "data_ora": "2026-06-27T15:30:00+02:00",
    "indirizzo_completo": "Via Roma 12, Milano",
    "operatore": "Dr.ssa Bianchi",
    "link_conferma": "https://gestionale.example.com/c/8f3k2"
  }
}

Esempio di risposta (202 Accepted)

{
  "message_id": "msg_3f9a2k7h",
  "status": "queued"
}

Conservare il message_id restituito: è il riferimento univoco da utilizzare per qualunque comunicazione futura relativa a quel messaggio.

5.Variabili disponibili

Le variabili vengono passate come oggetto nominato (chiave/valore), non come elenco posizionale. Questo rende l'integrazione più leggibile e tollerante a future modifiche.

6.Template disponibili

Ogni template richiede solo il sottoinsieme di variabili indicato: variabili non richieste dal template selezionato vengono ignorate se presenti. Il testo riportato è quello effettivamente inviato — le parti tra {{ }} sono sostituite con il valore della variabile corrispondente; il resto è fisso e non modificabile in questa versione.

Gentile paziente, la sua prenotazione è stata confermata per {{nome_cognome}} nella seguente data {{data_ora}}.

Dettagli Appuntamento:
📍 Ci trova in {{indirizzo_completo}}
{{operatore}}
{{note}}

Gentile paziente, questo è un promemoria del suo appuntamento per {{nome_cognome}} nella seguente data {{data_ora}}.

Dettagli Appuntamento:
📍 Ci trova in {{indirizzo_completo}}
{{operatore}}
{{note}}

La preghiamo di confermare la sua presenza selezionando un'opzione.

Gentile paziente, questo è un promemoria del suo appuntamento per {{nome_cognome}} nella seguente data {{data_ora}}.

Dettagli Appuntamento:
📍 Ci trova in {{indirizzo_completo}}
{{operatore}}
{{note}}

Gentile paziente, rimaniamo a disposizione per qualsiasi domanda sul post-trattamento. La sua recensione su Google aiuterebbe altre persone a trovarci. Grazie!

Gentile paziente, le scriviamo da {{nome_studio}} in merito al suo richiamo periodico di igiene dentale.

Secondo le indicazioni registrate presso lo studio, il prossimo richiamo è previsto a breve.

Può rispondere a questo messaggio per confermare la sua disponibilità o riprenotare tramite il seguente canale: {{link_richiamo}}

Grazie.

Nuovi template possono essere aggiunti su richiesta. Contattare IntelFriends per definire variabili, bottoni e formato testo.

7.Idempotenza

Per evitare invii duplicati in caso di ritrasmissioni (timeout, retry automatici, errori di rete), ogni richiesta deve includere un header Idempotency-Key con un valore univoco per quel singolo messaggio (consigliato: un UUID v4).

Idempotency-Key: 7c1b2e44-9f3a-4d2e-8b1a-2f6e9c0d1a5b

Se la stessa Idempotency-Key viene ricevuta più volte con lo stesso payload, IntelFriends restituisce la risposta originale senza inviare nuovamente il messaggio. Se viene riutilizzata con un payload differente, la richiesta viene rifiutata (codice 409).

8.Codici di risposta

In caso di errore (4xx/5xx), il corpo della risposta include un campo error con codice e descrizione leggibile:

{
  "error": {
    "code": "client_ref_not_found",
    "message": "Nessuna configurazione trovata per client_ref 'STUDIO_X'."
  }
}

9.Sicurezza

• Tutte le richieste devono avvenire esclusivamente su HTTPS.
• La API key non va mai inclusa nell'URL o nei parametri di query, solo nell'header Authorization.
• Si raccomanda la rotazione periodica della API key; IntelFriends può fornire una nuova chiave su richiesta mantenendo continuità del servizio.
• Non inviare dati sanitari sensibili nel campo note oltre a quanto strettamente necessario per il messaggio; il contenuto dei template è pensato per restare su informazioni organizzative (data, orario, operatore).
• IntelFriends non conserva nei log applicativi il contenuto delle variabili oltre il periodo strettamente necessario all'invio e al supporto tecnico.

10.Limiti di frequenza (rate limiting)

Ogni API key è soggetta a un limite di richieste al secondo, comunicato in fase di attivazione e proporzionato al volume previsto dal gestionale. Il superamento del limite restituisce codice 429 con un header Retry-After che indica dopo quanti secondi è possibile ritentare.

11.Roadmap — funzionalità future

Le seguenti funzionalità non sono incluse nella versione attuale e potranno essere aggiunte in versioni successive, in modo retrocompatibile:

• Webhook di notifica verso il gestionale per stato di consegna e risposte ricevute dal paziente.
• Tracciamento delle interazioni sui link di conferma.

Eventuali aggiornamenti a questo documento saranno numerati in modo incrementale (es. v1.1) e segnalati al team tecnico del gestionale partner.