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:

Tunnistautuminen API-avaimella
AI-agentin luominen ja sen avustajakäyttäytymisen määrittäminen
Viestintäkanavan yhdistäminen (käytämme WhatsApp Webiä esimerkkinä) ja sen osoittaminen agentille
Yhteystietojen tuominen
Viestien lähettäminen ja lukeminen
Analytiikan lukeminen
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 varmistaaksesi, että se on käytössä, ja Todentaminen 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.

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

curl "https://api.youraiconnector.com/v1/health?apiKey=YOUR_API_KEY"

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

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

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

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

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:

{
  "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:

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.

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

curl "https://api.youraiconnector.com/v1/channels?apiKey=YOUR_API_KEY"

Kunkin kanavan täydelliset yhdistämis- ja katkaisuvirrat on dokumentoitu Kanavaoppaassa. 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.

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" }'

await fetch(`${BASE}/channels/whatsapp-web/connections`, {
  method: "POST",
  headers,
  body: JSON.stringify({ phone_number: "+15551230000" }),
});

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.

curl "https://api.youraiconnector.com/v1/channels/whatsapp-web/connections/+15551230000/qr?apiKey=YOUR_API_KEY"

{
  "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 <img src="...">-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ä.

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)

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:

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

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

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

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:

{
  "success": true,
  "imported": 2,
  "contact_ids": ["contactId1", "contactId2"],
  "skipped": []
}

Yksittäisten luontien, listauksen/haun, listojen, tunnisteiden ja mukautettujen kenttien osalta katso Yhteystieto-opas.

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

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

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

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

{
  "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.

curl "https://api.youraiconnector.com/v1/contacts/contact123/messages?limit=50&apiKey=YOUR_API_KEY"

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

curl "https://api.youraiconnector.com/v1/analytics/summary?from=2026-05-01&to=2026-05-31&campaign_id=abc123campaign&apiKey=YOUR_API_KEY"

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();

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.

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:

curl "https://api.youraiconnector.com/v1/webhooks/events?apiKey=YOUR_API_KEY"

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

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

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

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"]

{
  "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 ja integraatiotason Webhookit-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 · Yhteystiedot · UKK · Viestit · Tapaamiset
Kanavat · Mallipohjat · Analytiikka · Webhookit · API-avaimet
Oletko uusi täällä? Aloittaminen · Todennus · Virheet ja sivutus

Stuck on something this guide does not cover? Email hi@youraiconnector.com.

Rakenna integraatio päästä päähän #

Vaihe 1 — Hanki API-avain ja tee ensimmäinen pyyntösi #

Vaihe 2 — Luo AI-agentti #

Määritä avustaja #

Vaihe 3 — Yhdistä kanava #

Esimerkki: WhatsApp Webin pariliittäminen QR-koodilla #

Reititä kanava agentillesi #

Vaihe 4 — Tuo yhteystietosi #

Vaihe 5 — Lähetä ja lue viestejä #

Lähetä viesti #

Lue keskustelu #

Vaihe 6 — Lue analytiikka #

Vaihe 7 — Tilaa webhookit reaaliaikaisia tapahtumia varten #

Kaiken kokoaminen yhteen #

Rakenna integraatio päästä päähän

Vaihe 1 — Hanki API-avain ja tee ensimmäinen pyyntösi

Vaihe 2 — Luo AI-agentti

Määritä avustaja

Vaihe 3 — Yhdistä kanava

Esimerkki: WhatsApp Webin pariliittäminen QR-koodilla

Reititä kanava agentillesi

Vaihe 4 — Tuo yhteystietosi

Vaihe 5 — Lähetä ja lue viestejä

Lähetä viesti

Lue keskustelu

Vaihe 6 — Lue analytiikka

Vaihe 7 — Tilaa webhookit reaaliaikaisia tapahtumia varten

Kaiken kokoaminen yhteen