Per Iniziare con la Qlara Platform API

Qlara Platform è un'API REST unificata che ti permette di inviare messaggi tramite SMS, RCS e WhatsApp, gestire contatti e liste, eseguire campagne di messaggistica massiva e tracciare le consegne in tempo reale.

Ottieni la tua API key in 2 minuti

Accedi a Qlara, genera una chiave e invia il tuo primo messaggio.

1. Accedi al tuo workspace Qlara
2. Apri Impostazioni → API keys → Nuova chiave
3. Salvala come QLARA_API_KEY nelle variabili d'ambiente

Apri la dashboard Qlara

A chi è rivolta questa documentazione?

• Sviluppatori e team tecnici che integrano la messaggistica nelle loro applicazioni
• Project manager e account manager che vogliono capire le funzionalità disponibili
• Team di supporto che assistono i clienti nell'integrazione API

URL Base

Tutti gli endpoint API sono serviti sotto:

https://api.qlara.ai/api

Autenticazione

Ogni richiesta deve includere l'autenticazione tramite uno di questi metodi:

• API Key (consigliato): header X-Api-Key: LA_TUA_API_KEY
• Basic Auth: header Authorization: Basic base64(username:password)

Per i dettagli vedi la guida all'autenticazione.

Verifica che la tua API key funzioni elencando i tuoi mittenti SMS con GET /partner-gateway/v1/sms/senders, una chiamata che non richiede parametri — scegli il tuo linguaggio preferito:

cURL

curl -H "X-Api-Key: LA_TUA_API_KEY" \
https://api.qlara.ai/api/partner-gateway/v1/sms/senders

Node.js

const res = await fetch(
'https://api.qlara.ai/api/partner-gateway/v1/sms/senders',
{ headers: { 'X-Api-Key': process.env.QLARA_API_KEY } }
);
const data = await res.json();
console.log(res.status, data);

Python

import os, requests

res = requests.get(
  "https://api.qlara.ai/api/partner-gateway/v1/sms/senders",
  headers={"X-Api-Key": os.environ["QLARA_API_KEY"]},
)
print(res.status_code, res.json())

Un 200 con l'elenco dei tuoi mittenti significa che la chiave funziona. Un 401 con {"error": "Invalid API Key"} significa che la chiave è mancante o errata, oppure non è abilitata agli SMS.

Suggerimento

Mantieni la tua API key segreta. Non esporla nel codice lato client o in repository pubblici. In produzione, ruota le chiavi regolarmente e conservale in un secrets manager.

Canali disponibili

SMS

Il canale più diffuso e universale. Funziona su qualsiasi cellulare, anche non smartphone. Ideale per notifiche transazionali, OTP e comunicazioni urgenti.

• Universal: formato moderno e consigliato — un messaggio per richiesta con supporto placeholder
• Legacy: formato retro-compatibile — supporta più destinatari nella stessa richiesta

RCS (Rich Communication Services)

L'evoluzione degli SMS. Invia messaggi ricchi con immagini, video, bottoni interattivi e caroselli. Richiede un dispositivo compatibile RCS.

• Tipi di messaggio: text, card (con media e bottoni), carousel (card scrollabili)
• Suggerimenti interattivi (reply, apertura URL, chiamata, posizione, calendario)
• Fallback automatico a WhatsApp e/o SMS se il destinatario non supporta RCS

WhatsApp Business

Il canale di messaggistica più usato al mondo. Invia messaggi tramite template approvati da Meta o contenuti free-form (entro la finestra di 24h).

• Tipi di contenuto: text, image, video, audio, document, location, sticker, reaction
• Template con bottoni, header media e link tracciati
• Fallback automatico a RCS e/o SMS

Invia il tuo primo messaggio

Dopo l'autenticazione basta una POST per inviare. Ecco il caso più semplice — un SMS:

cURL

curl -X POST https://api.qlara.ai/api/partner-gateway/v1/sms/messages \
-H "X-Api-Key: LA_TUA_API_KEY" \
-H "Content-Type: application/json" \
-d '{
  "destination": "+393334445566",
  "sender": "Qlara",
  "body": "Ciao da Qlara Platform!",
  "messageId": "msg-sms-001"
}'

Node.js

const res = await fetch(
'https://api.qlara.ai/api/partner-gateway/v1/sms/messages',
{
  method: 'POST',
  headers: {
    'X-Api-Key': process.env.QLARA_API_KEY,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    destination: '+393334445566',
    sender: 'Qlara',
    body: 'Ciao da Qlara Platform!',
    messageId: 'msg-sms-001',
  }),
}
);
const { messageId } = await res.json();
console.log('Inviato:', messageId);

Python

import os, requests

res = requests.post(
  "https://api.qlara.ai/api/partner-gateway/v1/sms/messages",
  headers={"X-Api-Key": os.environ["QLARA_API_KEY"]},
  json={
      "destination": "+393334445566",
      "sender": "Qlara",
      "body": "Ciao da Qlara Platform!",
      "messageId": "msg-sms-001",
  },
)
print("Inviato:", res.json()["messageId"])

sender deve essere uno dei mittenti restituiti dalla verifica qui sopra, altrimenti l'API risponde 403. messageId è il tuo identificativo del messaggio: conservalo, è il customerMessageId con cui ne segui la consegna.

L'API risponde 202 Accepted:

{
  "messageId": "msg-sms-001",
  "simulation": false,
  "results": {
    "sms": {
      "accepted": true,
      "unicode": false,
      "parts": 1,
      "reasons": []
    }
  }
}

Se la piattaforma di messaggistica rifiuta il messaggio, la risposta è invece 422 con i motivi.

Catena di fallback

Il sistema supporta il fallback automatico. Se il canale primario non riesce a consegnare, il sistema prova il successivo:

Come funziona

Concetti fondamentali

Concetto	Descrizione
Canali	SMS, RCS e WhatsApp. Ogni canale ha il proprio endpoint di invio e gestione dei template.
Contatti e Liste	La tua rubrica. Organizza i contatti in liste per il targeting delle campagne.
Campagne	Invii massivi che spediscono un messaggio a una lista di contatti su una pianificazione.
Webhook	Callback HTTPS per notifiche real-time su consegna, lettura e messaggi in arrivo.
Template	Template approvati per RCS e WhatsApp con placeholder ed elementi interattivi.
Esportazioni	Esportazioni dati asincrone (contatti, report di consegna) con link per il download.
Abbonamento	Il tuo piano e il saldo crediti.
Profili Social	Account social collegati (Facebook, Instagram, LinkedIn, Google, TikTok) al tuo account.

Prossimi passi

• Autenticazione — Scopri API Key, Basic Auth e IP Whitelist.
• Quick Start — Invia il primo messaggio in 3 minuti.
• Canali di Messaggistica — Confronta SMS, RCS e WhatsApp.
• Gestione Campagne — Crea e pianifica campagne massive.
• Contatti e Liste — Organizza il tuo pubblico.
• Webhook — Configura le notifiche di consegna real-time.
• FAQ — Domande e risposte frequenti.
• Riferimento API — Esplora tutti gli endpoint.
• Collezioni Postman — Scarica le collezioni pronte per il testing.