API-viite
Rakenna mukautettuja integraatioita Asyntai REST API:n avulla
Maksullinen paketti vaaditaan: API-pääsy on saatavilla Starter-, Standard- ja Pro-paketeissa. Näytä hinnoittelu
Yleiskatsaus
Asyntai API mahdollistaa tekoälypohjaisen asiakastuen integroinnin mihin tahansa sovellukseen. Lähetä viestejä ja vastaanota älykkäitä vastauksia, jotka on koulutettu verkkosivustosi sisällöllä ja tietopankilla.
Tunnistautuminen
Kaikki API-pyynnöt vaativat todennuksen API-avaimellasi. Voit hakea API-avaimesi API-asetukset-sivulta.
Sisällytä API-avaimesi pyyntöihin jollakin seuraavista tavoista:
- Authorization-otsikko (suositeltu):
Authorization: Bearer YOUR_API_KEY - X-API-Key-otsikko:
X-API-Key: YOUR_API_KEY
Pidä API-avaimesi salassa. Kuka tahansa, jolla on avaimesi, voi käyttää tiliäsi API:n kautta. Älä koskaan paljasta sitä asiakaspuolen koodissa.
Perus-URL
https://asyntai.com/api/v1/
Päätepisteet
POST /chat/
Lähetä viesti ja vastaanota tekoälyn tuottama vastaus.
Pyynnön runko
{
"message": "What are your business hours?",
"session_id": "user_123", // optional
"website_id": 1 // optional
}
| Parametri | Tyyppi | Pakollinen | Kuvaus |
|---|---|---|---|
message |
string | Kyllä | Käyttäjän viesti tekoälylle |
session_id |
string | Ei | Keskustelun yksilöllinen tunniste. Käytä samaa session_id-arvoa keskusteluhistorian säilyttämiseksi. |
website_id |
integer | Ei | Tietyn verkkosivuston ID. Jos sitä ei anneta, käytetään ensisijaista verkkosivustoasi. |
Vastaus
{
"success": true,
"response": "Our business hours are Monday-Friday, 9 AM to 5 PM EST.",
"session_id": "user_123"
}
Esimerkki (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"}'
Esimerkki (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"])
Esimerkki (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/
Listaa kaikki tiliisi liitetyt verkkosivustot.
Vastaus
{
"success": true,
"websites": [
{
"id": 1,
"name": "My Website",
"domain": "example.com",
"is_primary": true
}
]
}
Esimerkki (cURL)
curl https://asyntai.com/api/v1/websites/ \
-H "Authorization: Bearer YOUR_API_KEY"
GET /conversations/
Hae tietyn istunnon keskusteluhistoria.
Kyselyparametrit
| Parametri | Tyyppi | Pakollinen | Kuvaus |
|---|---|---|---|
session_id |
string | Kyllä | Istunnon tunniste, jonka historia haetaan |
limit |
integer | Ei | Palautettavien viestien enimmäismäärä (oletus: 50, maks: 100) |
Vastaus
{
"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"
}
]
}
Esimerkki (cURL)
curl "https://asyntai.com/api/v1/conversations/?session_id=user_123&limit=20" \
-H "Authorization: Bearer YOUR_API_KEY"
GET /sessions/
Listaa viimeisimmät keskusteluistuntosi. Käytä tätä istuntotunnisteiden löytämiseen, jotka voit sitten välittää /conversations/-päätepisteelle koko viestihistorian hakemiseksi.
Kyselyparametrit
| Parametri | Tyyppi | Pakollinen | Kuvaus |
|---|---|---|---|
limit |
integer | Ei | Palautettavien viimeisten istuntojen määrä (oletus: 20, maks: 100) |
website_id |
string | Ei | Suodata istunnot tietyn verkkosivuston tunnisteen mukaan |
source |
string | Ei | Suodata istunnon lähteen mukaan: widget, api, whatsapp, instagram, messenger, gorgias, freshchat, zapier |
Vastaus
{
"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"
}
]
}
Esimerkki (cURL)
curl "https://asyntai.com/api/v1/sessions/?limit=10" \
-H "Authorization: Bearer YOUR_API_KEY"
GET /leads/
Hae kerätyt liidit — sähköpostiosoitteet ja puhelinnumerot, jotka kävijät ovat lähettäneet chat-keskustelujen aikana.
Kyselyparametrit
| Parametri | Tyyppi | Pakollinen | Kuvaus |
|---|---|---|---|
limit |
integer | Ei | Palautettavien liidien määrä (oletus: 50, maks: 100) |
website_id |
string | Ei | Suodata liidit tietyn verkkosivuston tunnuksen mukaan |
Vastaus
{
"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"
}
]
}
| Kenttä | Tyyppi | Kuvaus |
|---|---|---|
session_id |
string | Chat-istunnon tunniste. Välitä tämä /conversations/-päätteelle nähdäksesi täydellisen chat-historian. |
email |
merkkijono tai null | Kävijän antama sähköpostiosoite, tai null jos ei kerätty |
phone |
merkkijono tai null | Kävijän antama puhelinnumero, tai null jos ei kerätty |
page_url |
merkkijono tai null | Sivun URL, jossa kävijä keskusteli |
started_at |
string | ISO 8601 -aikaleima chat-istunnon alkamisajankohdasta |
Esimerkki (cURL)
curl "https://asyntai.com/api/v1/leads/?limit=20" \
-H "Authorization: Bearer YOUR_API_KEY"
Esimerkki (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/
Hae tilisi tiedot ja käyttötilastot.
Vastaus
{
"success": true,
"account": {
"email": "you@example.com",
"plan": "starter",
"messages_used": 150,
"messages_limit": 2500
}
}
Esimerkki (cURL)
curl https://asyntai.com/api/v1/account/ \
-H "Authorization: Bearer YOUR_API_KEY"
Useita verkkosivustoja? Tietopankin päätepisteet oletuksena viittaavat ensisijaiseen verkkosivustoosi. Jos sinulla on useita verkkosivustoja, välitä website_id kohdistaaksesi tiettyyn. Löydät verkkosivustojesi tunnukset käyttämällä GET /websites/.
Päivittäiset latausrajat: Tietopankin lataukset (teksti, URL, laskentataulukko) ovat päivittäisen merkkirajoituksen alaisia pakettisi mukaan. Tämä koskee kaikkea tietopankin päätepisteisiin päivässä ladattua sisältöä yhteensä.
| Paketti | Merkkiä/päivä |
|---|---|
| Starter | 100 000 |
| Standard | 500 000 |
| Pro | 2 000 000 |
GET /knowledge/
Listaa tietopankin merkinnät. Nämä ovat sisältölähteet, joita tekoälychatbottisi käyttää kysymyksiin vastaamiseen.
Kyselyparametrit
| Parametri | Tyyppi | Pakollinen | Kuvaus |
|---|---|---|---|
limit |
integer | Ei | Palautettavien merkintöjen määrä (oletus: 50, maks: 100) |
website_id |
string | Ei | Suodata verkkosivuston tunnuksen mukaan (oletus: ensisijainen verkkosivustosi) |
Vastaus
{
"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"
}
]
}
Esimerkki (cURL)
curl "https://asyntai.com/api/v1/knowledge/?limit=10" \
-H "Authorization: Bearer YOUR_API_KEY"
POST /knowledge/text/
Lisää mukautettua tekstisisältöä tietopankkiisi. Tekoäly käyttää tätä vierailijoiden kysymyksiin vastaamiseen.
Pyynnön runko
{
"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"
}
| Parametri | Tyyppi | Pakollinen | Kuvaus |
|---|---|---|---|
title |
string | Kyllä | Tietopankkimerkinnän otsikko |
content |
string | Kyllä | Tekstisisältö (vähintään 10 merkkiä) |
website_id |
string | Ei | Kohdeverkkosivusto (oletus: ensisijainen verkkosivustosi) |
Vastaus
{
"success": true,
"id": "abc-123-def",
"title": "Return Policy",
"chunks_created": 1
}
Esimerkki (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/
Lisää verkkosivu tietopankkiisi. Sisältö haetaan ja poimitaan automaattisesti.
Pyynnön runko
{
"url": "https://example.com/faq",
"website_id": "123"
}
| Parametri | Tyyppi | Pakollinen | Kuvaus |
|---|---|---|---|
url |
string | Kyllä | URL-osoite, josta sisältö haetaan |
website_id |
string | Ei | Kohdeverkkosivusto (oletus: ensisijainen verkkosivustosi) |
Vastaus
{
"success": true,
"id": "abc-123-def",
"title": "FAQ - Example",
"url": "https://example.com/faq",
"chunks_created": 5
}
Esimerkki (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/
Lataa CSV- tai Excel-taulukko (.xlsx) tietopankkiisi. Jokaisesta rivistä tulee erillinen tietopankkimerkintä, joka sopii tuoteluetteloihin, UKK-listoihin, hintataulukoihin ja hakemistoihin.
Pyyntö
Lähetä muodossa multipart/form-data (tiedoston lataus), ei JSON.
| Parametri | Tyyppi | Pakollinen | Kuvaus |
|---|---|---|---|
file |
tiedosto | Kyllä | .csv- tai .xlsx-tiedosto. Ensimmäisen rivin on oltava sarakeotsikot. Rivien enimmäismäärä per lataus: Starter 500, Standard 2 000, Pro 10 000. Ylimääräiset rivit katkaistaan. |
website_id |
string | Ei | Kohdeverkkosivusto (oletus: ensisijainen verkkosivustosi) |
Vastaus
{
"success": true,
"id": "abc-123-def",
"title": "products.csv",
"rows_processed": 15,
"chunks_created": 15
}
Esimerkki (cURL)
curl -X POST "https://asyntai.com/api/v1/knowledge/spreadsheet/" \
-H "Authorization: Bearer YOUR_API_KEY" \
-F "file=@products.csv"
DELETE /knowledge/{id}/
Poista tietopankkimerkintä. id-tunnisteen löydät GET /knowledge/ -vastauksen kautta.
Vastaus
{
"success": true,
"message": "Knowledge base entry deleted"
}
Esimerkki (cURL)
curl -X DELETE "https://asyntai.com/api/v1/knowledge/abc-123-def/" \
-H "Authorization: Bearer YOUR_API_KEY"
Vinkki: Voit myös hallita webhookeja API-asetukset -sivulta ilman koodin kirjoittamista.
GET /webhooks/
Listaa rekisteröidyt webhookisi.
Vastaus
{
"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"
}
]
}
Esimerkki (cURL)
curl "https://asyntai.com/api/v1/webhooks/" \
-H "Authorization: Bearer YOUR_API_KEY"
POST /webhooks/
Rekisteröi uusi webhook vastaanottaaksesi reaaliaikaisia tapahtumailmoituksia.
Saatavilla olevat tapahtumat
| Tapahtuma | Kuvaus |
|---|---|
message.received |
Vierailija lähetti viestin ja sai vastauksen |
conversation.started |
Uusi keskusteluistunto aloitettiin |
escalation.requested |
Tekoäly käynnisti eskalaation ihmisagentille |
takeover.started |
Ihmisagentti otti keskusteluistunnon haltuunsa |
Pyynnön runko
{
"url": "https://example.com/webhook",
"events": ["message.received", "escalation.requested"],
"website_id": "123"
}
| Parametri | Tyyppi | Pakollinen | Kuvaus |
|---|---|---|---|
url |
string | Kyllä | HTTPS-URL-osoite webhook POST -pyyntöjen vastaanottamiseen |
events |
array | Kyllä | Lista tilattavista tapahtumista (katso yllä oleva taulukko) |
website_id |
string | Ei | Kohdeverkkosivusto (oletus: ensisijainen verkkosivustosi) |
Vastaus
{
"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"
}
}
Webhookien vahvistaminen: Jokainen webhook sisältää secret (näytetään vain luotaessa). Jokainen POST URL-osoitteeseesi sisältää X-Webhook-Signature otsikko — pyynnön rungon HMAC-SHA256, allekirjoitettu salaisuudellasi.
Esimerkki (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}/
Poista webhook. id-tunnisteen löydät GET /webhooks/ -vastauksen kautta.
Vastaus
{
"success": true,
"message": "Webhook deleted"
}
Esimerkki (cURL)
curl -X DELETE "https://asyntai.com/api/v1/webhooks/abc-123-def/" \
-H "Authorization: Bearer YOUR_API_KEY"
Virhevastaukset
Kaikki virhevastaukset noudattavat tätä muotoa:
{
"success": false,
"error": "Error message describing what went wrong"
}
| Tilakoodi | Kuvaus |
|---|---|
400 |
Virheellinen pyyntö – Virheelliset parametrit tai puuttuvat pakolliset kentät |
401 |
Luvaton - Virheellinen tai puuttuva API-avain |
429 |
Liian monta pyyntöä - Pakettisi viestiraja saavutettu |
503 |
Palvelu ei saatavilla - Tekoälypalvelu tilapäisesti poissa käytöstä |
Pyyntörajoitukset
API:n käyttöä rajoittaa tilauspakettisi:
- Ilmainen: 100 viestiä/kuukausi
- Starter (39 $/kk): 2 500 viestiä/kuukausi
- Standard (139 $/kk): 15 000 viestiä/kuukausi
- Pro (449 $/kk): 50 000 viestiä/kuukausi
Tarvitsetko apua?
Jos sinulla on kysyttävää tai kohtaat ongelmia, ota meihin yhteyttä osoitteessa hello@asyntai.com.