API Endpoints

Documentazione degli endpoint REST di Askme Chat, riallineata ai path presenti nella specifica OpenAPI

Base URL

Per gli esempi seguenti usiamo l'URL pubblico:

https://chat.askme.it

Autenticazione

Gli endpoint autenticati richiedono il token API nell'header:

X-AskmeToken: {api_token}

Gli endpoint pubblici (/public/api/...) non richiedono autenticazione.

---

Chat e conversazioni

Lista chat

GET /api/chat/

Recupera l'elenco delle chat con filtri, ordinamento e supporto sia a paginazione classica sia stile Spring.

Parametri query più usati

Campo	Tipo	Descrizione
active	boolean	Filtra le chat attive
categories	array(int64)	Filtra per categoria
assignedUsers	array(int64)	Filtra per operatori assegnati
users	array(int64)	Filtra per utenti coinvolti
channelCode	string	Filtra per canale (WIDGET, TELEGRAM, WHATSAPP, ...)
query	string	Ricerca libera
rating	integer	Filtra per rating
tags	array(int64)	Filtra per tag
startingPage	string	Filtra per pagina di avvio chat
tsInsFrom / tsInsTo	string (date-time)	Intervallo data creazione
includeContent	boolean	Include il contenuto nei risultati esportabili
loadTags	boolean	Carica i tag nella risposta
page / size	integer	Paginazione standard
pageNumber / pageSize	integer	Variante alternativa di paginazione
offset	integer	Offset di partenza
sort	array(string)	Ordinamento, es. sort=tsIns,desc

Esempio

curl -X GET "https://chat.askme.it/api/chat/?active=true&categories=1&categories=3&page=0&size=20&sort=tsIns,desc" \
  -H "X-AskmeToken: {api_token}"

Risposta (200 OK)

{
  "content": [
    {
      "idChat": 123,
      "name": "Supporto ordine #8451",
      "jid": "customer_123@chat",
      "active": true,
      "closed": false,
      "language": "it",
      "rating": 5,
      "startingPage": "/supporto",
      "category": {
        "idChatCategory": 1,
        "title": "Supporto"
      },
      "channel": {
        "code": "WIDGET",
        "description": "Widget"
      },
      "tsIns": "2026-03-31T09:12:00Z"
    }
  ],
  "totalElements": 1,
  "number": 0,
  "size": 20,
  "totalPages": 1
}

Dettaglio chat

GET /api/chat/{idChat}

Restituisce il dettaglio completo di una conversazione.

Parametro	In	Tipo	Descrizione
idChat	path	integer (int64)	ID univoco della chat

Esempio

curl -X GET "https://chat.askme.it/api/chat/123" \
  -H "X-AskmeToken: {api_token}"

Risposta (200 OK)

{
  "idChat": 123,
  "name": "Supporto ordine #8451",
  "jid": "customer_123@chat",
  "active": true,
  "closed": false,
  "muted": false,
  "language": "it",
  "startingPage": "/supporto",
  "status": "A",
  "category": {
    "idChatCategory": 1,
    "title": "Supporto"
  },
  "assignedUser": {
    "idUser": 456,
    "username": "operator1"
  },
  "tags": [
    {
      "idTag": 3,
      "title": "ordine"
    }
  ]
}

Storico chat

GET /api/chat/history/{idChat}

Recupera cronologia completa, messaggi ed eventi.

curl -X GET "https://chat.askme.it/api/chat/history/123" \
  -H "X-AskmeToken: {api_token}"

Operazioni principali su chat

Endpoint	Metodo	Descrizione
/api/chat/join	POST	Presa in carico della chat da parte di un operatore
/api/chat/assign	PUT	Assegna o riassegna la chat a un operatore
/api/chat/change-category	PUT	Cambia categoria della chat
/api/chat/change-priority/{idChat}/{priority}	PUT	Aggiorna la priorità
/api/chat/rename	PUT	Rinomina la chat
/api/chat/update	POST	Aggiorna i dati della chat
/api/chat/update-status	POST	Aggiorna lo stato di una o più chat
/api/chat/mute/{idChat}	PUT	Disattiva le notifiche della chat
/api/chat/unmute/{idChat}	PUT	Riattiva le notifiche
/api/chat/tags/{idChat}	POST	Aggiorna i tag associati
/api/chat/close/{idChat}	PUT	Chiude la chat
/api/chat/{idChat}	DELETE	Cancellazione logica
/api/chat/erase/{idChat}	DELETE	Cancellazione definitiva

Esempio: presa in carico

curl -X POST "https://chat.askme.it/api/chat/join" \
  -H "X-AskmeToken: {api_token}" \
  -H "Content-Type: application/json" \
  -d '{
    "idChat": 123,
    "idUser": 456
  }'

Risposta (200 OK)

{
  "idUser": 456,
  "username": "operator1",
  "nickname": "Mario"
}

Esempio: cambio categoria

curl -X PUT "https://chat.askme.it/api/chat/change-category" \
  -H "X-AskmeToken: {api_token}" \
  -H "Content-Type: application/json" \
  -d '{
    "idChat": 123,
    "idCategory": 2,
    "language": "it",
    "notes": "Escalation verso vendite"
  }'

Esempio: aggiornamento tag

curl -X POST "https://chat.askme.it/api/chat/tags/123" \
  -H "X-AskmeToken: {api_token}" \
  -H "Content-Type: application/json" \
  -d '[1, 3, 5]'

Pending, joined ed export

Endpoint	Metodo	Descrizione
/api/chat/pending/{priority}	GET	Chat pendenti per priorità
/api/chat/pending/connections/{priority}	GET	Connessioni pendenti
/api/chat/pending/categories/	GET	Pending aggregate per categoria
/api/chat/pending/operator/{idUser}	GET	Pending di un operatore
/api/chat/pending/operator/{idUser}/top/{top}	GET	Prime N pending
/api/chat/pending/operator/{idUser}/count	GET	Conteggio pending
/api/chat/joined/{idUser}	GET	Chat già prese in carico
/api/chat/export/{idChat}	GET	Download trascrizione singola
/api/chat/exportChats	GET	Export CSV delle chat filtrate
/api/chat/exportChatsWithContent	GET	Export CSV con contenuto messaggi

---

Categorie chat

La specifica usa il prefisso corretto:

/api/chat/categories/

e non /api/chat-categories/.

Lista categorie

GET /api/chat/categories/

Parametri query

Campo	Tipo	Descrizione
language	string	Lingua della risposta
minimal	boolean	Versione minimale
counters	boolean	Include contatori
tenantCode	string	Tenant specifico
waitingTimeElapsed	integer	Tempo di attesa trascorso
waitingTimeThreshold	integer	Soglia alert

CRUD categorie

Endpoint	Metodo	Descrizione
/api/chat/categories/	GET	Elenco categorie
/api/chat/categories/{idChatCategory}	GET	Dettaglio categoria
/api/chat/categories/	POST	Creazione
/api/chat/categories/	PUT	Aggiornamento
/api/chat/categories/{idChatCategory}	DELETE	Eliminazione

Esempio: creazione categoria

curl -X POST "https://chat.askme.it/api/chat/categories/" \
  -H "X-AskmeToken: {api_token}" \
  -H "Content-Type: application/json" \
  -d '{
    "code": "sales",
    "title": "Vendite",
    "description": "Categoria commerciale",
    "active": true,
    "opened": true,
    "priority": 2,
    "color": "#00cc66",
    "lang": "it"
  }'

Risposta (200 OK): 2

---

Utenti e operatori

Endpoint utenti verificati

Endpoint	Metodo	Descrizione
/api/users/?username={username}	GET	Cerca un utente per username
/api/users/{idUser}	GET	Dettaglio utente per ID
/api/users/	POST	Crea utente
/api/users/	PUT	Aggiorna utente
/api/users/?username={username}	DELETE	Elimina per username
/api/users/{idUser}	DELETE	Elimina per ID
/api/users/change-nickname	POST	Cambia nickname
/api/users/operators	GET	Lista operatori
/api/users/operators/online/{idChatCategory}	GET	Operatori online per categoria
/api/users/online/{idUser}	PUT	Imposta stato online
/api/users/away/{idUser}	PUT	Imposta stato away
/api/users/busy/{idUser}	PUT	Imposta stato busy
/api/users/offline/{idUser}	PUT	Imposta stato offline
/api/users/update-language	PUT	Aggiorna lingua operatore
/api/users/update-settings	PUT	Aggiorna impostazioni
/api/users/validate-password	POST	Valida password

Esempio: creazione utente

curl -X POST "https://chat.askme.it/api/users/" \
  -H "X-AskmeToken: {api_token}" \
  -H "Content-Type: application/json" \
  -d '{
    "username": "nuovo_operatore",
    "firstName": "Luca",
    "lastName": "Bianchi",
    "email": "[email protected]",
    "password": "securePassword123"
  }'

Risposta (200 OK): 456

Account autenticato

Endpoint	Metodo	Descrizione
/api/account	GET	Account autenticato
/api/authenticate	GET	Verifica autenticazione
/api/change-password	POST	Cambio password
/api/recover-password	POST	Avvia recupero password
/api/reset-password	POST	Reset con token
/api/register	POST	Registrazione tenant
/api/availability	GET	Disponibilità tenant
/api/username-availability	GET	Disponibilità username
/api/info	GET	Informazioni applicazione

---

Chatbot, workflow e intent

CRUD chatbot

Endpoint	Metodo	Descrizione
/api/bots/	GET	Elenco chatbot
/api/bots/{idChatBot}	GET	Dettaglio chatbot
/api/bots/	POST	Crea chatbot
/api/bots/	PUT	Aggiorna chatbot
/api/bots/{idChatBot}	DELETE	Elimina chatbot
/api/bots/clone/{idChatBot}	PUT	Duplica chatbot
/api/bots/name	GET	Nome e stato bot attivo

Esempio: creazione chatbot

curl -X POST "https://chat.askme.it/api/bots/" \
  -H "X-AskmeToken: {api_token}" \
  -H "Content-Type: application/json" \
  -d '{
    "code": "sales-bot",
    "name": "Bot Vendite",
    "language": "it",
    "active": true
  }'

Workflow del chatbot

Endpoint	Metodo	Descrizione
/api/bots/structure/{idChatBot}	GET	Recupera struttura workflow
/api/bots/structure/{idChatBot}	PUT	Aggiorna struttura workflow
/api/bots/actions	GET	Azioni disponibili
/api/bots/conditions	GET	Condizioni disponibili

Esempio: lettura workflow

curl -X GET "https://chat.askme.it/api/bots/structure/12" \
  -H "X-AskmeToken: {api_token}"

Risposta (200 OK)

{
  "idChatBot": 12,
  "rootNodeId": 1,
  "nodes": {
    "1": {
      "idNode": 1,
      "title": "Benvenuto",
      "message": "Ciao, come posso aiutarti?"
    }
  }
}

Intent

Endpoint	Metodo	Descrizione
/api/bots/intents/all	GET	Tutti gli intent
/api/bots/{idChatBot}/intents/	GET	Intent del bot
/api/bots/{idChatBot}/intents/	POST	Crea intent
/api/bots/{idChatBot}/intents/	PUT	Aggiorna intent
/api/bots/{idChatBot}/intents/multiple/	POST	Creazione multipla
/api/bots/intents/{idIntent}	GET	Dettaglio intent
/api/bots/intents/{idIntent}	DELETE	Elimina intent
/api/bots/intents/{idIntent}/utterance/	POST	Aggiunge utterance

Esempio: creazione intent

curl -X POST "https://chat.askme.it/api/bots/12/intents/" \
  -H "X-AskmeToken: {api_token}" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "saluto",
    "description": "L'utente saluta",
    "active": true,
    "closeChat": false,
    "closeWidget": false,
    "reactivateChat": false
  }'

Test, training e media

Endpoint	Metodo	Descrizione
/api/bots/train/{idChatBot}	POST	Addestra il bot
/api/bots/test/{idChatBot}?query=...	GET	Testa una risposta
/api/bots/test-widget/{idChatBot}	GET	Configurazione widget di test
/api/bots/avatar	POST	Upload avatar (multipart/form-data)
/api/bots/avatar/{idChatBot}	DELETE	Rimuove avatar
/api/bots/upload-media	POST	Upload media per messaggi bot

Esempio: test risposta

curl -X GET "https://chat.askme.it/api/bots/test/12?query=ciao" \
  -H "X-AskmeToken: {api_token}"

---

Askme AI

Livello interno legacy

Il gruppo di endpoint /api/ai/... è un livello interno legacy di Askme Chat, mantenuto per compatibilità con integrazioni esistenti. Per nuove integrazioni con le funzionalità di intelligenza artificiale (agenti, chat con RAG, knowledge base, analisi) utilizzare le API ufficiali di Askme AI (/api/v2): vedere Panoramica API di Askme AI ed Endpoint di Askme AI.

---

Widget

La specifica usa il prefisso corretto:

/api/widget/

e non /api/widgets/.

Endpoint	Metodo	Descrizione
/api/widget/	GET	Elenco widget
/api/widget/{idChatWidget}	GET	Dettaglio widget
/api/widget/	POST	Crea widget
/api/widget/	PUT	Aggiorna widget
/api/widget/{idChatWidget}	DELETE	Elimina widget
/api/widget/clone/{idChatWidget}	POST	Duplica widget
/api/widget/enable?idWidget={id}	PUT	Abilita widget
/api/widget/disable?idWidget={id}	PUT	Disabilita widget
/api/widget/upload-logo	POST	Upload logo
/api/widget/download-language-labels	GET	Scarica labels
/api/widget/export-language-labels	POST	Export labels
/api/widget/import-language-labels	POST	Import labels

Esempio: creazione widget

curl -X POST "https://chat.askme.it/api/widget/" \
  -H "X-AskmeToken: {api_token}" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Widget Supporto",
    "description": "Widget sito principale",
    "active": true,
    "configuration": "{}",
    "customCss": ""
  }'

---

API keys

La specifica usa il gruppo:

/api/keys/

e non /api/api-keys/.

Endpoint	Metodo	Descrizione
/api/keys/	GET	Elenco API key
/api/keys/{idApiKey}	GET	Dettaglio API key
/api/keys/	POST	Crea API key
/api/keys/	PUT	Aggiorna API key
/api/keys/enable/{idApiKey}	PUT	Abilita API key
/api/keys/disable/{idApiKey}	PUT	Disabilita API key
/api/keys/{idApiKey}	DELETE	Elimina API key

Esempio

curl -X POST "https://chat.askme.it/api/keys/" \
  -H "X-AskmeToken: {api_token}" \
  -H "Content-Type: application/json" \
  -d '{
    "description": "Token integrazione CRM",
    "active": true,
    "validFrom": "2026-03-31T00:00:00Z",
    "validTo": "2026-12-31T23:59:59Z"
  }'

---

Altri gruppi funzionali

Configurazioni operative

Endpoint	Metodo	Descrizione
/api/configuration/	GET, POST, PUT	Configurazione generale
/api/configuration/app	GET	Config app
/api/configuration/export	GET	Export configurazione
/api/configuration/import	POST	Import configurazione
/api/configuration/update-business-hours	PUT	Aggiorna orari
/api/configuration/test-email	POST	Test email
/api/configuration/complete-tutorial	POST	Marca tutorial completato

Campagne, tag e quick replies

Endpoint	Metodo	Descrizione
/api/campaigns/	GET, POST, PUT	CRUD campagne
/api/campaigns/{idCampaign}	GET, DELETE	Dettaglio / elimina campagna
/api/campaigns/enable/{idCampaign}	PUT	Abilita campagna
/api/campaigns/disable/{idCampaign}	PUT	Disabilita campagna
/api/campaigns/clone/{idCampaign}	PUT	Duplica campagna
/api/tags/	GET, POST, PUT	CRUD tag
/api/tags/{idTag}	DELETE	Elimina tag
/api/quick-replies/	GET, POST, PUT	CRUD quick replies
/api/quick-replies/{idQuickReply}	DELETE	Elimina quick reply
/api/quick-replies/all/{idUser}	GET	Tutte le quick replies di un utente

Blacklist, team e gruppi

Endpoint	Metodo	Descrizione
/api/blacklist/	GET, POST, PUT	CRUD blacklist
/api/blacklist/{idAddress}	GET, DELETE	Dettaglio / elimina
/api/blacklist/enable/{idAddress}	PUT	Abilita elemento blacklist
/api/blacklist/disable/{idAddress}	PUT	Disabilita elemento blacklist
/api/teams/	GET, POST, PUT	CRUD team
/api/teams/{idTeam}	GET, DELETE	Dettaglio / elimina team
/api/teams/users/{idTeam}	GET	Utenti del team
/api/groups/	GET, POST, PUT	CRUD gruppi
/api/groups/{idGroup}	GET, DELETE	Dettaglio / elimina gruppo
/api/groups/users/{idGroup}	GET	Utenti del gruppo
/api/groups/roles	GET	Ruoli disponibili

Knowledge base e template

Endpoint	Metodo	Descrizione
/api/knowledge-base/	GET, POST, PUT	CRUD articoli KB
/api/knowledge-base/{idKnowledgeBase}	GET, DELETE	Dettaglio / elimina articolo
/api/templates/	GET, POST, PUT	Template email
/api/templates/{type}	GET	Template per tipo

Integrazioni

Endpoint	Metodo	Descrizione
/api/integrations/askmedesk	GET, POST	Integrazione Askme Desk
/api/integrations/chat-widget	GET	Integrazione widget
/api/integrations/google-analytics	GET, POST	Google Analytics
/api/integrations/google-cloud	GET, POST	Google Cloud
/api/integrations/google-maps	GET, POST	Google Maps
/api/integrations/telegram	GET, POST	Telegram
/api/integrations/whatsapp	GET, POST	WhatsApp

Analytics

Endpoint	Metodo	Descrizione
/api/analytics/started-chats-category-counter	GET	Chat avviate per categoria
/api/analytics/started-chats-timeline	GET	Timeline chat avviate
/api/analytics/started-chats-slots	GET	Chat per fascia oraria
/api/analytics/abandoned-chats-counters	GET	Chat abbandonate
/api/analytics/closed-chats-counters	GET	Chat chiuse
/api/analytics/average-waiting-time-timeline	GET	Tempo medio attesa
/api/analytics/average-closing-time-timeline	GET	Tempo medio chiusura
/api/analytics/average-abandoning-time-timeline	GET	Tempo medio abbandono
/api/analytics/closing-time-slots	GET	Tempo chiusura per fascia
/api/analytics/rating-counters	GET	Distribuzione rating
/api/analytics/browser-counters	GET	Browser usati
/api/analytics/languages-chats-counters	GET	Lingue chat
/api/analytics/charged-chats-operators	GET	Chat per operatore
/api/analytics/operators-metrics	GET	Metriche operatori
/api/analytics/tags-chats-counter	GET	Distribuzione tag
/api/analytics/required-chat-effort	GET	Effort richiesto
/api/analytics/real-time	GET	Dashboard real-time
/api/analytics/starting-pages	GET	Pagine di ingresso
/api/analytics/starting-pages-counters	GET	Contatori pagine ingresso

---

Endpoint pubblici del widget

Gli endpoint pubblici restano utili lato frontend/widget e non richiedono token. Nella documentazione attuale sono usati anche negli esempi e nei webhook.

Endpoint	Metodo	Descrizione
/public/api/widget	GET	Configurazione widget pubblico
/public/api/chat/categories	GET	Categorie esposte al widget
/public/api/chat/queue-position/	GET	Posizione in coda
/public/api/chat/rating/	POST	Invio rating chat
/public/api/chat/transcription/	GET	Invio trascrizione via email
/public/api/chat/contact-request-email/	GET	Richiesta contatto email
/public/api/chat/contact-request-phone/	GET	Richiesta contatto telefonico
/public/api/chat/add-navigation-page	POST	Tracciamento navigazione utente
/public/api/chat/input/validate	POST	Validazione input
/public/api/attachments/upload	POST	Upload allegato
/public/api/attachments/	GET	Info allegato
/public/api/attachments/download	GET	Download allegato
/public/api/attachments/image	GET	Anteprima allegato
/public/api/attachments/{uuid}	DELETE	Elimina allegato
/public/api/bot/avatar	GET	Avatar pubblico bot
/public/api/bot/media	GET	Media pubblico bot
/public/api/health	GET	Health check
/public/api/version	GET	Versione applicazione

---

WebSocket

La messaggistica realtime usa WebSocket/STOMP.

ws://chat.askme.it/websocket

Header di connessione

Header	Descrizione
ASKMECHAT_WS_USER	Username
ASKMECHAT_WS_PASSWORD	Password

Prefissi

Prefisso	Uso
/app	Invio verso server
/topic	Sottoscrizione topic

---

Gestione errori

Codice	Descrizione
200	Richiesta completata con successo
201	Risorsa creata
204	Completato senza contenuto
400	Parametri non validi
401	Token non valido o mancante
403	Permessi insufficienti
404	Risorsa non trovata
429	Rate limit superato
500	Errore interno del server

Note operative

• Il token X-AskmeToken va inviato in tutte le chiamate autenticate.
• Le date in query sono esposte come date-time ISO 8601.
• Gli array in query string vengono passati come parametri multipli, per esempio ?categories=1&categories=3.
• Per gli export /api/chat/exportChats e /api/chat/exportChatsWithContent i filtri supportati sono gli stessi della lista chat.