Skip to main content

UC-009 — Conversazione Bidirezionale

CampoValore
IDUC-009
ObiettivoGestire conversazioni bidirezionali con i clienti
CanaleWhatsApp / RCS
Complessità⭐⭐⭐ Avanzato
Tempo stimato20 minuti
API coinvolteGET /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:

:::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​

ParametroTipoDescrizione
channelIdsstringID canali separati da virgola (es. WHATSAPP-123,RCS-456)
dateFromstringData ISO per filtrare conversazioni aggiornate dopo questa data
orderBystringOrdinamento con prefisso +/- (es. -lastMessageDate)
unreadOnlybooleanSe 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​

AspectDetail
Action completedInbound message received, reply sent, conversation archived
Channel usedWhatsApp / RCS
Delivery confirmationVia webhook (statusCode: 3) within 5-60 sec

Common errors​

ProblemProbable causeSolution
HTTP 401Missing or invalid API KeyCheck X-Api-Key header
accepted: falseInsufficient credit or invalid numberCheck credit; verify E.164 format
HTTP 400 — Invalid chatIdConversation not found or already archivedVerify the chatId exists and is not archived
Reply rejected — Window expiredWhatsApp 24h window has closedCheck whatsappWindowExpire; use a Meta-approved template instead
No INBOUND webhook receivedWebhook not configured or endpoint unreachableVerify webhook registration with GET /webhooks/delivery-status

Prossimi passi​