Entry Points API #

Entry Point (sisääntulopiste) on reitityssääntö: “kun tämä tapahtuu tällä kanavalla, ohjaa keskustelu tälle agentille”. Kanavan yhdistäminen tuo viestit tilille ja agentin luominen antaa sinulle jotain, joka voi vastata, mutta kumpikaan ei päätä, kuka vastaa tuntemattoman ensimmäiseen viestiin. Entry Pointit tekevät sen. Itse tuotetta koskien, katso Entry Points -opas.

• Perus-URL — https://api.youraiconnector.com/v1
• Todennus — API-avaimesi (katso Todennus)
• Virheet ja sivutus — katso Virheet ja sivutus

Kaikki alla olevat esimerkit näyttävät ?apiKey=-kyselymuodon cURL-muodossa ja X-API-Key-otsikon JavaScriptissä ja Pythonissa – kumpi tahansa toimii jokaisessa päätepisteessä.

API-selaimessa. Jokainen tämän sivun päätepiste on julkaistussa OpenAPI-määrityksessä, joten voit selata sen tarkkoja kenttiä ja suorittaa live-pyyntöjä API-selaimessa.

Yksi kutsu, jota useimmat integraatiot tarvitsevat #

Yhdistä kanava, luo agentti ja osoita sitten kanava agenttiin:

curl -X PUT "https://api.youraiconnector.com/v1/entry-points/channel-defaults?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "channel": "whatsapp", "agent_id": "ag7HkQ2ZpLxR3mNb" }'

Tämä on koko asennus “tämä agentti vastaa WhatsAppiin” -toiminnolle. Kaikki muu tällä sivulla on tarkoitettu kapeammille säännöille (avainsanat, kommentit, uudet seuraajat), useille numeroille yhdellä kanavalla ja määritettyjen asetusten lukemiseen.

Miten reititys päätetään #

Kun viesti saapuu, alusta käy läpi kiinteän tikapuu-mallin, ja ensimmäinen askel, joka tekee päätöksen, voittaa:

1. Ihminen on ottanut haltuunsa keskustelun — ei tekoälyä.
2. Yhteyshenkilö on jo määritetty agentille, joko manuaalisesti tai koska keskustelu kyseisen agentin kanssa on käynnissä — sama agentti pitää sen. Entry Pointit eivät koskaan siirrä olemassa olevaa keskustelua; jos haluat siirtää keskustelun toiselle agentille, määritä se (sovelluksessa tai Automaatiot-toiminnolla).
3. Yhteyshenkilö vastaa lähetykseen — lähetyksen agentti vastaa, tai ei kukaan, jos lähetyksellä ei ollut agenttia.
4. Kapea Entry Point täsmää. Avainsanasäännöt voittavat kommenttisäännöt, jotka voittavat seuraajasäännöt. Kahden samanlaisen säännön välillä viimeksi päivitetty voittaa.
5. Kanavan oletus sille kanavalle, jolle viesti saapui. Tiettyyn numeroon, johon yhteyshenkilö kirjoitti, rajattu oletus voittaa kanavan laajuisen oletuksen.
6. Mikään ei täsmännyt — viesti päätyy tiimisi saapuneet-kansioon, eikä avustaja vastaa.

Kaksi asiaa pehmentävät kohtaa 6. Tili, jolla on tasan yksi aktiivinen agentti ja jolle ei ole määritetty kanavakohtaista oletusta, saa silti kyseisen agentin vastaajaksi, joten uusi tili, joka yhdistää WhatsAppin ja lähettää testiviestin, ei saa hiljaisuutta. Tämä alaraja ei koske kanavaa, jolla on avainsanasääntö (siellä viesti, joka ei täsmää mihinkään avainsanaan, jätetään tarkoituksella ihmiselle), eikä se koskaan ohita kanavaa, jonka olet asettanut tilaan “ei kukaan” (katso Jätä kanava ilman vastaajaa).

Se, onko tikapuu-malli käytössä tilillä, raportoidaan kohdassa GET /entry-points/routing-status. Se on nykyään päällä jokaisella tilillä; kutsu on olemassa, jotta integraatio voi tarkistaa asian sen sijaan, että olettaisi.

Entry Point -objekti #

{
  "id": "ep3KmQ8vTzXr5nWd",
  "type": "keyword",
  "channels": ["whatsapp", "instagram"],
  "agent_id": "ag7HkQ2ZpLxR3mNb",
  "enabled": true,
  "match_config": {
    "keywords": ["pricing", "quote"]
  },
  "first_response_mode": null,
  "first_response_exact_text": null,
  "public_comment_reply_exact_text": null,
  "created_at": 1700000000000,
  "last_modified_at": 1700000000000
}

Sääntötyypit #

Avainsanasääntö kanavalla, jolla ei ole kanavan oletusasetusta, toimii myös porttina: viestit, jotka eivät vastaa yhtäkään avainsanaa, eivät saa automaattista vastausta ja päätyvät yksinkertaisesti saapuneet-kansioosi, jopa tilillä, jossa on vain yksi edustaja.

Määritä kanavalle edustaja #

PUT /entry-points/channel-defaults — tekee yhdestä edustajasta vastaajan uusille yhteyshenkilöille kanavalla. Kaikki muut edustajat, jotka on tällä hetkellä asetettu kyseisen kanavan oletusarvoksi, poistetaan samassa kutsussa, joten kanavalla on aina tasan yksi vastaaja. Sen edustajan asettaminen, joka on jo oletusarvona, ei muuta mitään.

cURL

curl -X PUT "https://api.youraiconnector.com/v1/entry-points/channel-defaults?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "channel": "instagram", "agent_id": "ag7HkQ2ZpLxR3mNb" }'

JavaScript

const res = await fetch("https://api.youraiconnector.com/v1/entry-points/channel-defaults", {
  method: "PUT",
  headers: {
    "X-API-Key": "YOUR_API_KEY",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({ channel: "instagram", agent_id: "ag7HkQ2ZpLxR3mNb" }),
});
const data = await res.json();

Python

import requests

res = requests.put(
    "https://api.youraiconnector.com/v1/entry-points/channel-defaults",
    headers={"X-API-Key": "YOUR_API_KEY"},
    json={"channel": "instagram", "agent_id": "ag7HkQ2ZpLxR3mNb"},
)
data = res.json()

Vastaus

{
  "success": true,
  "entry_point_id": "ep3KmQ8vTzXr5nWd",
  "disabled_entry_point_ids": ["epPrevious1234"]
}

entry_point_id on nyt voimassa oleva sääntö; disabled_entry_point_ids luettelee kaikki säännöt, jotka on poistettu sen tieltä (tyhjä, jos mitään ei tarvinnut korvata). Vain yhteyshenkilöt, joiden kanssa et ole koskaan puhunut, vaikuttavat tähän — kuka tahansa, joka on jo keskustelussa edustajan kanssa, säilyttää kyseisen edustajan.

400 tarkoittaa, että channel tai agent_id puuttuu, edustaja kuuluu toiselle tilille tai phone_number ei ole yksi yhdistetyistä numeroistasi.

Katso, kuka vastaa millekin kanavalle #

GET /entry-points/channel-defaults — tilin jokainen kanavan oletusasetus, uusimmasta alkaen, mukaan lukien poistetut (enabled: false) ja kanava, joka on tarkoituksella asetettu tilaan “ei kukaan” (agent_id: ""). Suodata enabled itse nykyisen tilanteen mukaan.

cURL

curl "https://api.youraiconnector.com/v1/entry-points/channel-defaults?apiKey=YOUR_API_KEY"

JavaScript

const res = await fetch("https://api.youraiconnector.com/v1/entry-points/channel-defaults", {
  headers: { "X-API-Key": "YOUR_API_KEY" },
});
const data = await res.json();

Python

import requests

res = requests.get(
    "https://api.youraiconnector.com/v1/entry-points/channel-defaults",
    headers={"X-API-Key": "YOUR_API_KEY"},
)
data = res.json()

Vastaus

{
  "success": true,
  "entry_points": [
    {
      "id": "ep3KmQ8vTzXr5nWd",
      "type": "channel_default",
      "channels": ["whatsapp"],
      "agent_id": "ag7HkQ2ZpLxR3mNb",
      "enabled": true,
      "match_config": {},
      "created_at": 1700000000000,
      "last_modified_at": 1700000000000
    },
    {
      "id": "epAEnhHoozpoGVze",
      "type": "channel_default",
      "channels": ["whatsapp"],
      "agent_id": "agRotterdamBranch",
      "enabled": true,
      "match_config": { "phone_numbers": ["+31685101091"] },
      "created_at": 1700000000000,
      "last_modified_at": 1700000000000
    }
  ]
}

Tämä on koko tilin kattava luku. Yhden agentin sääntöjen listaaminen GET /agents/{agentId}/entry-points-toiminnolla ei voi näyttää kanavaa, joka on asetettu tilaan “ei kukaan”, koska kyseinen sääntö ei kuulu yhdellekään agentille.

Poistu kanavalta, jolla kukaan ei vastaa #

DELETE /entry-points/channel-defaults?channel=instagram — poistaa kanavakohtaisen oletusasetuksen yhdeltä kanavalta. Kanava nimetään kyselyparametrina, ei rungossa. Lisää &phone_number=%2B31685101091, jos haluat tyhjentää vain kyseisen numeron oletusasetuksen ja antaa numeron palata sille, joka vastaa kanavalle.

cURL

curl -X DELETE "https://api.youraiconnector.com/v1/entry-points/channel-defaults?channel=instagram&apiKey=YOUR_API_KEY"

JavaScript

const res = await fetch(
  "https://api.youraiconnector.com/v1/entry-points/channel-defaults?channel=instagram",
  { method: "DELETE", headers: { "X-API-Key": "YOUR_API_KEY" } }
);
const data = await res.json();

Python

import requests

res = requests.delete(
    "https://api.youraiconnector.com/v1/entry-points/channel-defaults",
    params={"channel": "instagram"},
    headers={"X-API-Key": "YOUR_API_KEY"},
)
data = res.json()

Vastaus

{ "success": true, "disabled_entry_point_ids": ["ep3KmQ8vTzXr5nWd"] }

Turvallinen toistaa: sellaisen kanavan tyhjentäminen, jolla ei ole oletusasetusta, on 200, joka palauttaa tyhjän listan. Tyhjentäminen tarkoittaa asetuksen poistamista, ei hiljentämistä — tilillä, jolla on tasan yksi aktiivinen agentti, konfiguroimaton kanava palautuu edelleen kyseiselle agentille. Jos haluat pitää tekoälyn kokonaan poissa kanavalta, valitse sovelluksen Kuka vastaa uusiin keskusteluihin -paneelista Kukaan ei vastaa (tämä kirjoittaa eksplisiittisen “ei kukaan” -oletuksen, jota varajärjestelmä ei koskaan ohita) tai keskeytä agentti PATCH /agents/{agentId}/active-toiminnolla.

Yksi agentti per WhatsApp-numero #

Reititys on oletusarvoisesti kanavakohtainen: kaikki WhatsApp-numerosi jakavat yhden vastaajan. Kun WhatsApp Businessissa tai WhatsApp Webissä on yhdistetty kaksi tai useampia numeroita, oletusasetus voidaan rajata yhteen numeroon, jolloin yritys, jolla on numero per toimipiste tai brändi, voi antaa jokaiselle oman agentin saman tilin sisällä.

Lähetä phone_number set-kutsulla:

curl -X PUT "https://api.youraiconnector.com/v1/entry-points/channel-defaults?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "channel": "whatsapp_web",
    "agent_id": "agRotterdamBranch",
    "phone_number": "+31685101091"
  }'

• Numeron on oltava yksi kyseisen kanavan liitetyistä numeroista, kirjoitettuna samassa muodossa kuin se näkyy liitettyjen numeroiden kohdalla (E.164 ja +); kaikki muu on 400.
• Sääntö tallennetaan kanavan oletusarvona käyttäen match_config.phone_numbers: ["+31685101091"]-toimintoa. Kyseiseen numeroon saapuva viesti ohjautuu sen edustajalle; kaikki muut numerot noudattavat edelleen kanavanlaajuista oletusarvoa.
• Kanavanlaajuisen oletusarvon asettaminen tai poistaminen ei vaikuta numerokohtaisiin sääntöihin, ja päinvastoin. Poista numeron oma sääntö käyttämällä DELETE /entry-points/channel-defaults?channel=whatsapp_web&phone_number=%2B31685101091-toimintoa.
• Vastaukset lähetetään aina siitä numerosta, johon yhteyshenkilö kirjoitti, joten yhteyshenkilö jatkaa keskustelua saman numeron ja saman edustajan kanssa.

Lisää tarkempi sääntö #

POST /agents/{agentId}/entry-points — luo avainsana-, kommentti- tai seuraajasäännön (tai kanavan oletusarvon, vaikka PUT /entry-points/channel-defaults on siihen parempi vaihtoehto, koska se poistaa edellisen vastaajan puolestasi). Polussa määritetty edustaja on aina ensisijainen: sääntöä ei voi koskaan luoda eri edustajalle kuin sille, joka on määritetty URL-osoitteessa.

cURL

curl -X POST "https://api.youraiconnector.com/v1/agents/ag7HkQ2ZpLxR3mNb/entry-points?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "keyword",
    "channels": ["whatsapp", "instagram"],
    "match_config": { "keywords": ["pricing", "quote"] }
  }'

JavaScript

const res = await fetch(
  "https://api.youraiconnector.com/v1/agents/ag7HkQ2ZpLxR3mNb/entry-points",
  {
    method: "POST",
    headers: {
      "X-API-Key": "YOUR_API_KEY",
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      type: "keyword",
      channels: ["whatsapp", "instagram"],
      match_config: { keywords: ["pricing", "quote"] },
    }),
  }
);
const data = await res.json();

Python

import requests

res = requests.post(
    "https://api.youraiconnector.com/v1/agents/ag7HkQ2ZpLxR3mNb/entry-points",
    headers={"X-API-Key": "YOUR_API_KEY"},
    json={
        "type": "keyword",
        "channels": ["whatsapp", "instagram"],
        "match_config": {"keywords": ["pricing", "quote"]},
    },
)
data = res.json()

Vastaus (201)

{ "success": true, "entry_point_id": "ep3KmQ8vTzXr5nWd" }

Kommentista yksityisviestiksi -sääntö, joka reagoi vain “LINK”-sanan sisältäviin kommentteihin kahdessa tietyssä julkaisussa, odottaa kaksi minuuttia ja lähettää kiinteän ensimmäisen viestin:

{
  "type": "instagram_comment",
  "channels": ["instagram"],
  "match_config": {
    "keywords": ["LINK"],
    "post_ids": ["17895695668004550", "17841400008460056"],
    "delay_minutes": 2
  },
  "first_response_mode": "exact_text",
  "first_response_exact_text": "Hi {{first_name}}, here is the link you asked for: https://example.com/guide",
  "public_comment_reply_exact_text": "Sent you a DM!"
}

Jätä keywords tyhjäksi, jos haluat lähettää yksityisviestin kaikille seurattuihin julkaisuihin kommentoiville, ja post_ids tyhjäksi, jos haluat seurata jokaista julkaisua. 400 kertoo, mikä on vialla: tuntematon type, tyhjä channels, avainsanasääntö ilman avainsanoja tai kommenttisääntö, joka ei listaa omaa kanavaansa.

Listaa edustajan säännöt #

GET /agents/{agentId}/entry-points — säännöt, jotka lähettävät keskusteluja tälle edustajalle, uusimmasta alkaen: kanavan oletusarvot, avainsanasäännöt, kommenttisäännöt ja seuraajasäännöt. Poistetut säännöt tulevat takaisin enabled: false-toiminnolla.

cURL

curl "https://api.youraiconnector.com/v1/agents/ag7HkQ2ZpLxR3mNb/entry-points?apiKey=YOUR_API_KEY"

JavaScript

const res = await fetch(
  "https://api.youraiconnector.com/v1/agents/ag7HkQ2ZpLxR3mNb/entry-points",
  { headers: { "X-API-Key": "YOUR_API_KEY" } }
);
const data = await res.json();

Python

import requests

res = requests.get(
    "https://api.youraiconnector.com/v1/agents/ag7HkQ2ZpLxR3mNb/entry-points",
    headers={"X-API-Key": "YOUR_API_KEY"},
)
data = res.json()

Vastaus

{
  "success": true,
  "entry_points": [
    {
      "id": "ep3KmQ8vTzXr5nWd",
      "type": "keyword",
      "channels": ["whatsapp", "instagram"],
      "agent_id": "ag7HkQ2ZpLxR3mNb",
      "enabled": true,
      "match_config": { "keywords": ["pricing", "quote"] },
      "created_at": 1700000000000,
      "last_modified_at": 1700000000000
    }
  ]
}

Muuta sääntöä #

PUT /entry-points/{entryPointId} — muuttaa yhtä sääntöä. Lähetä vain ne kentät, joita olet muuttamassa; sisäkkäisiä asetuksia voi käsitellä taso kerrallaan pisteellä erotetulla avaimella, kuten "match_config.keywords". Aina kun muutos koskee kohtia type, channels tai match_config, koko sääntö tarkistetaan uudelleen, joten osittainen muokkaus ei voi koskaan jättää jälkeensä käyttökelvotonta sääntöä (esim. type vaihtaminen muotoon keyword ilman avainsanojen toimittamista hylätään). agent_id-kohdan lähettäminen siirtää säännön toiselle edustajallesi; tyhjä arvo hylätään. Omistajuus- ja identiteettikentät jätetään huomiotta.

cURL

curl -X PUT "https://api.youraiconnector.com/v1/entry-points/ep3KmQ8vTzXr5nWd?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "match_config": { "keywords": ["pricing", "quote", "demo"] } }'

JavaScript

const res = await fetch("https://api.youraiconnector.com/v1/entry-points/ep3KmQ8vTzXr5nWd", {
  method: "PUT",
  headers: {
    "X-API-Key": "YOUR_API_KEY",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({ match_config: { keywords: ["pricing", "quote", "demo"] } }),
});
const data = await res.json();

Python

import requests

res = requests.put(
    "https://api.youraiconnector.com/v1/entry-points/ep3KmQ8vTzXr5nWd",
    headers={"X-API-Key": "YOUR_API_KEY"},
    json={"match_config": {"keywords": ["pricing", "quote", "demo"]}},
)
data = res.json()

Vastaus

{ "success": true, "entry_point_id": "ep3KmQ8vTzXr5nWd" }

Muita yleisiä muokkauksia: { "enabled": false } poistaa säännön käytöstä poistamatta sitä, ja { "agent_id": "agOtherAgent" } siirtää sen toiselle edustajalle. Tyhjä runko palauttaa 400 ja "No fields to update".

Poista sääntö #

DELETE /entry-points/{entryPointId} — poistaa säännön pysyvästi. Mikään muu ei viittaa Entry Pointiin, joten mitään ei tarvitse irrottaa ensin.

cURL

curl -X DELETE "https://api.youraiconnector.com/v1/entry-points/ep3KmQ8vTzXr5nWd?apiKey=YOUR_API_KEY"

JavaScript

const res = await fetch("https://api.youraiconnector.com/v1/entry-points/ep3KmQ8vTzXr5nWd", {
  method: "DELETE",
  headers: { "X-API-Key": "YOUR_API_KEY" },
});
const data = await res.json();

Python

import requests

res = requests.delete(
    "https://api.youraiconnector.com/v1/entry-points/ep3KmQ8vTzXr5nWd",
    headers={"X-API-Key": "YOUR_API_KEY"},
)
data = res.json()

Vastaus

{ "success": true, "entry_point_id": "ep3KmQ8vTzXr5nWd" }

Jos haluat estää säännön suorittamisen mutta säilyttää sen, aseta enabled arvoon false. Erityisesti kanavan oletusarvot yleensä poistetaan käytöstä sen sijaan, että ne poistettaisiin kokonaan, mikä onnistuu DELETE /entry-points/channel-defaults-toiminnolla.

Tarkista, että reititys on aktiivinen #

GET /entry-points/routing-status — palauttaa tiedon siitä, päättääkö Entry Points -tikapuu, kuka tällä tilillä vastaa. Luettavissa katseluoikeuksilla, joten tiimin jäsen näkee saman vastauksen kuin omistaja.

curl "https://api.youraiconnector.com/v1/entry-points/routing-status?apiKey=YOUR_API_KEY"

{ "success": true, "cutover_enabled": true }

Se on nykyään true jokaisella tilillä. Puhelu säilytetään, jotta integraatio voi varmistaa asian ennen kuin se ilmoittaa jollekulle reititysmuutoksen olevan käytössä, sen sijaan että se olettaisi niin.

Vanhemmat, kampanjamuotoiset puhelut #

Kaksi päätepistettä ajalta ennen Agentteja toimivat edelleen tileillä, jotka on järjestetty kampanjoiden ympärille. Uusien integraatioiden tulisi käyttää yllä mainittuja kanavien oletuspuheluita.

• PUT /channel-routing/{channel} ja { "campaignId": "cp5NbV8xQrT2wYzA" } — nimeää kampanjan, ja kyseisen kampanjan Agentista tulee kanavan vastaaja. { "campaignId": null } tyhjentää kanavan. Vain lähteviä puheluita sisältävä kampanja hylätään, koska sillä ei ole tarjottavaa saapuvaa toimintaa.
• POST /channel-routing/clear ja { "channels": ["whatsapp", "instagram"] } — vapauttaa useita kanavia riippumatta siitä, mikä Agentti niihin vastaa yhdellä puhelulla, yleensä ennen kuin ne ohjataan muualle. Vastaus listaa released_channels, eli ne, joilla oli todellisuudessa vastaaja.

Molemmat poistavat asetuksen sen sijaan, että ne hiljentäisivät: tilillä, jolla on tasan yksi aktiivinen Agentti, vapautettu kanava palautuu edelleen kyseiselle Agentille.

Entry Points API -virheet #

Entry Point -päätepisteet palauttavat tavallisen virhekuoren:

{
  "success": false,
  "error": "Entry point not found"
}

Jaetut koodit, joita jokainen päätepiste voi palauttaa — 401, 403 (tilauksesi ei sisällä API-käyttöoikeutta), 429 (nopeusrajoitus) ja 500 — on lueteltu uudelleenyritysohjeiden kera kohdassa Virheet ja sivutus.

Seuraavat vaiheet #

• Entry Points — konsepti, sääntötyypit ja Kuka vastaa uusiin keskusteluihin -paneeli sovelluksessa.
• AI Agents API — luo ja määritä Agentit, joille nämä säännöt reitittävät.
• Channels API — yhdistä itse kanavat.
• Comment-to-DM Automation — mitä kommenttisäännöt tekevät, kun ne aktivoituvat.