UC-009 — Conversazione Bidirezionale

Campo	Valore
ID	UC-009
Obiettivo	Gestire conversazioni bidirezionali con i clienti
Canale	WhatsApp / RCS
Complessità	⭐⭐⭐ Avanzato
Tempo stimato	20 minuti
API coinvolte	GET /api/partner-gateway/v1/inbox/conversations, GET /{chatId}/messages, POST /conversations/reply, PATCH /{chatId}/archive, PATCH /{chatId}/read

Scenari reali

• TechStore — Customer support chat: Un cliente scrive su WhatsApp per chiedere informazioni su un ordine; il sistema riceve il messaggio, lo assegna a un operatore e risponde con lo stato della spedizione.
• Studio Dentistico Bianchi — Conferma prenotazione con risposta: Dopo l'invio di un promemoria appuntamento, il paziente conferma o richiede di spostare la visita rispondendo al messaggio.
• FashionOutlet — Raccolta feedback post-vendita: Un sondaggio post-acquisto chiede al cliente di rispondere con un voto da 1 a 5; il sistema raccoglie e cataloga le risposte automaticamente.

Prerequisites

Before you begin, make sure you have:

• Active API Key → How to get one
• Sufficient credit → Check in the Qlara Dashboard
• Webhook configured + WhatsApp number or RCS agent

:::tip Test without costs Add "simulation": true in the request body to validate the flow without actually sending messages and without consuming credit. :::

Flusso di interazione

Guida passo-passo

Step 1 — Configurare il webhook per messaggi inbound

Prima di tutto, registra un webhook per ricevere i messaggi in arrivo. Vedi la guida Webhooks per la configurazione completa.

curl -X POST "https://lora-api.agiletelecom.com/api/partner-gateway/v1/webhooks/delivery-status" \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "callbackUrl": "https://api.tuaazienda.it/webhook/inbound"
  }'

Step 2 — Ricevere un messaggio inbound

Quando un cliente invia un messaggio, il tuo endpoint riceve un payload come questo.

Inbound TEXT:

{
  "channel": "WHATSAPP",
  "eventType": "INBOUND",
  "messageId": "wamid.HBgNMzkzNDcxNDg4NDg5FQIAEhgUM0EB",
  "source": "+393471234567",
  "destination": "+393209998877",
  "receivedDate": "2026-04-09T09:15:22.041Z",
  "messageType": "TEXT",
  "text": "Buongiorno, vorrei sapere lo stato del mio ordine ORD-2026-1584"
}

Inbound IMAGE:

{
  "channel": "WHATSAPP",
  "eventType": "INBOUND",
  "source": "+393471234567",
  "destination": "+393209998877",
  "receivedDate": "2026-04-09T09:16:05.123Z",
  "messageType": "IMAGE",
  "mediaKey": "b394ab72/efd4987c/39b4879f6fed01f0d622453be1488c93"
}

:::tip Download media Per scaricare un file media allegato, usa GET /api/files/{mediaKey}?expireMinutes=180. La risposta contiene un URL pre-firmato temporaneo. :::

Step 3 — Elencare le conversazioni

Recupera tutte le conversazioni attive, filtrando per messaggi non letti:

curl -X GET "https://lora-api.agiletelecom.com/api/partner-gateway/v1/inbox/conversations?unreadOnly=true" \
  -H "X-Api-Key: YOUR_API_KEY"

Risposta:

[
  {
    "id": 1042,
    "hasUnreadMessages": true,
    "userName": "Marco Bianchi",
    "phoneNumber": "+393471234567",
    "unreadCount": 2,
    "lastMessageText": "Buongiorno, vorrei sapere lo stato del mio ordine ORD-2026-1584",
    "lastMessageDate": "2026-04-09T09:15:22.041Z",
    "socialMedia": "WHATSAPP",
    "companyProfileName": "TechStore Italia",
    "companyPhoneNumber": "+393209998877",
    "whatsappWindowExpire": "2026-04-10T09:15:22.041Z"
  }
]

Step 4 — Ottenere i messaggi della conversazione

Recupera il thread completo di una conversazione:

curl -X GET "https://lora-api.agiletelecom.com/api/partner-gateway/v1/inbox/conversations/1042/messages" \
  -H "X-Api-Key: YOUR_API_KEY"

Risposta:

{
  "profile": {
    "name": "Marco Bianchi",
    "phoneNumber": "+393471234567"
  },
  "messages": [
    {
      "id": 5001,
      "text": "Buongiorno, vorrei sapere lo stato del mio ordine ORD-2026-1584",
      "isRead": false,
      "isUserReply": true,
      "createdAt": "2026-04-09T09:15:22.041Z",
      "attachments": [],
      "status": "DELIVERED"
    }
  ]
}

Step 5 — Rispondere alla conversazione

Invia una risposta all'interno della conversazione esistente:

curl -X POST "https://lora-api.agiletelecom.com/api/partner-gateway/v1/inbox/conversations/reply" \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "chatId": 1042,
    "message": "Buongiorno Marco! Il suo ordine ORD-2026-1584 e'\'' in fase di spedizione. Ricevera'\'' il tracking entro oggi pomeriggio."
  }'

Risposta: 202 Accepted

:::warning Finestra 24 ore Per WhatsApp, le risposte free-form sono possibili solo entro 24 ore dall'ultimo messaggio del cliente. Controlla il campo whatsappWindowExpire nella conversazione. Dopo la scadenza, usa un template approvato da Meta. Vedi la guida WhatsApp. :::

Step 6 — Segnare come letto e archiviare

Dopo aver gestito la richiesta, segna la conversazione come letta:

curl -X PATCH "https://lora-api.agiletelecom.com/api/partner-gateway/v1/inbox/conversations/1042/read" \
  -H "X-Api-Key: YOUR_API_KEY"

Risposta: 204 No Content

Quando la conversazione e' conclusa, archiviala:

curl -X PATCH "https://lora-api.agiletelecom.com/api/partner-gateway/v1/inbox/conversations/1042/archive" \
  -H "X-Api-Key: YOUR_API_KEY"

Risposta: 204 No Content

:::info Ripristino Una conversazione archiviata puo' essere ripristinata in qualsiasi momento con PATCH /conversations/{chatId}/unarchive. :::

Parametri di filtro conversazioni

Parametro	Tipo	Descrizione
channelIds	string	ID canali separati da virgola (es. WHATSAPP-123,RCS-456)
dateFrom	string	Data ISO per filtrare conversazioni aggiornate dopo questa data
orderBy	string	Ordinamento con prefisso +/- (es. -lastMessageDate)
unreadOnly	boolean	Se true, ritorna solo conversazioni con messaggi non letti

Paginazione messaggi

Per thread lunghi, usa i parametri idFrom e idTo:

curl -X GET "https://lora-api.agiletelecom.com/api/partner-gateway/v1/inbox/conversations/1042/messages?idFrom=5000&idTo=5050" \
  -H "X-Api-Key: YOUR_API_KEY"

Dietro le quinte

Quando un cliente invia un messaggio, il carrier (Meta per WhatsApp, Google per RCS) lo recapita alla piattaforma Qlara, che:

1. Crea o aggiorna la conversazione -- Se il contatto ha già' una conversazione aperta sullo stesso canale, il messaggio viene aggiunto al thread esistente. Altrimenti ne viene creata una nuova.
2. Notifica via webhook -- Il payload INBOUND viene inviato al tuo callback URL registrato. Il tuo server deve rispondere con 200 OK entro pochi secondi.
3. Gestione finestra -- Per WhatsApp, la piattaforma aggiorna automaticamente la scadenza della finestra 24h ad ogni messaggio ricevuto dal cliente.
4. Routing della risposta -- Quando invii un reply tramite POST /conversations/reply, la piattaforma instrada automaticamente il messaggio sullo stesso canale della conversazione originale.

Expected result

Aspect	Detail
Action completed	Inbound message received, reply sent, conversation archived
Channel used	WhatsApp / RCS
Delivery confirmation	Via webhook (statusCode: 3) within 5-60 sec

Common errors

Problem	Probable cause	Solution
HTTP 401	Missing or invalid API Key	Check X-Api-Key header
accepted: false	Insufficient credit or invalid number	Check credit; verify E.164 format
HTTP 400 — Invalid chatId	Conversation not found or already archived	Verify the chatId exists and is not archived
Reply rejected — Window expired	WhatsApp 24h window has closed	Check whatsappWindowExpire; use a Meta-approved template instead
No INBOUND webhook received	Webhook not configured or endpoint unreachable	Verify webhook registration with GET /webhooks/delivery-status

Prossimi passi

• Guida Webhooks -- Configurazione completa dei webhook
• WhatsApp API -- Invio messaggi e template WhatsApp
• RCS API -- Invio messaggi rich con card e carousel
• UC-013: WhatsApp Template Workflow -- Quando la finestra 24h scade, usa i template