Takaisin hallintapaneeliin

Dokumentaatio

Opi käyttämään Asyntai

API-viite

Rakenna mukautettuja integraatioita Asyntai REST API:n avulla

Hanki API-avain

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ä
Starter100 000
Standard500 000
Pro2 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.