Nazaj na nadzorno ploščo

Dokumentacija

Naučite se uporabljati Asyntai

API referenca

Zgradite prilagojene integracije z Asyntai REST API

Pridobite API ključ

Zahtevan plačljiv načrt: Dostop do API je na voljo v načrtih Starter, Standard in Pro. Ogled cen

Pregled

API Asyntai vam omogoča, da integrirate podporo strankam z umetno inteligenco v katero koli aplikacijo. Pošljite sporočila in prejemajte inteligentne odgovore, naučene na vsebini vašega spletnega mesta in bazi znanja.

Avtentikacija

Vse zahteve API zahtevajo avtentikacijo z vašim API ključem. Svoj API ključ lahko pridobite na strani Nastavitve API.

Vključite svoj API ključ v zahteve z eno od teh metod:

  • Glava Authorization (priporočeno): Authorization: Bearer YOUR_API_KEY
  • Glava X-API-Key: X-API-Key: YOUR_API_KEY

Vaš API ključ naj ostane skrivnost. Kdorkoli z vašim ključem lahko dostopa do vašega računa prek API. Nikoli ga ne izpostavljajte v kodi na strani odjemalca.

Osnovni URL

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

Končne točke

POST /chat/

Pošljite sporočilo in prejmite odgovor, ustvarjen z UI.

Telo zahteve

{
  "message": "What are your business hours?",
  "session_id": "user_123",      // optional
  "website_id": 1                 // optional
}
Parameter Tip Zahtevano Opis
message string Da Uporabnikovo sporočilo za pošiljanje UI-ju
session_id string Ne Edinstven identifikator za pogovor. Uporabite isti session_id za ohranjanje zgodovine pogovora.
website_id integer Ne Specifičen ID spletnega mesta. Če ni naveden, se uporabi vaše primarno spletno mesto.

Odgovor

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

Primer (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"}'

Primer (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"])

Primer (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/

Seznam vseh spletnih mest, povezanih z vašim računom.

Odgovor

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

Primer (cURL)

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

GET /conversations/

Pridobite zgodovino pogovorov za določeno sejo.

Parametri poizvedbe

Parameter Tip Zahtevano Opis
session_id string Da ID seje, za katero želite pridobiti zgodovino
limit integer Ne Največje število sporočil za vrnitev (privzeto: 50, maks.: 100)

Odgovor

{
  "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"
    }
  ]
}

Primer (cURL)

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

GET /sessions/

Seznam vaših nedavnih sej klepeta. Uporabite to za odkrivanje ID-jev sej, ki jih lahko nato posredujete v /conversations/ za pridobitev celotne zgodovine sporočil.

Parametri poizvedbe

Parameter Tip Zahtevano Opis
limit integer Ne Število nedavnih sej za vrnitev (privzeto: 20, maks.: 100)
website_id string Ne Filtrirajte seje po določenem ID-ju spletnega mesta
source string Ne Filtrirajte po viru seje: widget, api, whatsapp, instagram, messenger, gorgias, freshchat, zapier

Odgovor

{
  "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",
      "website_domain": "example.com"
    }
  ]
}

Primer (cURL)

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

GET /leads/

Pridobi zbrane potencialne stranke — e-poštne naslove in telefonske številke, ki so jih obiskovalci poslali med pogovori v klepetu.

Parametri poizvedbe

Parameter Tip Zahtevano Opis
limit integer Ne Število potencialnih strank za vrnitev (privzeto: 50, maks: 100)
website_id string Ne Filtrirajte potencialne stranke po določenem ID-ju spletnega mesta

Odgovor

{
  "success": true,
  "leads": [
    {
      "session_id": "session_abc123def",
      "email": "visitor@example.com",
      "phone": "+1234567890",
      "page_url": "https://example.com/pricing",
      "started_at": "2024-01-15T10:30:00Z"
    }
  ]
}
Polje Tip Opis
session_id string ID seje klepeta. Posredujte ga v /conversations/ za ogled celotne zgodovine klepeta.
email niz ali null E-poštni naslov, ki ga je posredoval obiskovalec, ali null, če ni bil zbran
phone niz ali null Telefonska številka, ki jo je posredovala obiskovalka, ali null, če ni bila zbrana
page_url niz ali null URL strani, kjer se je obiskovalec pogovarjal
started_at string Časovni žig ISO 8601 začetka seje klepeta

Primer (cURL)

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

Primer (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 /account/

Pridobite informacije o svojem računu in statistiko uporabe.

Odgovor

{
  "success": true,
  "account": {
    "email": "you@example.com",
    "plan": "starter",
    "messages_used": 150,
    "messages_limit": 2500
  }
}

Primer (cURL)

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

Več spletnih mest? Končne točke baze znanja privzeto uporabljajo vaše primarno spletno mesto. Če imate več spletnih mest, posredujte website_id za ciljanje določenega. ID-je svojih spletnih mest lahko najdete z uporabo GET /websites/.

Dnevne omejitve nalaganja: Nalaganja v bazo znanja (besedilo, URL, preglednica) so predmet dnevne omejitve znakov glede na vaš načrt. To velja za celotno vsebino, naloženo prek vseh končnih točk baze znanja na dan.

Načrt Znakov/dan
Starter100.000
Standard500.000
Pro2.000.000

GET /knowledge/

Seznam vnosov vaše baze znanja. To so viri vsebine, ki jih vaš klepetalni robot z UI uporablja za odgovarjanje na vprašanja.

Parametri poizvedbe

Parameter Tip Zahtevano Opis
limit integer Ne Število vnosov za vrnitev (privzeto: 50, maks.: 100)
website_id string Ne Filtrirajte po ID-ju spletnega mesta (privzeto vaše primarno spletno mesto)

Odgovor

{
  "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"
    }
  ]
}

Primer (cURL)

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

POST /knowledge/text/

Dodajte prilagojeno besedilno vsebino v svojo bazo znanja. UI bo to uporabila za odgovarjanje na vprašanja obiskovalcev.

Telo zahteve

{
  "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"
}
Parameter Tip Zahtevano Opis
title string Da Naslov za ta vnos v bazo znanja
content string Da Besedilna vsebina (najmanj 10 znakov)
website_id string Ne Ciljno spletno mesto (privzeto vaše primarno spletno mesto)

Odgovor

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

Primer (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/

Dodajte spletno stran v svojo bazo znanja. Vsebina bo samodejno pridobljena in izvlečena.

Telo zahteve

{
  "url": "https://example.com/faq",
  "website_id": "123"
}
Parameter Tip Zahtevano Opis
url string Da URL, s katerega se pridobi vsebina
website_id string Ne Ciljno spletno mesto (privzeto vaše primarno spletno mesto)

Odgovor

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

Primer (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/

Naložite preglednico CSV ali Excel (.xlsx) v svojo bazo znanja. Vsaka vrstica postane ločen vnos v bazo znanja, idealno za kataloge izdelkov, sezname pogostih vprašanj, cenike in imenike.

Zahteva

Pošljite kot multipart/form-data (nalaganje datoteke), ne JSON.

Parameter Tip Zahtevano Opis
file datoteka Da Datoteka .csv ali .xlsx. Prva vrstica morajo biti glave stolpcev. Največje število vrstic na nalaganje: Starter 500, Standard 2.000, Pro 10.000. Presežne vrstice so odrezane.
website_id string Ne Ciljno spletno mesto (privzeto vaše primarno spletno mesto)

Odgovor

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

Primer (cURL)

curl -X POST "https://asyntai.com/api/v1/knowledge/spreadsheet/" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -F "file=@products.csv"

DELETE /knowledge/{id}/

Izbrišite vnos iz baze znanja. id lahko najdete v odgovoru GET /knowledge/.

Odgovor

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

Primer (cURL)

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

Nasvet: Webhooke lahko upravljate tudi iz Nastavitve API strani brez pisanja kakršne koli kode.

GET /webhooks/

Seznam vaših registriranih webhookov.

Odgovor

{
  "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"
    }
  ]
}

Primer (cURL)

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

POST /webhooks/

Registrirajte nov webhook za prejemanje obvestil o dogodkih v realnem času.

Razpoložljivi dogodki

Dogodek Opis
message.received Obiskovalec je poslal sporočilo in prejel odgovor
conversation.started Začeta je bila nova seja klepeta
escalation.requested UI je sprožila eskalacijo na človeškega agenta
takeover.started Človeški agent je prevzel sejo klepeta

Telo zahteve

{
  "url": "https://example.com/webhook",
  "events": ["message.received", "escalation.requested"],
  "website_id": "123"
}
Parameter Tip Zahtevano Opis
url string Da HTTPS URL za prejemanje POST zahtev webhookov
events array Da Seznam dogodkov za naročilo (glejte zgornjo tabelo)
website_id string Ne Ciljno spletno mesto (privzeto vaše primarno spletno mesto)

Odgovor

{
  "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"
  }
}

Preverjanje webhookov: Vsak webhook vključuje secret (prikazano samo ob ustvarjanju). Vsak POST na vaš URL vključuje X-Webhook-Signature glavo — HMAC-SHA256 telesa zahteve, podpisan z vašim tajnim ključem.

Primer (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}/

Izbrišite webhook. id lahko najdete v odgovoru GET /webhooks/.

Odgovor

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

Primer (cURL)

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

Odgovori z napako

Vsi odgovori z napako sledijo temu formatu:

{
  "success": false,
  "error": "Error message describing what went wrong"
}
Statusna koda Opis
400 Napačna zahteva - Neveljavni parametri ali manjkajoča zahtevana polja
401 Nepooblaščeno - Neveljaven ali manjkajoč API ključ
429 Preveč zahtev - Dosežena omejitev sporočil za vaš načrt
503 Storitev ni na voljo - Storitev UI je začasno nedosegljiva

Omejitve hitrosti

Uporaba API je omejena z vašim naročniškim načrtom:

  • Free: 100 sporočil/mesec
  • Starter (39 $/mesec): 2.500 sporočil/mesec
  • Standard (139 $/mesec): 15.000 sporočil/mesec
  • Pro (449 $/mesec): 50.000 sporočil/mesec

Potrebujete pomoč?

Če imate kakršna koli vprašanja ali naletite na težave, nas kontaktirajte na hello@asyntai.com.