API:n käytön aloittaminen #

Your AI Connector REST API mahdollistaa omien integraatioiden rakentamisen tilisi päälle. Voit luoda ja etsiä yhteystietoja, hallinnoida kampanjoita, UKK-osioita, tehtäviä ja tapaamisia, lähettää viestejä, rekisteröidä webhookeja, lukea analytiikkaa ja yhdistää viestintäkanavia — kaikki mitä hallintapaneelissa voi tehdä, onnistuu myös koodilla.

Tämä on API-dokumentaation keskeinen sivu. Jos yhdistät Your AI Connector-palvelun työkaluun, jossa on jo valmis integraatio, et ehkä tarvitse API:a lainkaan. API on tarkoitettu mukautettuja integraatioita ja laajamittaista automaatiota varten.

Perus-URL #

Jokainen pyyntö lähetetään samaan perusverkko-osoitteeseen, ja kaikki näiden dokumenttien polut ovat suhteellisia siihen nähden:

https://api.youraiconnector.com/v1

Joten kampanjoiden päätepiste on https://api.youraiconnector.com/v1/campaigns, yhteystietojen päätepiste on https://api.youraiconnector.com/v1/contacts, ja niin edelleen.

Kaikissa pyynnöissä on käytettävä suojattua yhteyttä (HTTPS). Tavalliset HTTP-pyynnöt hylätään.

API-avaimen hankkiminen #

API-käyttöoikeus on maksullinen ominaisuus. Jos tilauksesi ei sisällä sitä, jokainen pyyntö palauttaa 403-vastauksen, jonka runko on seuraava:

{
  "success": false,
  "error_code": 403,
  "error": "This action requires the \"api_access\" feature, which is not enabled for this account."
}

Kun API-käyttöoikeus on otettu käyttöön tilauksessasi, luo avain hallintapaneelista. Täydelliset vaiheittaiset ohjeet löytyvät kohdasta API Access — lyhyesti: siirry kohtaan Settings → Integrations → API Key luodaksesi tai luodaksesi avaimen uudelleen. API Key on oma osionsa Integrations-kohdassa, erillään Webhookeista, ja se näkyy vasta, kun API-käyttöoikeus on aktivoitu tilauksessasi. Käsittele avainta kuin salasanaa: se antaa täyden pääsyn tilillesi.

Todennus #

Voit lähettää API-avaimesi neljällä eri tavalla. Kaikki ne toimivat jokaisessa päätepisteessä, joka hyväksyy API-avaintunnistautumisen.

Tuotantokäytössä suosi jotakin otsikkomuotoa, jotta avaimesi ei koskaan päädy palvelimen lokiin tai selaimen historiaan. Kyselyparametrimuoto toimii aina ja on yksinkertaisin kertaluonteisiin testeihin.

Katso Tunnistautuminen nähdäksesi täydellisen erittelyn jokaisesta menetelmästä, esimerkkeineen ja ohjeineen siitä, milloin mitäkin kannattaa käyttää.

Ensimmäinen pyyntösi #

Tässä on täydellinen, toimiva kutsu, joka listaa tilisi kampanjat. Se käyttää API-avaintasi ja palauttaa uusimmat kampanjat ensin.

cURL

curl "https://api.youraiconnector.com/v1/campaigns?apiKey=YOUR_API_KEY&limit=10"

JavaScript

const res = await fetch("https://api.youraiconnector.com/v1/campaigns?limit=10", {
  headers: {
    "X-API-Key": "YOUR_API_KEY",
  },
});

const data = await res.json();
console.log(data.campaigns);

Python

import requests

res = requests.get(
    "https://api.youraiconnector.com/v1/campaigns",
    params={"limit": 10},
    headers={"X-API-Key": "YOUR_API_KEY"},
)

data = res.json()
print(data["campaigns"])

Onnistunut vastaus näyttää tältä:

{
  "success": true,
  "campaigns": [
    {
      "id": "NBCXrhqGPSFsd6MV7pRo",
      "name": "Inbound WhatsApp Leads",
      "type": "Incoming from Unknown Contacts",
      "status": "Live",
      "enabled": true,
      "archived": false,
      "created_at": 1700000000000,
      "ai_mode": true,
      "language": "en",
      "enabled_channels": ["whatsapp", "instagram"]
    }
  ],
  "next_cursor": null
}

Onnistumis- ja virhevastaukset #

Jokainen JSON-vastaus sisältää success-lipun, joten voit tehdä haarautumisen sen perusteella ilman tilakoodien jäsentämistä.

Onnistunut vastaus on success: true sekä kyseisen päätepisteen tiedot (kentän nimi vaihtelee — campaigns, contacts, data jne.):

{
  "success": true,
  "campaigns": []
}

Epäonnistunut vastaus on success: false, joka sisältää ihmisluettavan error-viestin ja numeerisen error_code-arvon, joka vastaa HTTP-tilaa:

{
  "success": false,
  "error": "Invalid cursor",
  "error_code": 400
}

Tarkista aina success (tai HTTP-tila) ennen tietojen lukemista. Katso Virheet ja sivutus nähdäksesi täydellisen tilakooditaulukon ja ohjeet suurten tulosjoukkojen selaamiseen.

Nopeusrajoitukset #

Todennetut pyynnöt on rajoitettu 300 pyyntöön minuutissa per API-avain. Lisäksi käytössä on laajempi 1 200 pyynnön yläraja minuutissa per tili, joka laskee jokaisen kyseiselle tilille tehdyn todennetun pyynnön.

Jos ylität kumman tahansa rajan, saat 429-vastauksen:

{
  "success": false,
  "error_code": 429,
  "error": "Rate limit exceeded. Please try again later."
}

Pidä tauko ja yritä uudelleen lyhyen odotuksen jälkeen. Voit myös tarkistaa nykyisen käyttösi milloin tahansa GET https://api.youraiconnector.com/v1/api-keys/usage-kutsulla, joka palauttaa tiedon siitä, kuinka monta pyyntöä olet käyttänyt nykyisessä ikkunassa ja milloin se nollautuu — tämä on hyödyllistä asiakaspuolen rajoitusten rakentamisessa. Katso API-avaimet.

Resurssioppaat #

Alla olevilla resurssiryhmillä on kullakin oma oppaansa, joka sisältää tarkat polut, pyyntökentät ja vastausmuodot.

Agentit, sisääntulopisteet ja lähetykset #

AI-agentit, sisääntulopisteet ja lähetykset ovat kaikki julkaistussa OpenAPI-määrityksessä, joten voit selata niiden tarkkoja kenttiä ja suorittaa niitä vastaan live-pyyntöjä API-selaimessa. Jokaisella on oma oppaansa: AI-agentit, Sisääntulopisteet ja Lähetykset.

Näiden ohjeiden lukeminen Markdown-muodossa #

Jokaisella tämän dokumentaation sivulla on Markdown-vastine: lisää sivun osoitteen loppuun /index.md. Tämä sivu on siis saatavilla myös osoitteesta https://docs.youraiconnector.com/api/getting-started/index.md, ja se palautuu selkeänä tekstinä verkkosivun sijaan – tämä on kätevää, kun haluat liittää sivun tekoälyavustajaan tai hakea sen skriptiin.

Voit selata koko aineistoa aloittamalla osoitteesta https://docs.youraiconnector.com/sitemap.xml, joka listaa kaikki julkaisemamme sivut. Huomaa, että dokumentaatio on tarkoituksella jätetty hakukoneiden ulkopuolelle, joten näiden osoitteiden suora hakeminen on oikea tapa käyttää niitä koodista käsin.

Dokumentaatiolle ei ole vielä avainten suojaamaa päätepistettä eikä massalatausmahdollisuutta – Markdown-vastineet ja sivukartta muodostavat koko rajapinnan, eikä kumpikaan niistä vaadi API-avainta.

Seuraavat vaiheet #

• Todennus — valitse integraatiollesi oikea todennusmenetelmä.
• Virheet ja sivutus — käsittele virheet ja selaa tuloksia sivuittain.
• API-pääsy — luo avaimesi ja katso käytännön esimerkkejä.