# Rakenna integraatio päästä päähän Tämä opas käy läpi kaiken tarvittavan, jotta voit käyttää Your AI Connector-palvelua omasta koodistasi avaamatta kertaakaan hallintapaneelia. Tämän oppaan lopussa olet rakentanut minimaalisen integraation, joka: 1. Tunnistautuminen API-avaimella 2. AI-agentin luominen ja sen avustajakäyttäytymisen määrittäminen 3. Viestintäkanavan yhdistäminen (käytämme WhatsApp Webiä esimerkkinä) ja sen osoittaminen agentille 4. Yhteystietojen tuominen 5. Viestien lähettäminen ja lukeminen 6. Analytiikan lukeminen 7. Webhookien tilaaminen reaaliaikaisia tapahtumia varten Jokainen vaihe linkittää täydelliseen resurssioppaaseen, jotta voit perehtyä yksityiskohtiin tarvittaessa. Tämä sivu on kartta; resurssioppaat ovat maasto. > **Ennen kuin aloitat.** API-käyttöoikeus on maksullinen ominaisuus. Jos tilauksesi ei sisällä sitä, jokainen pyyntö palauttaa `403`-vastauksen. Katso [API-käyttöoikeus](../integrations/api-access.md) varmistaaksesi, että se on käytössä, ja [Todentaminen](authentication.md) nähdäksesi kaikki tavat välittää avaimesi. Kaikki alla olevat polut ovat suhteessa perus-URL-osoitteeseen: ``` https://api.youraiconnector.com/v1 ``` --- ## Vaihe 1 — Hanki API-avain ja tee ensimmäinen pyyntösi API-avaimesi löytyy sovelluksesta kohdasta **Asetukset → Integraatiot → API-avain** — se on oma osionsa Integraatioiden alla, erillään Webhookeista, ja se näkyy vain, jos API-käyttöoikeus sisältyy tilaukseesi. Luo avain, kopioi se ja tallenna se turvalliseen paikkaan (palvelinpuolen salaisuuksien hallintaan tai ympäristömuuttujaan — ei koskaan selainkoodiin). Täydelliset ohjeet löytyvät kohdasta [API-käyttöoikeus](../integrations/api-access.md). Kun sinulla on avain, varmista sen toimivuus kutsumalla health-päätepistettä. Avaimen lähettämiseen on useita tapoja; yksinkertaisin on `?apiKey=`-kyselyparametri, mutta oikeassa koodissa kannattaa suosia `X-API-Key`-otsikkoa, jotta avain ei päädy palvelinlokeihin tai selaimen historiaan. **cURL** ```bash curl "https://api.youraiconnector.com/v1/health?apiKey=YOUR_API_KEY" ``` **JavaScript** ```javascript const BASE = "https://api.youraiconnector.com/v1"; const headers = { "X-API-Key": "YOUR_API_KEY", "Content-Type": "application/json" }; const res = await fetch(`${BASE}/health`, { headers }); const data = await res.json(); console.log(data); // { "success": true, ... } ``` **Python** ```python import requests BASE = "https://api.youraiconnector.com/v1" HEADERS = {"X-API-Key": "YOUR_API_KEY", "Content-Type": "application/json"} res = requests.get(f"{BASE}/health", headers=HEADERS) print(res.json()) # { "success": true, ... } ``` Jokainen onnistunut vastaus on kääritty samaan kirjekuoreen — `success: true`-kenttä ja tulosdata. Virheet palauttavat `success: false`-vastauksen, jossa on `error`-viesti ja `error_code`. Katso [Virheet ja sivutus](errors-and-pagination.md) nähdäksesi täydellisen luettelon sekä tiedot siitä, miten listojen päätepisteet sivutetaan `?limit`- ja `?cursor`-parametreilla. > **Nopeusrajoitus.** Todennetut pyynnöt on rajoitettu **300 pyyntöön minuutissa** (tilikohtainen yläraja on 1 200 pyyntöä minuutissa). Rajoituksen ylittäminen palauttaa `429`; odota hetki ja yritä uudelleen. --- ## Vaihe 2 — Luo AI-agentti **AI-agentti** on yksikkö, joka sisältää avustajasi käyttäytymisen: sen ohjeet, tavoitteen, aktiiviset tunnit ja tavan, jolla se keskustelee yhteystietojen kanssa. Se vastaa keskusteluihin, joten tämä on luonnollinen ensimmäinen askel. Luo sellainen käyttämällä `POST /agents`. `name` on ainoa kenttä, joka kannattaa lähettää heti alussa; kaiken muun voi määrittää alla olevalla bot-config-kutsulla. **cURL** ```bash curl -X POST "https://api.youraiconnector.com/v1/agents" \ -H "X-API-Key: YOUR_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "name": "Inbound WhatsApp Leads", "language": "en" }' ``` **JavaScript** ```javascript const res = await fetch(`${BASE}/agents`, { method: "POST", headers, body: JSON.stringify({ name: "Inbound WhatsApp Leads", language: "en", }), }); const { agent_id } = await res.json(); ``` **Python** ```python res = requests.post( f"{BASE}/agents", headers=HEADERS, json={"name": "Inbound WhatsApp Leads", "language": "en"}, ) agent_id = res.json()["agent_id"] ``` Onnistunut luonti palauttaa `201`-vastauksen ja uuden tunnisteen: ```json { "success": true, "agent_id": "abc123agent" } ``` **Tallenna `agent_id`** — viittaat siihen, kun reitität kanavia. ### Määritä avustaja `PUT /agents/{agentId}/bot-config` määrittää avustajan käyttäytymisen. Se *yhdistää* lähettämäsi kentät olemassa olevaan konfiguraatioon, joten kaikki, mitä jätät pois, säilyy ennallaan: ```bash curl -X PUT "https://api.youraiconnector.com/v1/agents/abc123agent/bot-config" \ -H "X-API-Key: YOUR_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "instructions": "Greet warmly, answer questions about our services, and offer to book a call.", "goal": "Book a discovery call.", "ai_speed": "balanced" }' ``` Aseta aktiiviset tunnit `PUT /agents/{agentId}/active-hours`-toiminnolla, jotta avustaja vastaa vain työaikana; näiden aikojen ulkopuolella se ei vastaa automaattisesti. > **Tietokanta.** Jos haluat avustajan vastaavan oman sisältösi perusteella, liitä mukaan UKK-osio. Katso [UKK-opas](faqs.md). > **Vanha versio: perinteiset kampanjat.** Tilit, joilla on edelleen **Kampanjat**-sivu, luovat saman avustajakäyttäytymisen kampanjaan (`POST /campaigns`, jossa on `type` ja `bot`-objekti, sitten `PUT /campaigns/{campaignId}/bot-config`). Täydellinen kampanjakenttien luettelo ja elinkaaren hallinta löytyvät [Kampanjat-oppaasta](campaigns.md). Jos rakennat jotain uutta, luo agentti. --- ## Vaihe 3 — Yhdistä kanava Agentti tarvitsee tavan lähettää ja vastaanottaa viestejä. Seitsemän yhteysvirtaa voidaan ohjata API:n kautta: WhatsApp Business, WhatsApp Web, Instagram ja Messenger yhdessä (yksi jaettu Meta-virta), Instagram-henkilökohtaiset tilit, Telegram, LINE ja Viber. Muut kanavat — kuten SMS, sähköposti, chat-widget ja mukautetut kanavat — määritetään hallintapaneelissa REST-rajapinnan sijaan. Kun ne on yhdistetty, viestintä-, yhteystieto- ja reitityspäätepisteet toimivat niissä täsmälleen samalla tavalla. `GET /channels` on reaaliaikainen lähde sille, mitä kyseisellä tilillä on todellisuudessa yhdistettynä: ```bash curl "https://api.youraiconnector.com/v1/channels?apiKey=YOUR_API_KEY" ``` Kunkin kanavan täydelliset yhdistämis- ja katkaisuvirrat on dokumentoitu [Kanavaoppaassa](channels.md). Alla käymme läpi **WhatsApp Webin** alusta loppuun, koska se havainnollistaa kiinnostavimman mallin: QR-koodilla tapahtuvan pariliitoksen, joka kääreohjelmasi on renderöitävä ja jota sen on kyseltävä. ### Esimerkki: WhatsApp Webin pariliittäminen QR-koodilla WhatsApp Webin pariliittäminen on kolmivaiheinen prosessi: **aloitus**, **QR-koodin haku** ja **tilan kysely yhteyden muodostumiseen asti**. **1. Aloita pariliitosistunto.** Anna yhdistettävä numero E.164-muodossa. ```bash curl -X POST "https://api.youraiconnector.com/v1/channels/whatsapp-web/connections" \ -H "X-API-Key: YOUR_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "phone_number": "+15551230000" }' ``` ```javascript await fetch(`${BASE}/channels/whatsapp-web/connections`, { method: "POST", headers, body: JSON.stringify({ phone_number: "+15551230000" }), }); ``` ```python requests.post( f"{BASE}/channels/whatsapp-web/connections", headers=HEADERS, json={"phone_number": "+15551230000"}, ) ``` **2. Hae QR-koodi ja näytä se käyttäjälle.** Kysy tätä 10–15 sekunnin välein. Vastaus sisältää raa'an `qr_code`-hyötykuorman (renderöi se itse QR-kuvaksi) ja valmiiksi näytettävän `qr_data_url`-koodin. ```bash curl "https://api.youraiconnector.com/v1/channels/whatsapp-web/connections/+15551230000/qr?apiKey=YOUR_API_KEY" ``` ```json { "success": true, "phone_number": "+15551230000", "status": "qr_pending", "qr_code": "2@abc...", "qr_data_url": "data:image/png;base64,iVBORw0KGgo..." } ``` Lisää kääreohjelmasi käyttöliittymässä `qr_data_url` suoraan ``-elementtiin ja pyydä käyttäjää skannaamaan se puhelimensa kohdasta **WhatsApp → Linkitetyt laitteet**. Jos QR-koodi vanhenee (`410`-vastaus), aloita alusta vaiheesta 1 saadaksesi uuden koodin. **3. Kysy tilaa, kunnes yhteys muodostuu.** Kun käyttäjä on skannannut koodin, jatka tilan kyselyä päätepisteestä, kunnes se raportoi `connected` (palvelu voi myös raportoida `open`). Käsittele tilat `disconnected` ja `not_initialized` lopullisina virheinä. ```python import time PHONE = "+15551230000" while True: res = requests.get( f"{BASE}/channels/whatsapp-web/connections/{PHONE}/status", headers=HEADERS, ) status = res.json()["status"] if status in ("connected", "open"): print("Connected!") break if status in ("disconnected", "not_initialized"): raise RuntimeError(f"Pairing failed: {status}") time.sleep(5) ``` ```javascript async function waitForConnection(phone) { while (true) { const res = await fetch( `${BASE}/channels/whatsapp-web/connections/${encodeURIComponent(phone)}/status`, { headers } ); const { status } = await res.json(); if (status === "connected" || status === "open") return; if (status === "disconnected" || status === "not_initialized") { throw new Error(`Pairing failed: ${status}`); } await new Promise((r) => setTimeout(r, 5000)); } } ``` > **Huomio.** Jokaisesta yhdistetystä WhatsApp Web -numerosta peritään toistuva kuukausittainen ylläpitomaksu, kunnes katkaiset yhteyden (`DELETE /channels/whatsapp-web/connections/{phoneNumber}`). ### Reititä kanava agentillesi Kanavan yhdistäminen saa sen toimimaan; reitittäminen kertoo alustalle, *mikä AI-agentti* vastaa uusiin saapuviin keskusteluihin kyseisessä kanavassa. Aseta kanavan oletusarvoinen sisääntulopiste (Entry Point) ja nimeä vaiheessa 2 luomasi agentti: ```bash curl -X PUT "https://api.youraiconnector.com/v1/entry-points/channel-defaults" \ -H "X-API-Key: YOUR_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "channel": "whatsapp_web", "agent_id": "abc123agent" }' ``` Toista kutsu jokaiselle kanavalle — yksi kanavan oletusarvo per kanava. Jos haluat jättää kanavan ilman vastaavaa agenttia, kutsu `DELETE /entry-points/channel-defaults?channel=whatsapp_web`; tarkistaaksesi, onko tilin sisääntulopisteiden järjestelmä käytössä, kutsu `GET /entry-points/routing-status`. Vanhempi `POST /channels/campaign`-kartta on säilytetty vain palautusta varten, eikä sitä enää käytetä saapuvaan reititykseen. Katso [Kanavat-opas](channels.md) muille kanavatyypeille ja WhatsApp Business OAuth -virralle. --- ## Vaihe 4 — Tuo yhteystietosi Kun kanava on käytössä, lataa ihmiset, jotka haluat tavoittaa. Tuontirajapinta hyväksyy enintään **500 tietuetta kutsua kohden**. Jokainen tietue tarvitsee `phone_number`-kentän kansainvälisessä muodossa; kaikki muu on valinnaista. Tietueet, joissa on virheellisiä numeroita, tukemattomia kanavia tai jo olemassa olevia numeroita, ohitetaan – ja jokaisesta ohituksesta raportoidaan sen indeksi ja syy, jotta voit yrittää uudelleen vain epäonnistuneiden kohdalla. **cURL** ```bash curl -X POST "https://api.youraiconnector.com/v1/contacts/import" \ -H "X-API-Key: YOUR_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "contacts": [ { "phone_number": "+12025551234", "first_name": "Ann", "last_name": "Lee" }, { "phone_number": "+12025551235", "first_name": "Bob" } ], "defaultChannel": "whatsapp_web" }' ``` **JavaScript** ```javascript const res = await fetch(`${BASE}/contacts/import`, { method: "POST", headers, body: JSON.stringify({ contacts: [ { phone_number: "+12025551234", first_name: "Ann", last_name: "Lee" }, { phone_number: "+12025551235", first_name: "Bob" }, ], defaultChannel: "whatsapp_web", }), }); const result = await res.json(); console.log(`${result.imported} imported, ${result.skipped.length} skipped`); ``` **Python** ```python res = requests.post( f"{BASE}/contacts/import", headers=HEADERS, json={ "contacts": [ {"phone_number": "+12025551234", "first_name": "Ann", "last_name": "Lee"}, {"phone_number": "+12025551235", "first_name": "Bob"}, ], "defaultChannel": "whatsapp_web", }, ) result = res.json() print(f"{result['imported']} imported, {len(result['skipped'])} skipped") ``` Vastaus kertoo tarkalleen, mitä tapahtui: ```json { "success": true, "imported": 2, "contact_ids": ["contactId1", "contactId2"], "skipped": [] } ``` Yksittäisten luontien, listauksen/haun, listojen, tunnisteiden ja mukautettujen kenttien osalta katso [Yhteystieto-opas](contacts.md). --- ## Vaihe 5 — Lähetä ja lue viestejä ### Lähetä viesti Yksinkertaisin lähetys on **kanavariippumaton**: anna yhteystiedon identiteetti ja viestin runko, niin alusta toimittaa sen millä tahansa kanavalla, jossa yhteystieto on. Voit kohdistaa viestin `contact_id`-tunnisteella tai `channel`-tunnisteella ja vastaavalla identiteettikentällä (`phone_number` WhatsAppille/WhatsApp Webille/SMS-viesteille, `instagram_id` Instagramille ja niin edelleen). **cURL** ```bash curl -X POST "https://api.youraiconnector.com/v1/contacts/send" \ -H "X-API-Key: YOUR_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "channel": "whatsapp_web", "phone_number": "+12025551234", "body": "Hi Ann! Thanks for reaching out." }' ``` **JavaScript** ```javascript const res = await fetch(`${BASE}/contacts/send`, { method: "POST", headers, body: JSON.stringify({ channel: "whatsapp_web", phone_number: "+12025551234", body: "Hi Ann! Thanks for reaching out.", }), }); const { message_id } = await res.json(); ``` **Python** ```python res = requests.post( f"{BASE}/contacts/send", headers=HEADERS, json={ "channel": "whatsapp_web", "phone_number": "+12025551234", "body": "Hi Ann! Thanks for reaching out.", }, ) message_id = res.json()["message_id"] ``` Toimitus on **asynkroninen** — `201` tarkoittaa, että viesti on *vastaanotettu ja asetettu jonoon*, ei vielä toimitettu. (Yhteystiedot, joilla on käytössä älä häiritse -tila tai yksityinen tila, hylätään `422`-vastauksella.) ```json { "success": true, "message_id": "aB3dE5fG7hI9jK1lM2nO", "contact_id": "contact123", "channel": "whatsapp_web" } ``` ### Lue keskustelu Voit lukea viestejä takaisin listaamalla ne yhteystiedon mukaan, uusimmasta alkaen, käyttäen kursorisivutusta. Välitä `next_cursor` yhdestä vastauksesta seuraavan vastauksen `cursor`-kenttään selataksesi historiaa taaksepäin. ```bash curl "https://api.youraiconnector.com/v1/contacts/contact123/messages?limit=50&apiKey=YOUR_API_KEY" ``` ```python res = requests.get( f"{BASE}/contacts/contact123/messages", headers=HEADERS, params={"limit": 50}, ) page = res.json() for msg in page["messages"]: print(msg) next_cursor = page["next_cursor"] # pass back as ?cursor= for the next page ``` Voit myös suodattaa sisällön tyypin (`?filter=text|media|tool_use`) tai suunnan (`?direction=inbound|outbound`) mukaan. [Viestiopas](messages.md) kattaa medialiitteet, viestien merkitsemisen luetuiksi ja istuntokohtaiset viestinäkymät. > **Älä kyselypohjaisesti tarkista vastauksia.** Viestien listaaminen ajastimella toimii, mutta se tuhlaa pyyntöjä ja aiheuttaa viivettä. Käytä saapuville viesteille sen sijaan webhookeja – se on vaihe 7. --- ## Vaihe 6 — Lue analytiikka Kun viestit kulkevat, analytiikkayhteenveto antaa sinulle kootut määrät valitulta ajanjaksolta: lähetetyt, toimitetut, luetut, vastatut, varatut, luodut yhteystiedot sekä käytetyt/ladatut krediitit. Saat sekä ajanjakson kokonaissummat että nollilla täytetyn päiväkohtaisen sarjan – mikä sopii täydellisesti kojelaudan kaavioon. Voit halutessasi rajata tiedot yhteen kampanjaan käyttämällä `campaign_id` (alla olevissa esimerkeissä käytetään paikkamerkkinä kampanjatunnusta `abc123campaign`); jätä parametri pois, jos haluat koko tilin kattavat kokonaissummat. ```bash curl "https://api.youraiconnector.com/v1/analytics/summary?from=2026-05-01&to=2026-05-31&campaign_id=abc123campaign&apiKey=YOUR_API_KEY" ``` ```javascript const params = new URLSearchParams({ from: "2026-05-01", to: "2026-05-31", campaign_id: "abc123campaign", }); const res = await fetch(`${BASE}/analytics/summary?${params}`, { headers }); const { totals, by_date } = await res.json(); ``` ```python res = requests.get( f"{BASE}/analytics/summary", headers=HEADERS, params={"from": "2026-05-01", "to": "2026-05-31", "campaign_id": "abc123campaign"}, ) data = res.json() totals = data["totals"] by_date = data["by_date"] ``` Ajanjakson oletusarvo on viimeiset 30 päivää, ja se on rajoitettu 366 päivään. Krediittikohtaiset käyttöhistoriat ja tekoälyn kustannuserittelyt löytyvät [analytiikkaoppaasta](analytics.md). --- ## Vaihe 7 — Tilaa webhookit reaaliaikaisia tapahtumia varten Kysely (polling) sopii nopeaan skriptiin, mutta kunnollisen integraation tulisi olla **push-pohjainen**. Webhookien avulla alusta voi kutsua *sinun* palvelintasi heti, kun jotain tapahtuu – uusi yhteystieto, vastaus, varattu tapaaminen tai päättynyt keskustelu. Selvitä ensin tarkat tapahtumanimet, joita voit tilata: ```bash curl "https://api.youraiconnector.com/v1/webhooks/events?apiKey=YOUR_API_KEY" ``` ```json { "success": true, "events": [ "Contact Created", "Human Alerted", "Appointment Booked", "Replies", "New Message", "Chat Concluded", "Task Created", "Daily Summary Created" ] } ``` Luo sitten tilaus, joka osoittaa palvelimesi HTTPS-URL-osoitteeseen. Käytä yllä olevan kutsun tarkkoja tapahtumamerkkijonoja. **cURL** ```bash curl -X POST "https://api.youraiconnector.com/v1/webhooks" \ -H "X-API-Key: YOUR_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "url": "https://hooks.example.com/incoming", "subscribed_to": ["Contact Created", "Replies"], "name": "Lead updates hook" }' ``` **JavaScript** ```javascript const res = await fetch(`${BASE}/webhooks`, { method: "POST", headers, body: JSON.stringify({ url: "https://hooks.example.com/incoming", subscribed_to: ["Contact Created", "Replies"], name: "Lead updates hook", }), }); const { webhook_id } = await res.json(); ``` **Python** ```python res = requests.post( f"{BASE}/webhooks", headers=HEADERS, json={ "url": "https://hooks.example.com/incoming", "subscribed_to": ["Contact Created", "Replies"], "name": "Lead updates hook", }, ) webhook_id = res.json()["webhook_id"] ``` ```json { "success": true, "webhook_id": "1", "webhook": { "id": "1", "name": "Lead updates hook", "url": "https://hooks.example.com/incoming", "subscribed_to": ["Contact Created", "Replies"], "subscribed_to_tags": [], "created_at": "2026-06-09T12:00:00.000Z" } } ``` URL-osoitteen on käytettävä HTTPS-yhteyttä ja oltava julkisesti tavoitettavissa. Tästä eteenpäin palvelimesi vastaanottaa POST-pyynnön jokaisesta tilatusta tapahtumasta. Voit lähettää testitoimituksen, tarkistaa tilauksen tilan ja ottaa uudelleen käyttöön tilauksen, joka on poistettu käytöstä toistuvien virheiden vuoksi – katso [Webhook-opas](webhooks.md) ja integraatiotason [Webhookit](../integrations/webhooks.md)-sivu hyötykuormien rakenteita ja vahvistusta varten. --- ## Kaiken kokoaminen yhteen Tässä on koko prosessi yhdellä silmäyksellä: | Vaihe | Tavoite | Avainkutsu | |---|---|---| | 1 | Tunnistaudu | `GET /health` | | 2 | Luo ja hienosäädä avustaja | `POST /agents`, `PUT /agents/{id}/bot-config`, `PUT /agents/{id}/active-hours` | | 3 | Yhdistä kanava ja reititä se | `POST /channels/whatsapp-web/connections` → kysy QR + tila → `PUT /entry-points/channel-defaults` | | 4 | Lataa yhteystiedot | `POST /contacts/import` | | 5 | Lähetä ja lue | `POST /contacts/send`, `GET /contacts/{id}/messages` | | 6 | Mittaa | `GET /analytics/summary` | | 7 | Reagoi reaaliajassa | `POST /webhooks` | Minimaalinen kääre on vain nämä seitsemän kutsua liitettynä omaan käyttöliittymääsi. Sen jälkeen voit lisätä resurssikohtaisia oppaita tarpeen mukaan: - [Kampanjat](campaigns.md) · [Yhteystiedot](contacts.md) · [UKK](faqs.md) · [Viestit](messages.md) · [Tapaamiset](appointments.md) - [Kanavat](channels.md) · [Mallipohjat](templates.md) · [Analytiikka](analytics.md) · [Webhookit](webhooks.md) · [API-avaimet](api-keys.md) - Oletko uusi täällä? [Aloittaminen](getting-started.md) · [Todennus](authentication.md) · [Virheet ja sivutus](errors-and-pagination.md) Stuck on something this guide does not cover? Email [hi@youraiconnector.com](mailto:hi@youraiconnector.com).