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://lora-api.agiletelecom.com/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 chiamando l'endpoint /messages/status — scegli il tuo linguaggio preferito:

cURL

curl -H "X-Api-Key: LA_TUA_API_KEY" \
https://lora-api.agiletelecom.com/api/partner-gateway/v1/messages/status

Node.js

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

Python

import os, requests

res = requests.get(
  "https://lora-api.agiletelecom.com/api/partner-gateway/v1/messages/status",
  headers={"X-Api-Key": os.environ["QLARA_API_KEY"]},
)
print(res.json())

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://lora-api.agiletelecom.com/api/partner-gateway/v1/sms/messages \
-H "X-Api-Key: LA_TUA_API_KEY" \
-H "Content-Type: application/json" \
-d '{
  "to": "+393334445566",
  "from": "Qlara",
  "text": "Ciao da Qlara Platform!"
}'

Node.js

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

Python

import os, requests

res = requests.post(
  "https://lora-api.agiletelecom.com/api/partner-gateway/v1/sms/messages",
  headers={"X-Api-Key": os.environ["QLARA_API_KEY"]},
  json={
      "to": "+393334445566",
      "from": "Qlara",
      "text": "Ciao da Qlara Platform!",
  },
)
print("Inviato:", res.json()["messageId"])

Una risposta di successo è così:

{
  "accepted": true,
  "messageId": "e76614d1-58c0-4f65-8a77-c1f6ce5f9d2a",
  "channel": "sms"
}

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, la quota contatti 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.