# Lähetä viesti API-rajapinnasta

URL: https://aihio.ai/ohjekeskus/tekoalyagentti/viestirajapinta\
Kuvaus: Kutsu tekoälyagenttia palvelimeltasi, jatka samaa keskustelua ja käsittele rajapinnan virhevastaukset.

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.

> **Varoitus — Pidä API-avain palvelimellasi:**
>
> Älä sijoita avainta selainkoodiin, mobiilisovelluksen jakelupakettiin,
> URL-osoitteeseen tai versiohallintaan. Reititä oman sovelluksesi kutsut
> palvelimesi kautta ja tarkista siellä käyttäjän oikeudet. Jos avain paljastuu,
> peru se ja ota uusi avain käyttöön.

## 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:

```sh
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.

| 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ä.

```json
{
  "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

| 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

| 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](https://app.aihio.ai/api/openapi). Tämä ohje koskee viestien lähettämistä, ei agenttien tai tietolähteiden hallinnan rajapintaa.
## Seuraavat vaiheet

- [Vastaanota tapahtumia webhookilla](/ohjekeskus/tekoalyagentti/webhookit) — Siirrä agentin tapahtumia omaan järjestelmääsi ja varmista saapuvien webhook-pyyntöjen aitous.