Lähetä viesti API-rajapinnasta

Kutsu tekoälyagenttia palvelimeltasi, jatka samaa keskustelua ja käsittele rajapinnan virhevastaukset.

Avaa kopiointivalikko

Viestirajapinnalla oma sovelluksesi voi lähettää kysymyksen Aihion tekoälyagentille ja vastaanottaa vastauksen JSON-muodossa. Rajapinta ei edellytä keskusteluikkunan upottamista.

Ennen aloittamista

Tarvitset julkaistun agentin tunnisteen ja saman työtilan API-avaimen. Tarkista API-avainten saatavuus omasta tilauksestasi ja luo avain Oma Aihio -palvelun integraatioasetuksissa.

Lähetä ensimmäinen viesti

Aseta palvelinympäristöön AIHIO_API_KEY ja AIHIO_AGENT_ID. Ensimmäinen sisältää salaisen API-avaimen, toinen agentin UUID-tunnisteen. Aja seuraava komento palvelimellasi tai turvallisessa paikallisessa terminaalissa:

curl --fail-with-body https://app.aihio.ai/api/v1/messages \
  -H "x-api-key: ${AIHIO_API_KEY}" \
  -H 'Content-Type: application/json' \
  --data "{\"chatbot_id\":\"${AIHIO_AGENT_ID}\",\"message\":\"Mistä saan apua palvelun käyttöön?\"}"

Onnistunut vastaus sisältää conversation_id-tunnisteen ja message-vastauksen. Kutsu käyttää palvelua ja sen käyttömäärää; se ei ole maksuton yhteystesti. Älä lähetä samaa viestiä toistuvasti pelkästään yhteyden tarkistamiseksi.

Pyynnön kentät

Osoite on POST /api/v1/messages. Tunnistautuminen tapahtuu x-api-key-otsakkeella, ei Bearer-tokenilla.

Pyynnön kentät
Kenttä	Pakollinen	Sisältö
`chatbot_id`	Kyllä	API-avaimen työtilaan kuuluvan agentin UUID.
`message`	Kyllä	Viesti, 1–10 000 merkkiä.
`conversation_id`	Ei	Edellisestä vastauksesta saatu keskustelutunniste.
`external_user_id`	Ei	Oman järjestelmäsi käyttäjätunniste, enintään 255 merkkiä. Ei yksin todista henkilöllisyyttä.
`metadata`	Ei	JSON-objekti lisätiedoille. Älä lähetä salaisuuksia tai tarpeettomia henkilötietoja.

Jatka keskustelua

Tallenna ensimmäisen vastauksen conversation_id oman sovelluksesi käyttäjäkohtaiseen tilaan. Lähetä se seuraavan viestin mukana. Älä jaa tunnistetta käyttäjien kesken tai ota sitä luotettuna arvona toiselta käyttäjältä.

{
  "chatbot_id": "00000000-0000-4000-8000-000000000001",
  "message": "Voitko tarkentaa edellistä vastausta?",
  "conversation_id": "EDELLISEN_VASTAUKSEN_TUNNISTE"
}

Korvaa esimerkin UUID oman agenttisi tunnisteella ja conversation_id todellisen vastauksen arvolla. Aloita uusi keskustelu jättämällä keskustelutunniste pois.

Vastauksen tulkinta

Vastauksen tulkinta
Kenttä	Käyttö
`conversation_id`	Seuraavan viestin liittäminen samaan keskusteluun.
`message`	Agentin vastausteksti.
`sources`	Vastaukseen liittyvät lähdetiedot, kun niitä on.
`follow_ups`	Ehdotetut jatkokysymykset, kun niitä on.
`tokens`	Vastauksen mukana palautuva tokenien käyttötieto.
`timing`	Mahdollinen käsittelyn ajoitustieto.

Rajapinta palauttaa kokonaisen JSON-vastauksen, ei vaiheittain saapuvaa tekstivirtaa. Tee sovellukseesi odotus- ja virhetila äläkä oleta lähteitä tai jatkokysymyksiä olevan jokaisessa vastauksessa.

Virheestä palautuminen

Virheestä palautuminen
HTTP-tila	Tarkista
`400`	JSON-rakenne, kenttien nimet ja viestin pituus.
`401`	API-avain, otsakkeen nimi ja avaimen voimassaolo.
`402`	Käyttömäärä ja käytettävissä oleva saldo.
`403`	Mallin käyttöoikeus tai agentin identiteettivaatimus.
`404`	Agentin tunniste ja kuuluminen API-avaimen työtilaan.
`422`	Pyynnön estänyt turvarajaus; älä kierrä sitä automaattisilla muunnelmilla.
`429`	Pyyntötahti; hidasta kutsuja ja huomioi vastauksen rajoitusotsakkeet.
`500`	Palveluvirhe; näytä palautumisohje ja säilytä pyynnön tunniste tukiselvitystä varten.

Aikakatkaisu ei todista, ettei viestiä käsitelty. Rajapinta ei tarjoa tässä pyynnössä idempotenssiavainta: sokea uudelleenlähetys voi tuottaa uuden vastauksen ja lisää käyttöä. Virherungon muoto voi vaihdella esimerkiksi identiteettivirheissä, joten käsittele myös HTTP-tila.

Tarkka koneellisesti luettava kuvaus on Aihion OpenAPI-kuvauksessa . Tämä ohje koskee viestien lähettämistä, ei agenttien tai tietolähteiden hallinnan rajapintaa.