API-käyttöoikeus #

API (Application Programming Interface) on tapa, jolla eri ohjelmistojärjestelmät voivat kommunikoida keskenään. Your AI Connector-rajapinnan avulla voit (tai kehittäjäsi voi) luoda yhteystietoja, lähettää viestejä, hallita listoja ja vastaanottaa saapuvia viestejä mukautetuista kanavista automaattisesti – ilman, että sinun tarvitsee käyttää hallintapaneelia.

Miksi käyttää APIa? Jos haluat yhdistää sovelluksen työkaluun, jolla ei ole sisäänrakennettua integraatiota, tai jos sinun on automatisoitava toistuvia tehtäviä laajassa mittakaavassa, API on oikea tapa toimia.

API-avaimen luominen #

1. Napsauta vasemmasta sivupalkista Asetukset (rataskuvake).
2. Napsauta Asetukset-sivupalkin Integraatiot-ryhmän alta API-avain.

3. Jos sinulla ei vielä ole avainta, napsauta Generate API key.
4. Jos sinulla on jo avain, se näkyy peitettynä kohdassa Your key. Jos avain tukee sitä, napsauta Show nähdäksesi sen ja sitten Copy kopioidaksesi sen – näet vahvistusilmoituksen.
5. Säilytä avain turvallisessa paikassa – tarvitset sitä jokaisessa API-pyynnössä.

Tiimin jäsenet: API-avain kuuluu tilin omistajalle, joten jos olet kirjautunut sisään kutsuttuna tiimin jäsenenä (mukaan lukien järjestelmänvalvoja), osiossa näkyy huomautus avaimen sijaan. Kirjaudu sisään tilin omistajana nähdäksesi, kopioidaksesi tai luodaksesi avaimen uudelleen – tämä koskee myös rajattuja avaimia.

Mistä se löytyy: API-avain on oma osionsa Asetukset → Integraatiot -kohdassa, erillään Webhookeista. Jos opas tai kollega kehottaa etsimään avainta “Webhookit”-kohdasta, katso sen sijaan viereisestä osiosta.

Rajatut avaimet: lisäavaimet tiettyä tehtävää varten #

Pääavaimesi voi tehdä kaiken, joten se ei ole oikea avain annettavaksi raportille, asiakkaan hallintapaneelille tai erilliselle hiekkalaatikko- ja kehitysympäristölle. Luo sitä varten rajattuja avaimia (scoped keys) Rajatut avaimet -kortissa, samassa API-avain-osiossa Oma avaimesi -kohdan alapuolella:

1. Napsauta Uusi avain.
2. Anna sille Nimi, jonka tunnistat myöhemmin, esimerkiksi “Hiekkalaatikko” tai “Acme-asiakkaan hallintapaneeli”.
3. Valitse kohdasta Mitä se voi nähdä vain ne alueet, joita se tarvitsee.
4. Jätä kohdassa Mitä se voi tehdä valinnaksi Vain luku, ellei työkalun tarvitse tehdä muutoksia. Avain, joka voi tehdä muutoksia, voi lähettää viestejä ja muokata asetuksiasi.
5. Voit halutessasi asettaa Pyyntöä minuutissa -rajan (sen oma rajoitus, joten se ei koskaan hidasta muita integraatioitasi) sekä Vanhenee-päivämäärän.
6. Napsauta Luo avain ja kopioi se heti. Rajatut avaimet näytetään vain kerran; jos kadotat avaimen, peruuta se ja luo uusi.

Voit luoda niin monta avainta kuin tarvitset. Jokaisessa listan avaimessa näkyy, milloin sitä on viimeksi käytetty, ja Peruuta avain -toiminto estää sen toiminnan välittömästi. Rajatun avaimen luominen tai peruuttaminen ei koskaan vaikuta pääavaimeesi. Täydelliset vaihtoehdot, mukaan lukien tiettyihin alatileihin rajoitetut avaimet, löytyvät API-viitteistön API-avainsivulta.

Perus-URL #

Kaikissa API-pyynnöissä käytetään seuraavaa verkko-osoitteen perusosaa:

https://api.youraiconnector.com/v1/

Todennus #

Jokaisen pyynnön on sisällettävä API-avaimesi, jotta alusta tietää, että kyseessä olet sinä. Yksinkertaisin tapa on lisätä se verkko-osoitteen loppuun:

https://api.youraiconnector.com/v1/contacts?apiKey=YOUR_API_KEY

Voit myös lähettää avaimen pyynnön otsikkotietona (header) URL-osoitteen sijaan (suositellaan tuotantokäyttöön, jotta avain ei päädy palvelinlokeihin):

X-API-Key: YOUR_API_KEY

Authorization: Bearer YOUR_API_KEY

Kaikkien pyyntöjen on käytettävä suojattua yhteyttä (HTTPS). Suojaamattomat (HTTP) pyynnöt hylätään.

Etsitkö täydellisiä kehittäjäoppaita? Tämä sivu on nopea johdanto yleisimpiin toimintoihin. Täydelliset, vaiheittaiset oppaat — jokainen resurssi cURL-, JavaScript- ja Python-esimerkein — löytyvät kohdista Getting Started with the API ja API Reference.

Yleiset API-toiminnot #

Luo yhteystieto #

Pyyntö:

POST https://api.youraiconnector.com/v1/contacts?apiKey=YOUR_API_KEY
Content-Type: application/json

{
  "firstName": "Jane",
  "lastName": "Smith",
  "phoneNumber": "+15551234567",
  "email": "jane@example.com"
}

Pakolliset kentät: phoneNumber (maakoodilla) on aina pakollinen yhteystiedon luomiseksi. Pelkkä sähköpostiosoite ei riitä – pyyntö ilman kelvollista puhelinnumeroa hylätään. Sähköpostiosoite on valinnainen.

Vastaus:

{
  "success": true,
  "data": {
    "message": "Successfully created new contact",
    "contactId": "abc123xyz",
    "listsAdded": []
  }
}

Tallenna data.contactId – tarvitset sitä “Lisää yhteystieto listalle” -kutsussa.

Lisää yhteystieto listaan #

POST https://api.youraiconnector.com/v1/contacts/lists?apiKey=YOUR_API_KEY
Content-Type: application/json

{
  "contactId": "abc123xyz",
  "listId": "YOUR_LIST_ID"
}

Löydät listan tunnisteen sovelluksesta kohdasta Yhteystiedot → Listat listan rivivalikosta (Kopioi listan tunniste).

Päivitä yhteystieto #

PUT https://api.youraiconnector.com/v1/contacts/YOUR_CONTACT_ID?apiKey=YOUR_API_KEY
Content-Type: application/json

{
  "customFields": { "company": "Acme Inc" }
}

Vain sisällyttämäsi kentät muuttuvat. Tämä on myös tapa ladata mukautettujen kenttien arvoja massana tuonnin jälkeen — katso Custom Fields, Lead Profile & Notes. Täydelliset tiedot löytyvät Contacts API -osiosta.

Lähetä viesti (mukautettu kanava) #

POST https://api.youraiconnector.com/v1/send_custom_channel_message?apiKey=YOUR_API_KEY
Content-Type: application/json

{
  "customData": {
    "fromId": "external-contact-id",
    "customChannel": "my-channel",
    "body": "Hello Jane! Your order has been shipped.",
    "campaignId": "optional-campaign-id",
    "firstName": "Jane",
    "lastName": "Smith"
  }
}

Vastaanota saapuvia viestejä (mukautettu kanava) #

Vastaanota viestejä ulkoisista järjestelmistä mukautettuna kanavana. Näin integraatiot, kuten GoHighLevel, lähettävät viestejä Your AI Connector-palveluun. Katso täydelliset tiedot kohdasta Mukautetut kanavat.

POST https://api.youraiconnector.com/v1/incoming_custom_channel_message?apiKey=YOUR_API_KEY
Content-Type: application/json

{
  "customData": {
    "messageSid": "unique-message-id",
    "fromId": "external-contact-id",
    "toId": "your-user-id",
    "body": "Customer's message here",
    "channel": "custom",
    "status": "received"
  },
  "messageType": "text"
}

Yleiskatsaus käytettävissä olevista toiminnoista #

Nopeusrajoitukset #

API asettaa nopeusrajoituksia alustan vakauden varmistamiseksi. Rajoituksen ylittäminen palauttaa 429 Too Many Requests — keskeytä pyynnöt ja yritä uudelleen vastausotsikoissa ilmoitetun ajan kuluttua. Suuren volyymin käyttötapauksissa (massatuonnit) käytä sisäänrakennettua tuontitoimintoa tai lähetä sähköpostia osoitteeseen hi@youraiconnector.com ohjeiden saamiseksi.

Parhaat käytännöt #

• Säilytä API-avaimesi turvallisesti — käytä salasananhallintaohjelmaa tai palvelinpuolen asetuksia, älä koskaan tallenna sitä asiakaspuolen koodiin, jonka selaimen käyttäjä voisi lukea.
• Sisällytä aina maakoodi puhelinnumeroihin (+1 Yhdysvalloille, +44 Isolle-Britannialle, +31 Alankomaille).
• Käsittele virheet asianmukaisesti — tarkista tilakoodit ja lue mahdolliset palautetut virheilmoitukset.
• Käsittele kaksoiskappaleet — kaksoiskappaleena oleva puhelinnumero palauttaa { "success": false, "error_code": 409 } uuden yhteystiedon sijaan, ja olemassa olevan yhteystiedon ID on kohdassa contactId.
• Testaa pienellä tietojoukolla ennen massatoimintojen suorittamista.

Virhevastaukset #

{
  "error": {
    "code": "INVALID_PHONE",
    "message": "Phone number must include a valid country code."
  }
}

Seuraavat vaiheet #

• Webhooks – vastaanota reaaliaikaisia ilmoituksia sovelluksesta (erillinen osio API-avaimestasi).
• Yhdistä tekoälyavustajat (MCP) – käytä samaa API-avainta antaaksesi Clauden hallita tiliäsi.
• Facebook-liidilomakkeet – käytä API-rajapintaa automaatioalustojen kanssa liidien keräämiseen.
• GoHighLevel-integraatio – esimerkki täydellisestä kaksisuuntaisesta API-integraatiosta.