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.

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 #

The API enforces rate limits to ensure platform stability. Exceeding your limit returns 429 Too Many Requests — back off and retry after the time indicated in the response headers. For high-volume use cases (bulk imports), use the built-in import feature or email hi@youraiconnector.com for guidance.

Parhaat käytännöt #

• Säilytä API-avaimesi turvallisesti – käytä salasananhallintaohjelmaa tai palvelinpuolen asetuksia, älä koskaan asiakaspuolen koodia, jonka verkkosivuston vierailija voisi lukea.
• Lisää aina maakoodi puhelinnumeroihin (+1 Yhdysvallat, +44 Iso-Britannia, +31 Alankomaat).
• Käsittele virheet asianmukaisesti – tarkista tilakoodit ja lue kaikki palautetut virheilmoitukset.
• Käsittele kaksoiskappaleet – sama puhelinnumero palauttaa { "success": false, "error_code": 409 } uuden yhteystiedon sijaan. Etsi yhteystieto ensin, jos haluat muokata sitä.
• Testaa pienellä tietoaineistolla 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.