Passa al contenuto principale

Domande Frequenti

Trova risposte a domande comuni su API Qlara Partner Gateway. Per supporto aggiuntivo, contatta il nostro team.

Autenticazione​

Quale metodo di autenticazione devo utilizzare?​

Consigliamo l'autenticazione con API Key per tutte le richieste. L'autenticazione con API Key è sicura, semplice da implementare e fornisce chiari audit trail per l'utilizzo della tua API.

Includi la tua API key nell'header X-Api-Key:

X-Api-Key: your_api_key_here

Dove posso trovare la mia API key?​

La tua API key è disponibile nella tua dashboard Qlara Partner Gateway sotto Impostazioni Account. Puoi trovarla nella sezione "API Keys".

Posso avere più API key?​

Sì, puoi creare più API key per diverse applicazioni o ambienti. Ogni key può essere gestita indipendentemente con i suoi permessi e può essere revocata senza influenzare altre key.

Per creare key aggiuntive:

  1. Naviga a Impostazioni Account → API Keys
  2. Clicca "Genera Nuova Key"
  3. Dai alla tua key un nome descrittivo
  4. Copia la key immediatamente (non potrai vederla di nuovo)

La mia API key è sensibile?​

Sì, tratta la tua API key come una password. Non condividerla mai o commitarla nel controllo di versione. Se credi che una key sia stata compromessa, revocala immediatamente nella tua dashboard e genera una nuova.

Invio di Messaggi​

Qual è la differenza tra "accepted" e "delivered"?​

  • Accepted: Il messaggio è stato con successo accettato dal carrier/provider e è in coda per la consegna. Questo accade velocemente (solitamente entro pochi secondi).
  • Delivered: Il messaggio è stato con successo consegnato al dispositivo del destinatario. Questo è confermato via callback webhook e potrebbe richiedere più tempo a seconda delle condizioni di rete.

Usa sempre i webhook di consegna per confermare la consegna effettiva all'utente finale.

Posso inviare messaggi WhatsApp senza template?​

Sì, puoi inviare messaggi liberi di WhatsApp al di fuori dei template. Tuttavia, i messaggi liberi sono validi solo entro una finestra di 24 ore dopo che il cliente ha interagito con la tua attività.

Dopo 24 ore di inattività, devi utilizzare un template approvato per inviare messaggi.

Come funziona il fallback RCS?​

Il fallback RCS (Rich Communication Services) consente al tuo messaggio di tentare automaticamente la consegna via RCS se la consegna WhatsApp fallisce.

Abilita il fallback RCS impostando fallbackRcs: true nella tua richiesta di invio:

\{
  "destination": "+39XXXXXXXXXX",
  "body": "Your message",
  "fallbackRcs": true
\}

Se WhatsApp non è disponibile per il destinatario, il messaggio si instrada automaticamente a RCS.

I link tracciati ti permettono di monitorare l'engagement dei messaggi e i tassi di click-through. Usa il placeholder \{shortLinkT1\} nei tuoi messaggi:

Click here to learn more: \{shortLinkT1\}

Il placeholder è automaticamente sostituito con un URL breve tracciato che registra i clic e fornisce analitiche.

Qual è la differenza tra Universal SMS e Legacy SMS?​

  • Universal SMS: Consegna SMS moderna con supporto per caratteri Unicode e messaggi più lunghi. Funziona a livello globale con tassi di consegna consistenti.
  • Legacy SMS: SMS tradizionale con supporto solo per caratteri ASCII di base. Usato per compatibilità all'indietro con sistemi più vecchi.

Universal SMS è consigliato per le nuove implementazioni.

Template​

Quanto tempo impiega l'approvazione del template WhatsApp?​

Meta generalmente approva i template WhatsApp entro 24 ore. Alcuni template potrebbero essere approvati più velocemente (entro minuti), mentre altri potrebbero richiedere più tempo a seconda della complessità del contenuto e del volume di revisione.

Durante i periodi di picco, l'approvazione potrebbe richiedere fino a 48 ore.

Posso modificare un template WhatsApp approvato?​

Sì, puoi modificare i template approvati, ma le modifiche richiedono un nuovo ciclo di approvazione. I template modificati sono trattati come nuovi template e devono essere ri-approvati da Meta prima dell'uso.

Per modificare un template:

  1. Usa l'endpoint di Aggiornamento Template
  2. Invia il template modificato per l'approvazione
  3. Attendi l'approvazione di Meta
  4. Distribuisci il template aggiornato quando approvato

Quali sono i tipi di template RCS?​

RCS supporta più tipi di template:

  • Text Templates: Messaggi semplici basati su testo
  • Card Templates: Card rich con immagini, titoli e pulsanti d'azione
  • Carousel Templates: Più card in un carosello scorrevole
  • Form Templates: Form interattive con campi di input

I template RCS sono più flessibili dei template WhatsApp e supportano formattazione più ricca.

Webhook​

Come configuro l'URL di callback?​

Configura l'URL di callback nella dashboard Qlara Partner Gateway:

  1. Vai a Impostazioni Account → Webhook
  2. Inserisci l'URL di callback (deve essere HTTPS)
  3. Salva la configurazione
  4. Testa la connessione webhook

L'URL di callback riceverà richieste POST con aggiornamenti di stato di consegna e messaggi in arrivo.

Cos'è il callback INBOUND?​

Il callback INBOUND ti notifica quando un cliente risponde al tuo messaggio o invia un nuovo messaggio alla tua attività.

Questo ti permette di:

  • Implementare flussi conversazionali
  • Tracciare l'engagement del cliente
  • Instradare messaggi ai team appropriati
  • Costruire esperienze interattive

Quanto tempo sono validi gli URL dei media nei webhook?​

Gli URL dei media inclusi nei payload webhook sono validi per una durata configurabile. Per impostazione predefinita, gli URL dei media scadono dopo 180 minuti (3 ore).

Questo è controllato dal parametro expireMinutes nelle impostazioni del tuo account. Assicurati di scaricare o elaborare i media entro la finestra di validità.

Cosa devo fare se perdo un webhook?​

I webhook potrebbero occasionalmente fallire a causa di problemi di rete o timeout. Implementa le seguenti best practice:

  • Logica di Retry: L'endpoint di callback deve gestire i retry e i timeout con grazia
  • Polling: Usa gli endpoint di polling dello stato come backup se i webhook falliscono
  • Idempotenza: Progetta il tuo sistema per gestire in modo sicuro le consegne webhook duplicate
  • Logging: Registra tutti gli eventi webhook per il controllo e il debug

Codici di Errore​

Cosa significano i codici di stato HTTP?​

CodiceStatoDescrizione
200OKRichiesta riuscita; messaggio inviato con successo
400Bad RequestRichiesta non valida (campi mancanti, formato errato, ecc.)
401UnauthorizedAPI key mancante, non valida o scaduta
403ForbiddenNon hai permesso di accedere a questa risorsa o numero di telefono
404Not FoundLa risorsa richiesta non esiste (template, numero di telefono non valido, ecc.)
422Unprocessable EntityRichiesta ben formata ma contiene errori semantici (formato telefono non valido, ecc.)
429Too Many RequestsLimite di tasso superato; attendi prima di riprovare
500Server ErrorErrore interno del server; il nostro team è stato notificato

Come devo gestire il rate limiting?​

Quando ricevi una risposta 429 Too Many Requests, attendi prima di riprovare:

  1. Controlla l'header Retry-After per il tempo di attesa consigliato
  2. Implementa backoff esponenziale: attendi 1 secondo, poi 2 secondi, poi 4 secondi, ecc.
  3. Imposta un tempo di attesa massimo (es. 5 minuti) prima di rinunciare
  4. Registra gli eventi di rate limit per identificare i modelli di utilizzo

Cosa causa un errore 422 Unprocessable Entity?​

Un errore 422 indica che la richiesta è ben formata ma contiene dati non validi:

  • Formato numero di telefono non valido (codice paese mancante, lunghezza errata)
  • Le variabili del template non corrispondono ai parametri del template
  • Numero di telefono di destinazione non whitelistato (in modalità test)
  • Formato file media non supportato
  • Dimensione del file supera i limiti

Controlla i dettagli dell'errore nella risposta per informazioni specifiche.

Come debuggo un errore 400 Bad Request?​

Un errore 400 significa che la richiesta è malformata. Cause comuni:

  • Campi obbligatori mancanti (destination, phoneNumberId, ecc.)
  • Errori di sintassi JSON
  • Tipi di dati non corretti (es. numero invece di stringa)
  • Valori vuoti o nulli nei campi obbligatori

Verifica che la tua richiesta corrisponda alle specifiche API e includa tutti i campi obbligatori.

Domande Generali​

Quali canali di messaggistica supporta Qlara?​

Qlara supporta più canali di messaggistica:

  • WhatsApp Business API
  • RCS (Rich Communication Services)
  • SMS
  • Email (tramite integrazioni partner)
  • Notifiche push (tramite integrazioni partner)

Puoi configurare catene di fallback per utilizzare automaticamente canali alternativi se il tuo canale principale non è disponibile.

C'è una garanzia di consegna del messaggio?​

Forniamo consegna "best-effort" con alta affidabilità. Tuttavia, la consegna del messaggio dipende da:

  • Connettività di rete del destinatario
  • Disponibilità dell'operatore
  • Validità del numero di telefono
  • Conformità del contenuto del messaggio

Monitora i webhook di consegna per confermare la consegna. Se la consegna fallisce, le catene di fallback indirizzano automaticamente ai canali alternativi.

Qual è la lunghezza massima del messaggio?​

La lunghezza massima del messaggio dipende dal canale:

  • WhatsApp: 4,096 caratteri per messaggio
  • RCS: 1,024 caratteri (può variare per operatore)
  • SMS: 160 caratteri (i caratteri UTF-8 contano come più byte)
  • Email: Nessun limite rigoroso, ma mantieni le righe dell'oggetto sotto 100 caratteri

Posso inviare messaggi in diverse lingue?​

Sì, tutti i canali supportano più lingue. Quando usi i template, specifica la lingua:

\{
  "template": \{
    "name": "greeting",
    "language": "it"
  \}
\}

Assicurati che il contenuto del messaggio e i media siano appropriati per la lingua e la regione di destinazione.

Come gestisco la conformità opt-in/opt-out?​

Qlara supporta più framework di conformità normativa:

  • GDPR (Unione Europea): Ottieni consenso esplicito prima di inviare messaggi promozionali
  • CCPA (California): Onora le richieste di opt-out entro 10 giorni
  • Normative SMS regionali: Conformità con requisiti specifici dell'operatore

Gestisci le liste opt-in/opt-out nelle impostazioni del tuo account o tramite endpoint API.

C'è un ambiente sandbox/test?​

Sì, usa numeri di telefono test in modalità sviluppo per inviare messaggi di test senza addebiti. Contatta il supporto per abilitare la modalità test per il tuo account.

In modalità test:

  • Solo i numeri test whitelistati possono ricevere messaggi
  • Non vengono addebitati costi
  • Tutta la funzionalità API è disponibile
  • I webhook funzionano normalmente

Come monitoro l'utilizzo della API?​

Monitora l'utilizzo della tua API nella dashboard:

  1. Vai a Analitiche → Utilizzo API
  2. Visualizza richieste, tassi di consegna e costi dei messaggi
  3. Imposta avvisi di utilizzo e quote
  4. Esporta report di utilizzo

Supporto e Contatti​

Per domande aggiuntive o supporto tecnico: