Riferimento API

Crea integrazioni personalizzate con l'API REST di Asyntai

Piano a pagamento richiesto: L'accesso API è disponibile nei piani Starter, Standard e Pro. Visualizza i prezzi

Panoramica

The Asyntai API allows you to integrate AI-powered customer support into any application. Send messages and receive intelligent responses grounded in your website content and knowledge base.

Autenticazione

All API requests require authentication using your API key. You can get your API key from the API Settings page.

Includi la tua chiave API nelle richieste utilizzando uno di questi metodi:

Header Authorization (consigliato): Authorization: Bearer YOUR_API_KEY
Header X-API-Key: X-API-Key: YOUR_API_KEY

Mantieni segreta la tua chiave API. Chiunque abbia la tua chiave può accedere al tuo account tramite l'API. Non esporla mai nel codice lato client.

URL di base

https://asyntai.com/api/v1/

Endpoint

POST /chat/

Invia un messaggio e ricevi una risposta generata dall'IA.

Corpo della richiesta

{
  "message": "What are your business hours?",
  "session_id": "user_123",      // optional
  "website_id": 1                 // optional
}

Parametro	Tipo	Obbligatorio	Descrizione
`message`	string	Sì	Il messaggio dell'utente da inviare all'IA
`session_id`	string	No	Identificativo univoco per la conversazione. Usa lo stesso session_id per mantenere la cronologia della conversazione.
`website_id`	integer	No	ID sito web specifico. Se non fornito, utilizza il tuo sito web principale.

Risposta

{
  "success": true,
  "response": "Our business hours are Monday-Friday, 9 AM to 5 PM EST.",
  "session_id": "user_123"
}

Esempio (cURL)

curl -X POST https://asyntai.com/api/v1/chat/ \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"message": "What are your business hours?", "session_id": "user_123"}'

Esempio (Python)

import requests

response = requests.post(
    "https://asyntai.com/api/v1/chat/",
    headers={
        "Authorization": "Bearer YOUR_API_KEY",
        "Content-Type": "application/json"
    },
    json={
        "message": "What are your business hours?",
        "session_id": "user_123"
    }
)

data = response.json()
print(data["response"])

Esempio (JavaScript)

const response = await fetch("https://asyntai.com/api/v1/chat/", {
  method: "POST",
  headers: {
    "Authorization": "Bearer YOUR_API_KEY",
    "Content-Type": "application/json"
  },
  body: JSON.stringify({
    message: "What are your business hours?",
    session_id: "user_123"
  })
});

const data = await response.json();
console.log(data.response);

GET /websites/

Elenca tutti i siti web associati al tuo account.

Risposta

{
  "success": true,
  "websites": [
    {
      "id": 1,
      "name": "My Website",
      "domain": "example.com",
      "is_primary": true
    }
  ]
}

Esempio (cURL)

curl https://asyntai.com/api/v1/websites/ \
  -H "Authorization: Bearer YOUR_API_KEY"

POST /websites/

Create a new AI agent. This does the same thing as adding a website in your dashboard: it makes the agent, reads your site, and writes the first draft of the AI instructions.

Use this to set up customers from your own software. You get back the widget ID and the code to put on the website.

Corpo della richiesta

Campo	Tipo	Descrizione
`domain`	string	Required. The website address, for example example.com
`name`	string	Optional. A display name for the agent. Useful when one website has several agents.
`crawl`	boolean	Optional, true by default. Set it to false to create the agent without reading the website. Nothing is crawled and no instructions are written.
`force`	boolean	Optional, false by default. Set it to true to add a website you already have. The copy is stored with a number after it.

Risposta

{
  "success": true,
  "website": {
    "id": 42,
    "domain": "example.com",
    "name": "Support agent",
    "widget_id": "asyntai_ab12cd34ef56",
    "is_primary": true,
    "crawl_started": true,
    "instructions_status": "generating",
    "job_id": "8f2c1e90-..."
  },
  "embed_code": "<script>...</script>"
}

Esempio (cURL)

curl -X POST https://asyntai.com/api/v1/websites/ \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"domain": "example.com", "name": "Support agent"}'

Reading a website takes a few minutes, so this call answers straight away. Check when the agent is ready with the next endpoint.

Errors

Code	Meaning
`403`	You have reached the number of websites your plan allows. The answer tells you the limit.
`409`	Your account already has this website. Send force as true to add it again.

GET /websites/{id}/

Get one website and see whether it is ready. Use this after you create an agent, to wait until the website has been read and the AI instructions are written.

Risposta

{
  "success": true,
  "website": {
    "id": 42,
    "domain": "example.com",
    "name": "Support agent",
    "widget_id": "asyntai_ab12cd34ef56",
    "is_primary": true,
    "created_at": "2026-08-11T09:12:00+00:00",
    "ready": true,
    "instructions": {
      "status": "completed",
      "has_instructions": true,
      "characters": 3421
    },
    "crawl": {
      "job_id": "8f2c1e90-...",
      "status": "completed",
      "pages_crawled": 47,
      "pages_found": 50,
      "max_pages": 50,
      "completed_at": "2026-08-11T09:15:31+00:00",
      "error": ""
    },
    "knowledge_items": 47
  },
  "embed_code": "<script>...</script>"
}

The ready field is true when nothing is still running. A crawl that failed also counts as ready, because it has finished. Look at the crawl status to see what happened.

Esempio (cURL)

curl https://asyntai.com/api/v1/websites/42/ \
  -H "Authorization: Bearer YOUR_API_KEY"

GET PATCH /websites/{id}/settings/

Read or change the chat widget settings for one website. These are the same settings you see on the Customize page: colours, the name of the assistant, the first message, lead capture, and everything else.

Reading the settings

A GET request returns every setting with its current value, plus a locked list. Locked shows the settings your plan cannot change, and which plans they need.

{
  "success": true,
  "settings": {
    "ai_support_name": "AI Assistant",
    "widget_color": "#0B0D10",
    "initial_message": "Hi, how can I help you?",
    "hide_branding": false,
    "...": "..."
  },
  "locked": {
    "hide_branding": ["pro", "enterprise"],
    "widget_style": ["pro", "enterprise"]
  }
}

Changing the settings

A PATCH request changes only the settings you send. Everything you leave out stays as it is.

curl -X PATCH https://asyntai.com/api/v1/websites/42/settings/ \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"ai_support_name": "Ava", "widget_color": "#0f172a", "use_emoji": true}'

{
  "success": true,
  "updated": ["ai_support_name", "use_emoji", "widget_color"],
  "settings": { "...": "..." },
  "locked": { "...": "..." }
}

Plans

Each setting needs its own plan, the same as in the dashboard. For example, hiding the Asyntai branding needs the Pro plan, and voice input needs Standard.

Plan needed	Impostazioni	Examples
Any paid plan	25	`widget_color`, `ai_support_name`, `initial_message`
Starter e superiori	22	`profile_picture`, `conversation_starters_enabled`
Standard e superiori	25	`speech_to_text_enabled`, `image_vision_enabled`, `escalation_enabled`
Pro	6	`hide_branding`, `widget_style`

If you send a setting your plan does not allow, the whole request is refused with code 403 and nothing is saved. The same happens if any value is wrong, for example a colour that is not a hex code. Your settings never end up half changed.

GET PUT /websites/{id}/instructions/

Read or replace the AI instructions for one website. These are the rules that tell the assistant who it is, what it may say, and what it must not say. They are the same instructions you edit in the dashboard.

Reading

{
  "success": true,
  "instructions": "You are the support agent for Acme Tools...",
  "characters": 1979,
  "version": 7,
  "mode": "instructions",
  "ask_questions": true,
  "generation_status": "completed",
  "being_edited_by": null
}

Replacing

A PUT request replaces the whole text, the same as saving in the dashboard. There is no append mode. To add a paragraph, read the instructions, add your text, then write it back.

curl -X PUT https://asyntai.com/api/v1/websites/42/instructions/ \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"instructions": "You are the support agent for Acme Tools...", "version": 7}'

Corpo della richiesta

Campo	Tipo	Descrizione
`instructions`	string	Required. The complete new text. It replaces everything that was there.
`version`	number	Optional but recommended. The version you read. If somebody changed the instructions since then, your write is refused instead of overwriting their work.
`mode`	string	Optional. Either instructions or general.
`ask_questions`	boolean	Optional. Whether the assistant asks a follow-up question at the end of its answers.
`force`	boolean	Optional, false by default. Needed only when your new text is less than half the length of the current text.

How your instructions are protected

Instructions can take hours to write, so a write can be refused to protect them:

Code	Meaning
`400`	Your new text is less than half the length of the current text. This catches a script that sends empty or cut-off text over instructions somebody spent hours on. Send force as true if you meant it.
`409`	The instructions changed after you read them. Read them again, apply your change, then write.
`423`	Somebody is editing the instructions in the dashboard right now. The answer tells you who. Try again in a couple of minutes.

Every change also saves a copy of the previous text, so an earlier version can always be restored from the dashboard.

GET /conversations/

Recupera la cronologia della conversazione per una sessione specifica.

Parametri di query

Parametro	Tipo	Obbligatorio	Descrizione
`session_id`	string	Sì	L'ID della sessione di cui recuperare la cronologia
`limit`	integer	No	Numero di messaggi da restituire (predefinito: 50, max: 100)

Risposta

{
  "success": true,
  "session_id": "user_123",
  "messages": [
    {
      "role": "user",
      "content": "What are your business hours?",
      "timestamp": "2024-01-15T10:30:00Z"
    },
    {
      "role": "assistant",
      "content": "Our business hours are Monday-Friday, 9 AM to 5 PM EST.",
      "timestamp": "2024-01-15T10:30:01Z",
      "sender_type": "ai",
      "agent_name": null,
      "response_time_ms": 1840.5
    }
  ]
}

Una domanda e la sua risposta sono salvate in un unico record, quindi entrambe portano lo stesso timestamp. Non sottragga l'uno dall'altro per misurare la velocità di risposta, perché il risultato è sempre zero. Usi response_time_ms, che è il tempo reale impiegato dalla risposta, in millisecondi.

sender_type vale ai quando ha risposto il chatbot e human quando uno dei suoi agenti ha preso in carico la chat. agent_name contiene il nome visualizzato di quell'agente.

Esempio (cURL)

curl "https://asyntai.com/api/v1/conversations/?session_id=user_123&limit=20" \
  -H "Authorization: Bearer YOUR_API_KEY"

GET /sessions/

Elenca le tue sessioni di chat recenti. Usalo per scoprire gli ID delle sessioni, che puoi poi passare a /conversations/ per recuperare la cronologia completa dei messaggi.

Parametri di query

Parametro	Tipo	Obbligatorio	Descrizione
`limit`	integer	No	Numero di sessioni recenti da restituire (predefinito: 20, max: 100)
`website_id`	string	No	Filtra le sessioni per un ID sito web specifico
`source`	string	No	Filtra per origine della sessione: `widget`, `api`, `whatsapp`, `instagram`, `messenger`, `gorgias`, `freshchat`, `zapier`
`since`	string	No	Solo le sessioni il cui ultimo messaggio è in questa data ISO o dopo, per esempio 2024-01-15
`before`	string	No	Solo le sessioni il cui ultimo messaggio è prima di questa data o data-ora ISO. Usalo per scorrere all'indietro, vedi sotto.

Risposta

{
  "success": true,
  "sessions": [
    {
      "session_id": "session_abc123def",
      "source": "widget",
      "message_count": 5,
      "first_message": "What are your business hours?",
      "first_message_at": "2024-01-15T10:30:00Z",
      "last_message_at": "2024-01-15T10:35:00Z",
      "first_response_time_ms": 1840.5,
      "first_human_response_at": null,
      "started_at": "2024-01-15T10:29:58Z",
      "ended_at": "2024-01-15T10:41:12Z",
      "taken_over_at": null,
      "page_url": "https://example.com/pricing",
      "country": "Germany",
      "category": "Pricing",
      "website_domain": "example.com"
    }
  ]
}

Campi di marca temporale per il reporting

Campo	Descrizione
`started_at`	Quando il visitatore ha aperto la chat. Disponibile solo per le sessioni del widget, perché le sessioni create tramite API non aprono mai un widget.
`first_message_at`	Quando è stato salvato il primo messaggio della conversazione.
`first_response_time_ms`	Quanto è durata la prima risposta, in millisecondi. Usi questo campo per il tempo di prima risposta.
`first_human_response_at`	Quando uno dei suoi agenti ha inviato la prima risposta. Il valore è `null` quando il chatbot ha gestito l'intera conversazione.
`taken_over_at`	Quando un agente ha preso in carico la chat dal chatbot.
`last_message_at`	Quando è stato salvato l'ultimo messaggio della conversazione.
`ended_at`	Quando il visitatore ha lasciato la chat. Una chat non ha uno stato risolto o chiuso, perché un visitatore può sempre tornare e fare un'altra domanda.

Tutte le marche temporali sono in UTC e usano il formato ISO 8601. Non è possibile cambiare il fuso orario. Converta i valori nel suo strumento di reporting.

Altri campi per i report

Campo	Descrizione
`page_url`	La pagina su cui si trovava il visitatore all'inizio della chat. Disponibile solo per le sessioni del widget.
`country`	Il paese del visitatore, dall'indirizzo IP al momento della chat. Disponibile solo per le sessioni del widget.
`category`	L'argomento dalle categorie di chat. Vuoto quando la funzione è disattivata o il processo giornaliero non ha ancora etichettato questa chat.

Esempio (cURL)

curl "https://asyntai.com/api/v1/sessions/?since=2024-01-01&limit=100" \
  -H "Authorization: Bearer YOUR_API_KEY"

Scorrere la cronologia

Una chiamata restituisce al massimo 100 sessioni, le più recenti per prime. Per leggere più indietro, prendi il last_message_at dell'ultima sessione della pagina e passalo come before nella chiamata successiva. Ripeti finché una chiamata non restituisce una lista vuota.

import requests

url = "https://asyntai.com/api/v1/sessions/"
headers = {"Authorization": "Bearer YOUR_API_KEY"}
params = {"since": "2024-01-01", "limit": 100}

sessions = []
while True:
    page = requests.get(url, headers=headers, params=params).json()["sessions"]
    if not page:
        break
    sessions.extend(page)
    params["before"] = page[-1]["last_message_at"]

print(len(sessions), "sessions since 2024-01-01")

GET /leads/

Recupera i lead raccolti — indirizzi email e numeri di telefono inviati dai visitatori durante le conversazioni in chat.

Parametri di query

Parametro	Tipo	Obbligatorio	Descrizione
`limit`	integer	No	Numero di lead da restituire (predefinito: 50, max: 100)
`website_id`	string	No	Filtra i lead per un ID sito web specifico
`since`	string	No	Solo lead iniziati in questa data ISO o dopo, per esempio 2024-01-15
`before`	string	No	Solo lead iniziati prima di questa data o ora ISO. Usalo per scorrere all'indietro tutta la cronologia.

Risposta

{
  "success": true,
  "leads": [
    {
      "session_id": "session_abc123def",
      "email": "[email protected]",
      "phone": "+1234567890",
      "page_url": "https://example.com/pricing",
      "started_at": "2024-01-15T10:30:00Z"
    }
  ]
}

Campo	Tipo	Descrizione
`session_id`	string	L'ID della sessione di chat. Passalo a `/conversations/` per vedere la cronologia completa della chat.
`email`	stringa o null	Indirizzo email fornito dal visitatore, o null se non raccolto
`phone`	stringa o null	Numero di telefono fornito dal visitatore, o null se non raccolto
`page_url`	stringa o null	L'URL della pagina in cui il visitatore stava chattando
`started_at`	string	Timestamp ISO 8601 dell'inizio della sessione di chat

Esempio (cURL)

curl "https://asyntai.com/api/v1/leads/?limit=20" \
  -H "Authorization: Bearer YOUR_API_KEY"

Esempio (Python)

import requests

response = requests.get(
    "https://asyntai.com/api/v1/leads/",
    headers={"Authorization": "Bearer YOUR_API_KEY"},
    params={"limit": 20}
)

leads = response.json()["leads"]
for lead in leads:
    print(f"{lead['email'] or ''} | {lead['phone'] or ''}")

GET /tickets/

Recupera i ticket di assistenza con le marche temporali che ti servono per misurare i tempi di gestione: quando è arrivato il ticket, quando qualcuno lo ha preso, quando ha ricevuto la prima risposta e quando è stato risolto.

Parametri di query

Parametro	Tipo	Obbligatorio	Descrizione
`limit`	integer	No	Numero di ticket da restituire (predefinito: 50, massimo: 100)
`website_id`	string	No	Filtra i ticket per ID del sito web o per dominio del sito web, ad esempio example.com
`name`	string	No	Filtra per qualsiasi parte del nome del visitatore, ad esempio anna
`status`	string	No	Filtra per stato: open, in_progress, resolved o closed
`since`	string	No	Solo i ticket creati a partire da questa data ISO, per esempio 2024-01-15
`before`	string	No	Solo i ticket creati prima di questa data o data-ora ISO. Usalo per scorrere all'indietro, vedi sotto.

Risposta

{
  "success": true,
  "tickets": [
    {
      "ticket_number": "TKT-00001",
      "session_id": "session_abc123def",
      "status": "resolved",
      "priority": "medium",
      "subject": "Cannot complete checkout",
      "visitor_email": "[email protected]",
      "visitor_name": "Anna Novak",
      "page_url": "https://example.com/checkout",
      "website_id": 12,
      "channel": "session",
      "assigned_to": "[email protected]",
      "created_at": "2024-01-15T10:30:00Z",
      "first_assigned_at": "2024-01-15T10:41:00Z",
      "first_response_at": "2024-01-15T11:02:00Z",
      "resolved_at": "2024-01-15T12:20:00Z"
    }
  ]
}

Campo	Tipo	Descrizione
`ticket_number`	string	Il riferimento del ticket mostrato nella tua dashboard
`session_id`	string	La sessione di chat da cui è nato il ticket. Passala a `/conversations/` per leggere l'intera conversazione dietro al ticket.
`visitor_name`	stringa o null	Il nome del visitatore, oppure null se il visitatore non lo ha indicato
`status`	string	Uno tra: open, in_progress, resolved, closed
`priority`	string	Uno tra: low, medium, high
`channel`	string	Da dove è arrivata la conversazione, per esempio session per la chat del sito web
`assigned_to`	stringa o null	Il membro del team che ha il ticket, o null se non lo ha preso nessuno
`created_at`	string	Quando è stato creato il ticket
`first_assigned_at`	stringa o null	Quando qualcuno ha preso il ticket per la prima volta. Null se non lo ha fatto nessuno.
`first_response_at`	stringa o null	Quando è stata inviata la prima risposta da Asyntai. Null se da Asyntai non è partita alcuna risposta.
`resolved_at`	stringa o null	Quando il ticket è stato segnato come risolto. Null finché resta aperto.

Vediamo solo le risposte inviate da Asyntai. Se il tuo team risponde a un visitatore dalla propria casella di posta, noi non lo vediamo mai e first_response_at resta vuoto anche se il visitatore ha avuto risposta. Tienilo presente prima di fare medie con questi numeri.

Tutte le marche temporali sono in UTC e usano il formato ISO 8601. I ticket creati prima di questa funzione non hanno first_assigned_at né first_response_at, perché quei tempi non sono mai stati registrati.

Esempio (cURL)

curl "https://asyntai.com/api/v1/tickets/?status=resolved&limit=20" \
  -H "Authorization: Bearer YOUR_API_KEY"

Esempio (Python)

import requests
from datetime import datetime

response = requests.get(
    "https://asyntai.com/api/v1/tickets/",
    headers={"Authorization": "Bearer YOUR_API_KEY"},
    params={"since": "2024-01-01", "limit": 100}
)

for ticket in response.json()["tickets"]:
    if ticket["first_response_at"]:
        created = datetime.fromisoformat(ticket["created_at"])
        replied = datetime.fromisoformat(ticket["first_response_at"])
        print(ticket["ticket_number"], replied - created)

Scorrere la cronologia

Una chiamata restituisce al massimo 100 ticket, i più recenti per primi. Per leggere più indietro, prendi il created_at dell'ultimo ticket della pagina e passalo come before nella chiamata successiva. Ripeti finché una chiamata non restituisce una lista vuota.

import requests

url = "https://asyntai.com/api/v1/tickets/"
headers = {"Authorization": "Bearer YOUR_API_KEY"}
params = {"since": "2024-01-01", "limit": 100}

tickets = []
while True:
    page = requests.get(url, headers=headers, params=params).json()["tickets"]
    if not page:
        break
    tickets.extend(page)
    params["before"] = page[-1]["created_at"]

print(len(tickets), "tickets since 2024-01-01")

GET /account/

Ottieni le informazioni del tuo account e le statistiche di utilizzo.

Risposta

{
  "success": true,
  "account": {
    "email": "[email protected]",
    "plan": "starter",
    "messages_used": 150,
    "messages_limit": 800
  }
}

Esempio (cURL)

curl https://asyntai.com/api/v1/account/ \
  -H "Authorization: Bearer YOUR_API_KEY"

Più siti web? Gli endpoint della knowledge base utilizzano per impostazione predefinita il tuo sito web principale. Se hai più siti web, passa website_id per selezionarne uno specifico. Puoi trovare gli ID dei tuoi siti web utilizzando GET /websites/.

Limiti di caricamento giornalieri: I caricamenti nella knowledge base (testo, URL, fogli di calcolo) sono soggetti a un limite giornaliero di caratteri in base al tuo piano. Questo si applica al contenuto totale caricato su tutti gli endpoint della knowledge base al giorno.

Piano	Caratteri/giorno
Starter	300.000
Standard	1.500.000
Pro	6.000.000

GET /knowledge/

Elenca le voci della tua knowledge base. Queste sono le fonti di contenuto che il tuo chatbot IA utilizza per rispondere alle domande.

Parametri di query

Parametro	Tipo	Obbligatorio	Descrizione
`limit`	integer	No	Numero di voci da restituire (predefinito: 50, massimo: 100)
`website_id`	string	No	Filtra per ID sito web (predefinito: il tuo sito web principale)

Risposta

{
  "success": true,
  "entries": [
    {
      "id": "abc-123-def",
      "type": "text",
      "title": "Business Hours",
      "description": "Manual text content (150 words)",
      "created_at": "2024-01-15T10:30:00Z"
    },
    {
      "id": "ghi-456-jkl",
      "type": "url",
      "title": "About Us - Example",
      "description": "Content from https://example.com/about",
      "created_at": "2024-01-14T09:00:00Z"
    }
  ]
}

Esempio (cURL)

curl "https://asyntai.com/api/v1/knowledge/?limit=10" \
  -H "Authorization: Bearer YOUR_API_KEY"

POST /knowledge/text/

Aggiungi contenuto testuale personalizzato alla tua knowledge base. L'IA lo utilizzerà per rispondere alle domande dei visitatori.

Corpo della richiesta

{
  "title": "Return Policy",
  "content": "We offer a 30-day return policy on all items. Items must be unused and in original packaging. Refunds are processed within 5-7 business days.",
  "website_id": "123"
}

Parametro	Tipo	Obbligatorio	Descrizione
`title`	string	Sì	Un titolo per questa voce della knowledge base
`content`	string	Sì	Il contenuto testuale (minimo 10 caratteri)
`website_id`	string	No	Sito web di destinazione (predefinito: il tuo sito web principale)

Risposta

{
  "success": true,
  "id": "abc-123-def",
  "title": "Return Policy",
  "chunks_created": 1
}

Esempio (cURL)

curl -X POST "https://asyntai.com/api/v1/knowledge/text/" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"title": "Return Policy", "content": "We offer a 30-day return policy..."}'

POST /knowledge/url/

Aggiungi una pagina web alla tua knowledge base. Il contenuto verrà recuperato ed estratto automaticamente.

Corpo della richiesta

{
  "url": "https://example.com/faq",
  "website_id": "123"
}

Parametro	Tipo	Obbligatorio	Descrizione
`url`	string	Sì	L'URL da cui recuperare il contenuto
`website_id`	string	No	Sito web di destinazione (predefinito: il tuo sito web principale)

Risposta

{
  "success": true,
  "id": "abc-123-def",
  "title": "FAQ - Example",
  "url": "https://example.com/faq",
  "chunks_created": 5
}

Esempio (cURL)

curl -X POST "https://asyntai.com/api/v1/knowledge/url/" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"url": "https://example.com/faq"}'

POST /knowledge/spreadsheet/

Carica un foglio di calcolo CSV o Excel (.xlsx) nella tua knowledge base. Ogni riga diventa una voce separata, ideale per cataloghi prodotti, elenchi FAQ, tabelle prezzi e directory.

Richiesta

Invia come multipart/form-data (caricamento file), non JSON.

Parametro	Tipo	Obbligatorio	Descrizione
`file`	file	Sì	Un file .csv o .xlsx. La prima riga deve contenere le intestazioni delle colonne. Righe massime per caricamento: Starter 500, Standard 2.000, Pro 10.000. Le righe in eccesso vengono troncate.
`website_id`	string	No	Sito web di destinazione (predefinito: il tuo sito web principale)

Risposta

{
  "success": true,
  "id": "abc-123-def",
  "title": "products.csv",
  "rows_processed": 15,
  "chunks_created": 15
}

Esempio (cURL)

curl -X POST "https://asyntai.com/api/v1/knowledge/spreadsheet/" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -F "[email protected]"

GET /knowledge/{id}/

Leggi una voce della base di conoscenza, incluso il testo memorizzato per essa. Il valore id proviene dalla risposta di GET /knowledge/.

Il contenuto viene restituito per le voci che hai aggiunto tu: testo, file, fogli di calcolo, singoli URL e video. La scansione di un sito web compare nell'elenco, ma le sue pagine non vengono restituite, perché la fonte è il tuo sito pubblico. In tal caso content è null e il campo reason ne spiega il motivo.

Risposta

{
  "success": true,
  "id": "abc-123-def",
  "type": "text",
  "title": "Business Hours",
  "description": "Manual text content (150 words)",
  "created_at": "2024-01-15T10:30:00Z",
  "chunks_count": 3,
  "content": "We are open Monday to Friday, 9am to 5pm...",
  "content_available": true,
  "char_count": 43
}

Esempio (cURL)

curl "https://asyntai.com/api/v1/knowledge/abc-123-def/" \
  -H "Authorization: Bearer YOUR_API_KEY"

DELETE /knowledge/{id}/

Elimina una voce della knowledge base. L'id può essere trovato nella risposta di GET /knowledge/.

Risposta

{
  "success": true,
  "message": "Knowledge base entry deleted"
}

Esempio (cURL)

curl -X DELETE "https://asyntai.com/api/v1/knowledge/abc-123-def/" \
  -H "Authorization: Bearer YOUR_API_KEY"

Suggerimento: Puoi anche gestire i webhook dalla Impostazioni API pagina senza scrivere codice.

GET /webhooks/

Elenca i tuoi webhook registrati.

Risposta

{
  "success": true,
  "webhooks": [
    {
      "id": "abc-123-def",
      "url": "https://example.com/webhook",
      "events": ["message.received", "escalation.requested"],
      "is_active": true,
      "created_at": "2024-01-15T10:30:00Z"
    }
  ]
}

Esempio (cURL)

curl "https://asyntai.com/api/v1/webhooks/" \
  -H "Authorization: Bearer YOUR_API_KEY"

POST /webhooks/

Registra un nuovo webhook per ricevere notifiche sugli eventi in tempo reale.

Eventi disponibili

Evento	Descrizione
`message.received`	Un visitatore ha inviato un messaggio e ha ricevuto una risposta
`conversation.started`	Una nuova sessione di chat è stata avviata
`escalation.requested`	L'IA ha attivato un'escalation verso un agente umano
`takeover.started`	Un agente umano ha preso il controllo di una sessione di chat

Corpo della richiesta

{
  "url": "https://example.com/webhook",
  "events": ["message.received", "escalation.requested"],
  "website_id": "123"
}

Parametro	Tipo	Obbligatorio	Descrizione
`url`	string	Sì	L'URL HTTPS per ricevere le richieste POST del webhook
`events`	array	Sì	Elenco degli eventi a cui iscriversi (vedi tabella sopra)
`website_id`	string	No	Sito web di destinazione (predefinito: il tuo sito web principale)

Risposta

{
  "success": true,
  "webhook": {
    "id": "abc-123-def",
    "url": "https://example.com/webhook",
    "events": ["message.received", "escalation.requested"],
    "secret": "whsec_abc123...",
    "created_at": "2024-01-15T10:30:00Z"
  }
}

Verifica dei webhook: Ogni webhook include un secret (mostrato solo alla creazione). Ogni POST al tuo URL include un X-Webhook-Signature header — un HMAC-SHA256 del corpo della richiesta firmato con il tuo segreto.

Esempio (cURL)

curl -X POST "https://asyntai.com/api/v1/webhooks/" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"url": "https://example.com/webhook", "events": ["message.received"]}'

DELETE /webhooks/{id}/

Elimina un webhook. L'id può essere trovato nella risposta di GET /webhooks/.

Risposta

{
  "success": true,
  "message": "Webhook deleted"
}

Esempio (cURL)

curl -X DELETE "https://asyntai.com/api/v1/webhooks/abc-123-def/" \
  -H "Authorization: Bearer YOUR_API_KEY"

Risposte di errore

Tutte le risposte di errore seguono questo formato:

{
  "success": false,
  "error": "Error message describing what went wrong"
}

Codice di stato	Descrizione
`400`	Bad Request - Parametri non validi o campi obbligatori mancanti
`401`	Unauthorized - Chiave API non valida o mancante
`429`	Too Many Requests - Limite di messaggi raggiunto per il tuo piano
`503`	Service Unavailable - Servizio IA temporaneamente non disponibile

Limiti di frequenza

L'utilizzo dell'API è limitato dal tuo piano di abbonamento:

Free: 50 messaggi/mese
Starter ($39/mese): 800 messaggi/mese
Standard ($139/mese): 15.000 messaggi/mese
Pro ($449/mese): 50.000 messaggi/mese

Hai bisogno di aiuto?

If you have any questions or run into issues, contact us at [email protected].

Documentazione

Riferimento API

Panoramica

Autenticazione

URL di base

Endpoint

POST /chat/

Corpo della richiesta

Risposta

Esempio (cURL)

Esempio (Python)

Esempio (JavaScript)

GET /websites/

Risposta

Esempio (cURL)

POST /websites/

Corpo della richiesta

Risposta

Esempio (cURL)

Errors

GET /websites/{id}/

Risposta

Esempio (cURL)

GET PATCH /websites/{id}/settings/

Reading the settings

Changing the settings

Plans

GET PUT /websites/{id}/instructions/

Reading

Replacing

Corpo della richiesta

How your instructions are protected

GET /conversations/

Parametri di query

Risposta

Esempio (cURL)

GET /sessions/

Parametri di query

Risposta

Campi di marca temporale per il reporting

Altri campi per i report

Esempio (cURL)

Scorrere la cronologia

GET /leads/

Parametri di query

Risposta

Esempio (cURL)

Esempio (Python)

GET /tickets/

Parametri di query

Risposta

Esempio (cURL)

Esempio (Python)

Scorrere la cronologia

GET /account/

Risposta

Esempio (cURL)

GET /knowledge/

Parametri di query

Risposta

Esempio (cURL)

POST /knowledge/text/

Corpo della richiesta

Risposta

Esempio (cURL)

POST /knowledge/url/

Corpo della richiesta

Risposta

Esempio (cURL)

POST /knowledge/spreadsheet/

Richiesta

Risposta

Esempio (cURL)

GET /knowledge/{id}/

Risposta

Esempio (cURL)

DELETE /knowledge/{id}/

Risposta

Esempio (cURL)

GET /webhooks/