API ryšiai

Prijunkite savo išorinius API prie enuchat, kad DI ir taisyklės galėtų gauti realaus laiko duomenis iš jūsų sistemų.

Kaip tai veikia

API ryšiai leidžia integruoti enuchat su savo backend sistemomis — rezervavimo varikliais, CRM, užsakymų valdymu, atsargomis ir daugiau. Kai lankytojas užduoda klausimą, enuchat gali iškviesti jūsų API, kad gautų tikrus duomenis ir įtrauktų juos į atsakymą.

Eiga

Sukonfigūruokite ryšį — jūsų API bazinis URL ir autentifikavimas
Pridėkite galinius taškus — konkrečius API iškvietimus su kelio šablonais ir atsakymo atvaizdavimu
Sukurkite taisyklę — DI ar statinę taisyklę su CALL_API veiksmu
Lankytojas užduoda klausimą — taisyklė suveikia, iškviečia jūsų API, atvaizduoja atsakymą į sesijos kintamuosius
DI atsako su tikrais duomenimis — sesijos kintamieji prieinami DI tiksliam atsakymui generuoti

Pavyzdys: viešbučio kambario prieinamumas

Lankytojas: "Ar 205 kambarys prieinamas kitą savaitę?"

DI taisyklė atitinka: "Kai lankytojas klausia apie kambario prieinamumą"

CALL_API veiksmas: GET https://api.hotel.com/rooms/205/availability

Atsakymas atvaizduotas: room_available = true, price = "120 €/naktis"

DI atsako: "205 kambarys prieinamas kitą savaitę už 120 €/naktį. Ar norite jį rezervuoti?"

Ryšio sąranka

Eikite į Nustatymai → API ryšiai savo skydelyje.

1. Sukurti ryšį

Ryšys atstovauja vieną išorinį API. Jums reikia:

Laukas	Aprašymas	Pavyzdys
Pavadinimas	Šio ryšio etiketė	Viešbučio rezervavimo API
Bazinis URL	API šakninis URL	`https://api.hotel.com/v1`
Autentifikavimo tipas	Kaip autentifikuotis	Bearer Token, OAuth2 ir t. t.

2. Autentifikavimo tipai

Nėra

Viešiems API, kuriems nereikia autentifikavimo.

API raktas

Siunčia statinį raktą kaip antraštę arba užklausos parametrą.

Laukas	Aprašymas
Raktas	Jūsų API rakto reikšmė
Antraštės pavadinimas	Naudojama antraštė (numatyta: `X-Api-Key`)

Raktas siunčiamas kaip: X-Api-Key: your_key_here

Bearer Token

Siunčia statinį žetoną Authorization antraštėje.

Siunčiamas kaip: Authorization: Bearer your_token_here

Basic Auth

Siunčia naudotojo vardą ir slaptažodį, užkoduotus base64.

Siunčiamas kaip: Authorization: Basic dXNlcjpwYXNz

OAuth 2.0 (kliento kredencialai)

Automatiškai gauna prieigos žetoną ir kešuoja jį iki galiojimo pabaigos. Geriausia šiuolaikiniams API kaip Salesforce, Google ar pasirinktiniams OAuth serveriams.

Laukas	Aprašymas
Žetono URL	OAuth žetono galinis taškas (pvz., `https://auth.example.com/oauth/token`)
Kliento ID	Jūsų OAuth kliento ID
Kliento paslaptis	Jūsų OAuth kliento paslaptis
Apimtis	Tarpais atskirtos apimtys (pvz., `read write`)

enuchat automatiškai tvarko žetono gyvavimo ciklą — gauna pirmojo iškvietimo metu, kešuoja iki galiojimo pabaigos, prireikus atnaujina.

Saugumas: Visi kredencialai šifruojami nenaudojant, naudojant libsodium. Jie niekada neatskleidžiami API atsakymuose — tik maskuotos reikšmės rodomos skydelyje.

Galinių taškų konfigūravimas

Kiekvienas ryšys gali turėti kelis galinius taškus — konkrečius API iškvietimus, kuriuos norite atlikti.

Laukas	Aprašymas	Pavyzdys
Pavadinimas	Šio galinio taško etiketė	Patikrinti prieinamumą
Metodas	HTTP metodas	GET, POST, PUT, DELETE
Kelias	URL kelias (pridedamas prie bazinio URL). Naudokite `{'{'}variable}` dinaminėms reikšmėms	`/rooms/{'{'}roomId}/availability`
Užklausos parametrai	URL parametrai kaip rakto-vertės poros. Reikšmės palaiko `{'{'}variable}`	`date={'{'}checkIn}`
Kūno šablonas	JSON kūnas POST/PUT. Palaiko `{'{'}variable}` interpoliaciją	`{'{'}"guest": "{'{'}name}"}`
Atsakymo atvaizdavimas	Atvaizduokite JSON atsakymo laukus į sesijos kintamuosius naudojant tašką kaip skirtuką	`data.available → room_available`
Aprašymas	Kontekstas DI (kokius duomenis grąžina šis galinis taškas)	Grąžina kambario prieinamumą ir kainas

Kintamųjų interpoliacija

Naudokite {'{'}variableName} keliuose, užklausos parametruose ir kūno šablonuose. Kintamieji kyla iš:

Sesijos kintamųjų — nustatytų ankstesnių taisyklių (SET_VARIABLE veiksmas)
Veiksmo parametrų — iš anksto užkoduotų CALL_API taisyklės veiksme

Atsakymo atvaizdavimas

Atvaizduokite JSON atsakymo laukus į sesijos kintamuosius naudodami tašką kaip skirtuką:

// API grąžina:
{'{'}
  "data": {'{'}
    "available": true,
    "price": {'{'} "amount": 120, "currency": "EUR" }
  }
}

// Atvaizdavimas:
data.available  →  room_available    // "true"
data.price.amount  →  room_price    // "120"
data.price.currency  →  room_currency  // "EUR"

Atvaizduoti kintamieji saugomi kaip sesijos kintamieji pokalbyje ir prieinami DI atsakymams generuoti.

Naudojimas su taisyklėmis

API iškvietimus sukelia CALL_API veiksmas taisyklėse. Galite derinti juos su kitais veiksmais.

Receptas: užsakymo būsenos paieška

Ryšys: Užsakymų valdymo API — https://api.shop.com/v2 — Bearer Token

Galinis taškas: GET /orders/{'{'}orderId} → atvaizduoja data.status → order_status, data.eta → delivery_eta

Taisyklė (DI tipas): "Kai lankytojas klausia apie savo užsakymo būseną ar pristatymą"

Veiksmai:

CALL_API → Užsakymo būsenos galinis taškas
REPLY_AI → DI naudoja order_status ir delivery_eta, kad atsakytų

Rezultatas: Lankytojas: "Kur mano užsakymas #4521?" — DI: "Jūsų užsakymas #4521 šiuo metu siunčiamas ir turėtų atvykti iki ketvirtadienio."

Receptas: realaus laiko kainos

Ryšys: Kainų API — https://pricing.example.com — API raktas

Galinis taškas: GET /products/{'{'}productId}/price → atvaizduoja price → current_price, currency → price_currency

Taisyklė (statinė): MESSAGE_MATCHES_REGEX: /\b(price|cost|how much)\b/i

Veiksmai:

CALL_API → Kainų galinis taškas
REPLY_TEXT → "Dabartinė kaina yra {'{'}current_price} {'{'}price_currency}."

Testavimas

Visada išbandykite savo ryšius ir galinius taškus prieš naudodami juos taisyklėse:

Testuoti ryšį — patikrina, ar autentifikavimas veikia (OAuth2: gauna žetoną)
Testuoti galinį tašką — atlieka tikrą API iškvietimą su pavyzdiniais kintamaisiais ir rodo atsakymą
Testuoti taisyklę (bandomasis paleidimas) — Taisyklių puslapyje išbandykite, ar taisyklė suveiktų ir kokie veiksmai įvyktų

Patarimas: Pradėkite testuodami ryšį, tada kiekvieną galinį tašką, tada visą taisyklę. Taip galite izoliuoti problemas kiekviename lygyje.

Saugumas

Šifravimas nenaudojant — visi kredencialai šifruojami naudojant libsodium prieš saugant
Niekada neatskleidžiama — API atsakymai niekada neįtraukia iššifruotų kredencialų, tik maskuotas reikšmes
SSRF apsauga — enuchat blokuoja iškvietimus į localhost, privačius IP ir vidinius kompiuterių vardus
Laiko limitas — išoriniai API iškvietimai turi 5 sekundžių laiko limitą, kad išvengtų pakibimo
OAuth2 žetono kešavimas — prieigos žetonai saugiai kešuojami ir automatiškai atnaujinami
Nuomininkų izoliacija — ryšiai yra apriboti jūsų nuomininkui, neprieinami kitiems

Pasiruošę prijungti savo API?

Pradėkite integruoti savo sistemas su enuchat šiandien.

Pradėti nemokamai