Viestit ja keskustelut #

Messages API:n avulla voit lähettää viestin mille tahansa yhteyshenkilölle, lukea keskusteluhistorian, korjata tai poistaa jo lähettämäsi viestin, reagoida viestiin, hakea koko keskusteluketjun, viedä keskustelun tekstimuodossa ja merkitä keskusteluja luetuiksi tai lukemattomiksi – kaikki tämä ilman, että sinun tarvitsee avata postilaatikkoa.

Kaikki tämän sivun polut ovat suhteessa perus-URL-osoitteeseen https://api.youraiconnector.com/v1. Jokainen pyyntö vaatii API-avaimesi – katso todennus nähdäksesi täydellisen listan tavoista lähettää se. Alla olevissa esimerkeissä käytetään X-API-Key-otsikkoa, ja yhdessä cURL-esimerkissä näytetään myös ?apiKey=-kyselylomake.

Miten toimitus toimii: Viestin lähettäminen ei odota sen perillemenoa. API vastaanottaa viestisi, palauttaa välittömästi viestin tunnisteen ja toimittaa sen sitten taustalla yhteyshenkilön kanavalla (WhatsApp, SMS, Instagram jne.). Jos haluat seurata, onko viesti todella toimitettu tai luettu, kuuntele tilapäivityksiä Webhookien avulla – älä käytä kyselyitä (polling). Lähetysvastaus vahvistaa vain, että viesti on otettu vastaan.

Lähetä viesti #

Lähettämiseen on kaksi tapaa. Valitse se, joka sopii parhaiten tapaasi tunnistaa yhteyshenkilö:

• Lähetä yhteyshenkilön tunnisteella – tiedät jo yhteyshenkilön tunnisteen (esimerkiksi loit yhteyshenkilön API:n kautta tai sait sen webhookista). Käytä POST /contacts/{contactId}/send-message.
• Lähetä yhteyshenkilön identiteetillä – tiedät yhteyshenkilön puhelinnumeron, Instagram-tunnisteen jne., mutta et heidän sisäistä tunnistettaan. Käytä POST /contacts/send ja anna alustan etsiä oikea yhteyshenkilö.

Molemmat asettavat viestin jonoon samalla tavalla ja toimittavat sen kanavalla, jota yhteyshenkilö käyttää. Sinun ei tarvitse valita siirtotapaa – alusta reitittää WhatsApp-yhteyshenkilöt WhatsAppin kautta, SMS-yhteyshenkilöt tekstiviestillä ja niin edelleen.

Molemmat löytävät vain jo olemassa olevia yhteystietoja. Kumpikaan kutsu ei luo uutta yhteystietoa: jos ID tai identiteetti ei täsmää mihinkään, palautuu 404, eikä siitä tule uutta yhteystietoa. Jos siis lähetät viestiä jollekin ensimmäistä kertaa, luo yhteystieto ensin kohdassa POST /contacts tai käytä WhatsApp Webissä alla olevaa toimintoa Lähetä suoraan WhatsApp Web -numeroon, joka luo yhteystiedon saman kutsun yhteydessä.

Lähetä yhteyshenkilön tunnisteella #

POST /contacts/{contactId}/send-message

LinkedInissä tällä tavalla tai postilaatikosta lähettämäsi viesti toimitetaan perille, vaikka henkilö käsittelisi ketjua LinkedInin puolella. Tekoälyn omat vastaukset ja jatkoviestit pidetään tällaisessa ketjussa odottamassa. Odotustilassa oleva vastaus poistetaan keskustelusta sen sijaan, että se näytettäisiin epäonnistuneena, koska mitään ei lähetetty eikä krediittejä käytetty. Tekoälyn viimeinen vastaus ennen kuin se siirtää ketjun ihmiselle toimitetaan edelleen perille.

cURL

curl -X POST "https://api.youraiconnector.com/v1/contacts/contact123/send-message" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "body": "Hi! Your appointment is confirmed for tomorrow at 10:00."
  }'

JavaScript

const res = await fetch(
  "https://api.youraiconnector.com/v1/contacts/contact123/send-message",
  {
    method: "POST",
    headers: {
      "X-API-Key": "YOUR_API_KEY",
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      body: "Hi! Your appointment is confirmed for tomorrow at 10:00.",
    }),
  }
);
const data = await res.json();
console.log(data.messageId);

Python

import requests

res = requests.post(
    "https://api.youraiconnector.com/v1/contacts/contact123/send-message",
    headers={
        "X-API-Key": "YOUR_API_KEY",
        "Content-Type": "application/json",
    },
    json={"body": "Hi! Your appointment is confirmed for tomorrow at 10:00."},
)
print(res.json()["messageId"])

Vastaus (200 OK):

{
  "success": true,
  "messageId": "aB3dE5fG7hI9jK1lM2nO",
  "contactId": "contact123",
  "channel": "whatsapp",
  "message": "Message created successfully. Delivery is being processed."
}

Lähetä yhteyshenkilön identiteetillä #

POST /contacts/send

Käytä tätä, kun sinulla ei ole yhteyshenkilön sisäistä tunnistetta. Anna viestin body sekä joko contact_id tai channel yhdessä kyseistä kanavaa vastaavan identiteettikentän kanssa.

Mitkä kanavat voidaan tunnistaa identiteetin perusteella. Vain kuusi 14 kanavasta hyväksyy identiteettikentän contact_id sijasta: whatsapp, whatsapp_web ja sms haetaan phone_number perusteella, instagram haetaan instagram_id perusteella, messenger haetaan messenger_id perusteella ja telegram haetaan telegram_user_id perusteella. Muilla kahdeksalla — instagram_private, chat-widget, custom, email, line, imessage, linkedin ja viber — ei ole julkista identiteettiä, jota voisi hakea, joten lähettäminen näillä kanavilla vaatii contact_id; pelkän channel välittäminen palauttaa 400, joka ilmoittaa, että contact_id vaaditaan.

cURL (käyttäen ?apiKey=-kyselylomaketta)

curl -X POST "https://api.youraiconnector.com/v1/contacts/send?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "channel": "whatsapp",
    "phone_number": "+31612345678",
    "body": "Hi! Your appointment is confirmed."
  }'

JavaScript

const res = await fetch("https://api.youraiconnector.com/v1/contacts/send", {
  method: "POST",
  headers: {
    "X-API-Key": "YOUR_API_KEY",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    channel: "whatsapp",
    phone_number: "+31612345678",
    body: "Hi! Your appointment is confirmed.",
  }),
});
const data = await res.json();
console.log(data.message_id, data.channel);

Python

import requests

res = requests.post(
    "https://api.youraiconnector.com/v1/contacts/send",
    headers={
        "X-API-Key": "YOUR_API_KEY",
        "Content-Type": "application/json",
    },
    json={
        "channel": "whatsapp",
        "phone_number": "+31612345678",
        "body": "Hi! Your appointment is confirmed.",
    },
)
data = res.json()
print(data["message_id"], data["channel"])

Vastaus (201 Created):

{
  "success": true,
  "message_id": "aB3dE5fG7hI9jK1lM2nO",
  "contact_id": "contact123",
  "channel": "whatsapp"
}

Miksi viesti saatetaan hylätä: Yhteyshenkilö, jolla on käytössä ”älä häiritse” -tila tai yksityinen tila, ei voi vastaanottaa lähteviä viestejä — pyyntö epäonnistuu ja palauttaa virheen 422. Jos mikään yhteyshenkilö ei vastaa antamaasi tunnusta tai identiteettiä, saat virheen 404.

Lähettäminen WhatsApp Webissä: variaatiot ja purskesuojaus #

Kaksi asiaa pätee kohteeseen body, kun yhteyshenkilö käyttää WhatsApp Webiä.

Spintax-aaltosulkeet laajennetaan lähetyskohtaisesti. body, joka on {Hi|Hello|Hey} there, quick question, lähetetään yhtenä kolmesta tervehdyksestä, joka valitaan kyseistä lähetystä varten — aaltosulkeet eivät koskaan päädy yhteyshenkilölle asti. Käytä tätä antaaksesi jokaiselle yhteyshenkilölle erilaisen aloitusviestin samasta integraatiokoodista. Teksti ilman aaltosulkeita lähetetään täsmälleen sellaisena kuin se on kirjoitettu.

Identtisten aloitusviestien purskeet hylätään. Jos kymmenen lähes identtistä aloitusviestiä lähetetään yhdestä WhatsApp Web -numerosta tunnin sisällä yhteyshenkilöille, jotka eivät ole koskaan kirjoittaneet sinulle, seuraavia viestejä ei toimiteta: lähetys hyväksytään tavalliseen tapaan (saat silti kohteen messageId), ja viesti jää tilaan status: "failed" ja error_code: "opener_burst", ja siinä on asiakkaan luettavissa oleva syy. Saman tekstin uudelleenyrittäminen ei auta — muuta tekstiä, odota tunti ja lähetä uudelleen. Vastaukset olemassa olevissa keskusteluissa eivät koskaan vaikuta tähän. Perustelut löytyvät kohdasta Identtiset aloitusviestit johtavat numeroiden rajoittamiseen.

Lähetä suoraan WhatsApp Web -numeroon #

POST /whatsapp-web/send

Lähetä viesti puhelinnumeroon WhatsApp Webissä etsimättä ensin yhteystietoa. Jos numero ei ole vielä yhteystieto, se luodaan saman kutsun yhteydessä tekoälyn ollessa pois päältä, jolloin viesti näyttää käsin lähetetyltä eikä avustaja ota keskustelua haltuunsa sen jälkeen. Olemassa olevaa yhteystietoa käytetään sellaisenaan.

curl -X POST "https://api.youraiconnector.com/v1/whatsapp-web/send?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "phoneNumber": "+31612345678",
    "message": "Hi Alex, your quote is ready."
  }'

Onnistunut kutsu vastaa 202:

{ "success": true, "queued": true, "contactId": "abc123" }

202 tarkoittaa, että viesti on hyväksytty, mutta ei vielä toimitettu. Aktiivisten aikojen ulkopuolella lähetys pidetään jonossa ja lähetetään seuraavassa sallitussa aikaikkunassa, ellet käyttänyt ignoreActiveHours-valintaa. Lue viestin oma tila kohdasta Listaa yhteystiedon viestit käyttämällä tästä saatua contactId-tunnistetta.

Kun lähetys ei onnistu:

Toinen kutsu samalle yhteystiedolle, kun yksi lähetys on vielä jonossa, vastaa 409, joten jono ei koskaan kerry yhden henkilön taakse.

Lisää muistiinpano keskusteluun #

POST /contacts/notes

Lisää rivin yhteyshenkilön keskusteluun lähettämättä sitä. Käytä tätä kontekstiin, joka tiimilläsi ja tekoälyllä tulisi olla, mutta jota yhteyshenkilön ei pitäisi koskaan nähdä: yhteenveto puhelusta, jonka puheagenttisi juuri soitti, huomautus CRM-järjestelmästäsi tai kollegan jättämä viesti. Tämä toimii kaikissa kanavissa (WhatsApp, SMS, Instagram, Messenger, Telegram, chat-widget, mukautetut kanavat ja niin edelleen).

Mitä muistiinpanolle tapahtuu:

• Se näkyy keskustelussa saapuneet-kansiossa keltaisena Muistiinpano-korttina, jossa näkyy kirjoittaja, jos sellainen on määritetty.
• Tekoäly lukee sen osana keskusteluhistoriaa sisäisenä muistiinpanona, joten se ottaa sen huomioon seuraavassa vastauksessaan.
• Sitä ei koskaan lähetetä yhteyshenkilölle, se ei kuluta viestikiintiötä eikä käynnistä mitään: ei tekoälyn vastausta, ei automaatiota, ei webhookia, ei ilmoitusta eikä lukemattomien viestien merkkiä. Se ei keskeytä tekoälyä eikä lasketa tiimisi vastaukseksi.

Etsi yhteyshenkilö samalla tavalla kuin kohdassa Lähetä yhteyshenkilön tunnisteella: joko sen ID:llä tai channel-tunnisteella ja vastaavalla tunnisteella. Muistiinpano lähetetään vain yhteyshenkilölle, joka on jo olemassa; jos mitään ei löydy, tuloksena on 404.

cURL

curl -X POST "https://api.youraiconnector.com/v1/contacts/notes" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "channel": "whatsapp",
    "phone_number": "+31612345678",
    "author": "Voice agent",
    "body": "Voice call, 3:12. Asked about knee surgery waiting times, prefers a call back on Tuesday morning.",
    "external_id": "call_8f2k1"
  }'

Vastaus (201 tai 200, jossa on duplicate: true, kun external_id oli jo kirjattu)

{
  "success": true,
  "messageId": "note_4c1f0e...",
  "contactId": "contact123"
}

Muistiinpano näkyy kohdassa Listaa yhteyshenkilön viestit tunnisteella type: "note".

Luo vastausluonnos tekoälyllä #

POST /contacts/{contactId}/draft-reply

Pyytää keskustelua käsittelevää tekoälyagenttia kirjoittamaan seuraavan vastauksen ja palauttaa tekstin sinulle. Mitään ei lähetetä. Se on sama luonnos, jonka postilaatikon Luo vastaus -painike kirjoittaa: agentti käyttää asetuksiaan, tietokantaansa ja tähänastista keskustelua vastatakseen yhteyshenkilön kielellä. Käytä tätä asettaaksesi ihmisen (tai oman sovelluksesi) tekoälyn ja yhteyshenkilön väliin: hae luonnos, näytä se hyväksyttäväksi ja lähetä se sitten Lähetä yhteyshenkilön tunnuksella -toiminnolla, joko muutettuna tai sellaisenaan.

• Luonnoksen kirjoittaa yhteyshenkilölle määritetty agentti. Yhteyshenkilö, jolla ei vielä ole agenttia, saa sen agentin, joka vastaisi hänen seuraavaan viestiinsä.
• Luonnostelun aikana agentti ei suorita mitään työkaluja tai toimintoja, joten varauksia, tunnisteiden lisäämistä, siirtoja tai muita toimintoja ei tapahdu.
• Keskusteluun ei tallenneta mitään, eikä yhteyshenkilö näe mitään.
• Luonnos maksaa saman verran krediittejä kuin yksi kyseisen agentin tekoälyvastaus tässä keskustelussa, eikä se maksa mitään, kun oma tekoälyavaimesi on yhdistetty.
• Keskustelussa on oltava vähintään yksi viesti.

Kaikki runkokentät ovat valinnaisia; tyhjä runko (tai rungon puuttuminen) luonnostelee seuraavan vastauksen.

cURL

curl -X POST "https://api.youraiconnector.com/v1/contacts/contact123/draft-reply" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "instruction": "Offer Tuesday at 3pm for the consultation" }'

Vastaus (200)

{
  "success": true,
  "contact_id": "contact123",
  "draft": "Hi Sara, Tuesday at 3pm works for the consultation. Shall I put you down for it?"
}

400 tarkoittaa, että keskustelussa ei ole vielä viestejä, krediittisi loppuivat tai yhteyshenkilöllä ei ole agenttia tai kampanjaa, josta luonnostella (error kertoo kumpi). 404 tarkoittaa, että yhteyshenkilöä ei ole olemassa tai tiimin jäsenen avain on rajoitettu yhteyshenkilöihin, joita hän ei voi nähdä. Avaimella tai tiimin jäsenellä on oltava oikeus muokata viestejä.

Käytätkö tekoälyasiakasohjelmaa MCP:n kautta? Sama toiminto on käytettävissä generate_reply_draft-työkaluna.

Listaa yhteyshenkilön viestit #

GET /contacts/{contactId}/messages

Palauttaa yhteyshenkilön viestit uusimmasta alkaen, käyttäen osoittimeen (cursor) perustuvaa sivutusta.

Huomautus suodatuksesta ja sivutuksesta: filter- ja direction-suodattimet sovelletaan jokaiselle sivulle sen lukemisen jälkeen, joten suodatettu sivu voi sisältää vähemmän kohteita kuin limit. next_cursor etenee edelleen koko keskustelun läpi, joten jatka sivutusta, kunnes next_cursor on null.

cURL

curl "https://api.youraiconnector.com/v1/contacts/contact123/messages?limit=50&direction=inbound" \
  -H "X-API-Key: YOUR_API_KEY"

JavaScript

const params = new URLSearchParams({ limit: "50", direction: "inbound" });
const res = await fetch(
  `https://api.youraiconnector.com/v1/contacts/contact123/messages?${params}`,
  { headers: { "X-API-Key": "YOUR_API_KEY" } }
);
const data = await res.json();
console.log(data.messages, data.next_cursor);

Python

import requests

res = requests.get(
    "https://api.youraiconnector.com/v1/contacts/contact123/messages",
    headers={"X-API-Key": "YOUR_API_KEY"},
    params={"limit": 50, "direction": "inbound"},
)
data = res.json()
print(data["messages"], data["next_cursor"])

Vastaus (200 OK):

{
  "success": true,
  "contact_id": "contact123",
  "messages": [
    {
      "id": "aB3dE5fG7hI9jK1lM2nO",
      "body": "Hi! Thanks for reaching out.",
      "direction": "inbound",
      "channel": "whatsapp",
      "status": "delivered",
      "type": null,
      "timestamp": "2026-06-01T10:00:00.000Z",
      "media_url": null,
      "media_content_type": null,
      "bot_reply": false
    }
  ],
  "next_cursor": "cD4eF6gH8iJ0kL2mN3oP"
}

Viestikentät #

Lataa viestin liite #

POST /chat-exports/media/download-url

Antaa sinulle uuden latauslinkin viestiin liitettyyn tiedostoon: kuvaan, ääniviestiin, videoon tai asiakirjaan. Linkki toimii 1 tunnin ajan. Käytä tätä, kun haluat tallentaa liitteitä muualle (esimerkiksi arkistoidaksesi ansioluetteloita tai yhteyshenkilön lähettämiä ääniviestejä) tai kun viestin media_url tai uuden viestin webhook ei enää avaudu.

Löytääksesi viestit, joissa on liitteitä, listaa yhteyshenkilön viestit käyttämällä filter=media. Kunkin viestin id ja yhteyshenkilön tunniste muodostavat messagePath:n.

cURL

curl -X POST "https://api.youraiconnector.com/v1/chat-exports/media/download-url" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"messagePath": "contacts/contact123/messages/aB3dE5fG7hI9jK1lM2nO"}'

JavaScript

const res = await fetch("https://api.youraiconnector.com/v1/chat-exports/media/download-url", {
  method: "POST",
  headers: { "X-API-Key": "YOUR_API_KEY", "Content-Type": "application/json" },
  body: JSON.stringify({ messagePath: "contacts/contact123/messages/aB3dE5fG7hI9jK1lM2nO" }),
});
const { data } = await res.json();
console.log(data.url); // download the file within the hour

Python

import requests

res = requests.post(
    "https://api.youraiconnector.com/v1/chat-exports/media/download-url",
    headers={"X-API-Key": "YOUR_API_KEY"},
    json={"messagePath": "contacts/contact123/messages/aB3dE5fG7hI9jK1lM2nO"},
)
file_url = res.json()["data"]["url"]

Vastaus (200 OK):

{
  "success": true,
  "data": {
    "url": "https://storage.googleapis.com/...",
    "expiresInMs": 3600000
  }
}

Käytätkö tekoälyasiakasohjelmaa MCP:n kautta? Sama toiminto on käytettävissä get_chat_media_download_url-työkaluna.

Listaa keskusteluistunnot #

Chat-istunto on yksi keskusteluikkuna yhteyshenkilön kanssa. Se avautuu ensimmäisestä saapuvasta viestistä, kun istuntoa ei ole auki, ja se sulkeutuu automaattisesti 48 tuntia yhteyshenkilön viimeisen saapuvan viestin jälkeen (jokainen uusi saapuva viesti siirtää sulkeutumista 48 tunnilla eteenpäin). Tekoälyn suorittama keskustelun päättäminen ei sulje istuntoa; se laukaisee ainoastaan Chat Concluded -verkkokoukun. Istuntojen avulla pitkä historia voidaan jakaa luettaviin keskusteluihin yhden loputtoman listan sijaan.

Viimeisimmät istunnot kaikilla yhteyshenkilöillä #

GET /chat-sessions/recent

Palauttaa istunnot, jotka alkoivat viimeisen X tunnin aikana, uusimmasta alkaen, kaikilta tilin yhteyshenkilöiltä.

cURL

curl "https://api.youraiconnector.com/v1/chat-sessions/recent?hours=24&status=ChatSessionClosed" \
  -H "X-API-Key: YOUR_API_KEY"

JavaScript

const params = new URLSearchParams({ hours: "24", status: "ChatSessionClosed" });
const res = await fetch(`https://api.youraiconnector.com/v1/chat-sessions/recent?${params}`, {
  headers: { "X-API-Key": "YOUR_API_KEY" },
});
const data = await res.json();
console.log(data.data.total_sessions, data.data.sessions);

Python

import requests

res = requests.get(
    "https://api.youraiconnector.com/v1/chat-sessions/recent",
    headers={"X-API-Key": "YOUR_API_KEY"},
    params={"hours": 24, "status": "ChatSessionClosed"},
)
data = res.json()["data"]
print(data["total_sessions"], data["sessions"])

Vastaus (200 OK):

{
  "success": true,
  "data": {
    "hours_ago": 24,
    "total_sessions": 2,
    "sessions": [
      {
        "session_id": "session456",
        "contact_id": "contact123",
        "contact_name": "Jane Doe",
        "contact_phone": "+31612345678",
        "contact_email": "jane@example.com",
        "start_date_time": "2026-06-01T09:55:00.000Z",
        "end_date_time": "2026-06-01T10:20:00.000Z",
        "status": "ChatSessionClosed",
        "tag": "Booking enquiry"
      }
    ]
  }
}

Kaikki yhden yhteyshenkilön istunnot #

GET /chat-sessions/{contactId}

Palauttaa jokaisen keskusteluistunnon yhdelle yhteyshenkilölle. Samat status-, limit- ja includeMessages-parametrit kuin yllä – hours ei päde tässä.

cURL

curl "https://api.youraiconnector.com/v1/chat-sessions/contact123?limit=20" \
  -H "X-API-Key: YOUR_API_KEY"

Vastaus (200 OK):

{
  "success": true,
  "data": {
    "contact_id": "contact123",
    "contact_name": "Jane Doe",
    "total_sessions": 2,
    "sessions": [
      {
        "id": "session456",
        "start_date_time": "2026-06-01T09:55:00.000Z",
        "end_date_time": "2026-06-01T10:20:00.000Z",
        "status": "ChatSessionClosed",
        "tag": "Booking enquiry"
      }
    ]
  }
}

Istunnon tunnisteen kenttien nimet eroavat näiden kahden päätepisteen välillä. Viimeisimpien istuntojen luettelossa sitä kutsutaan nimellä session_id (se sisältää myös yhteyshenkilön tiedot, koska istunnot tulevat monilta yhteyshenkilöiltä); yhteyshenkilökohtaisessa luettelossa sitä kutsutaan nimellä id. Kumpaa tahansa arvoa käytetään, kun haet koko keskusteluketjua alla olevan {sessionId}-kohdan kautta.

Kun includeMessages=true, jokainen istunto saa messages-taulukon, jonka merkinnät sisältävät id, body, direction, timestamp, type, channel ja status.

Hae keskusteluketju #

GET /contacts/{contactId}/chat-sessions/{sessionId}/messages

Chat-istunto ryhmittelee yhteyshenkilön viestit yhteen keskusteluikkunaan. Tämä päätepiste palauttaa yksittäisen istunnon koko viestiketjun vanhimmasta alkaen sekä istunnon metatiedot. Löydät yhteyshenkilön istuntotunnukset chat-istuntojen päätepisteiden kautta.

cURL

curl "https://api.youraiconnector.com/v1/contacts/contact123/chat-sessions/session456/messages" \
  -H "X-API-Key: YOUR_API_KEY"

JavaScript

const res = await fetch(
  "https://api.youraiconnector.com/v1/contacts/contact123/chat-sessions/session456/messages",
  { headers: { "X-API-Key": "YOUR_API_KEY" } }
);
const data = await res.json();
console.log(data.session, data.messages);

Python

import requests

res = requests.get(
    "https://api.youraiconnector.com/v1/contacts/contact123/chat-sessions/session456/messages",
    headers={"X-API-Key": "YOUR_API_KEY"},
)
data = res.json()
print(data["session"], data["messages"])

Vastaus (200 OK):

{
  "success": true,
  "contact_id": "contact123",
  "session": {
    "id": "session456",
    "status": "ChatSessionClosed",
    "start_date_time": "2026-06-01T09:55:00.000Z",
    "end_date_time": "2026-06-01T10:20:00.000Z",
    "tag": "Booking enquiry"
  },
  "messages": [
    {
      "id": "aB3dE5fG7hI9jK1lM2nO",
      "body": "Hi! Thanks for reaching out.",
      "direction": "inbound",
      "channel": "whatsapp",
      "status": "delivered",
      "type": null,
      "timestamp": "2026-06-01T09:55:00.000Z",
      "media_url": null,
      "media_content_type": null,
      "bot_reply": false
    }
  ]
}

session-objekti raportoi status (ChatSessionOpened aktiivisena, ChatSessionClosed kun päättynyt), start_date_time, end_date_time ja ihmisluettavan tag. messages-taulukko käyttää samoja viestikenttiä kuin listauspäätepiste.

Muokkaa, poista ja reagoi viesteihin #

Nämä päätepisteet muuttavat viestiä sen lähettämisen jälkeen. Kaksi niistä ottaa yhteyttä yhteyshenkilön kanavaan sekä omaan kopioosi, joten lue osion johdanto ennen niiden käyttöönottoa – se, mikä on mahdollista, riippuu täysin kanavasta, jossa keskustelu käydään.

Mitä kukin kanava sallii

Kaikissa muissa kanavissa — WhatsApp Business API, SMS, Instagram, Messenger, sähköposti, LINE, mukautetut kanavat — poistaminen poistaa viestin edelleen postilaatikostasi, mutta yhteyshenkilö säilyttää oman kopionsa, eikä muokkaaminen tai reagoiminen ole lainkaan mahdollista.

Viestin muokkaaminen #

POST /contacts/{contactId}/messages/{messageId}/edit

Kirjoittaa uudelleen jo lähettämäsi viestin sekä yhteyshenkilön laitteella että omassa kopiossasi.

Toisin kuin poistaminen, tämä epäonnistuu näkyvästi, jos kanava kieltäytyy: saat 409-ilmoituksen ja kopiosi pysyy täsmälleen sellaisena kuin yhteyshenkilöllä, koska sellaisen muokkauksen näyttäminen, jota he eivät koskaan vastaanottaneet, saisi osapuolet epätahtiin. edit_reason-kenttä kertoo syyn – kanavan muokkausaika on umpeutunut, kanava on katkaistu, viestissä on liite, jota kanava ei voi muokata (media_not_editable: WhatsApp Webissä vain tekstiviestejä voi muokata, ei kuvan, videon tai tiedoston alla olevaa tekstiä), tai jokin muu meni vikaan.

cURL

curl -X POST "https://api.youraiconnector.com/v1/contacts/contact123/messages/msg_1/edit" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "body": "Sorry - I meant Thursday at 3pm." }'

JavaScript

const res = await fetch(
  "https://api.youraiconnector.com/v1/contacts/contact123/messages/msg_1/edit",
  {
    method: "POST",
    headers: {
      "X-API-Key": "YOUR_API_KEY",
      "Content-Type": "application/json",
    },
    body: JSON.stringify({ body: "Sorry - I meant Thursday at 3pm." }),
  }
);
const data = await res.json();
console.log(data.edited, data.edit_reason);

Python

import requests

res = requests.post(
    "https://api.youraiconnector.com/v1/contacts/contact123/messages/msg_1/edit",
    headers={
        "X-API-Key": "YOUR_API_KEY",
        "Content-Type": "application/json",
    },
    json={"body": "Sorry - I meant Thursday at 3pm."},
)
data = res.json()
print(data.get("edited"), data.get("edit_reason"))

Vastaus (200 OK):

{
  "success": true,
  "contact_id": "contact123",
  "message_id": "msg_1",
  "edited": true,
  "edit_reason": "edit_dispatched"
}

Jos kanava ei hyväksy muokkausta, saat sen sijaan 409-vastauksen, eikä mitään muutettu:

{
  "success": false,
  "error": "The message could not be edited",
  "edit_reason": "channel_disconnected"
}

Jo poistettu viesti, kanava, joka ei tue muokkaamista lainkaan, ja viesti, joka on liian vanha kanavalleen, palauttavat kaikki 400-vastauksen — pyyntö ei koskaan saavuta kanavaa.

Yhden viestin poistaminen #

DELETE /contacts/{contactId}/messages/{messageId}

Poistaa viestin keskustelustasi ja, jos kanava sen sallii, hakee myös yhteyshenkilön kopion takaisin. Ei pyyntörunkoa.

Tämä vastaa aina 200, kun viesti oli olemassa, vaikka yhteyshenkilön kopiota ei olisi voitu poistaa — oma kopiosi on poistettu, joten virheilmoitus olisi harhaanjohtava. Lue vastauksen kolme kenttää kertoaksesi käyttäjälle, mitä todellisuudessa tapahtui:

cURL

curl -X DELETE "https://api.youraiconnector.com/v1/contacts/contact123/messages/msg_1" \
  -H "X-API-Key: YOUR_API_KEY"

JavaScript

const res = await fetch(
  "https://api.youraiconnector.com/v1/contacts/contact123/messages/msg_1",
  { method: "DELETE", headers: { "X-API-Key": "YOUR_API_KEY" } }
);
const data = await res.json();
console.log(data.revoked, data.revoke_reason);

Python

import requests

res = requests.delete(
    "https://api.youraiconnector.com/v1/contacts/contact123/messages/msg_1",
    headers={"X-API-Key": "YOUR_API_KEY"},
)
data = res.json()
print(data["revoked"], data["revoke_reason"])

Vastaus (200 OK):

{
  "success": true,
  "contact_id": "contact123",
  "message_id": "msg_1",
  "revoke_supported": true,
  "revoked": true,
  "revoke_reason": "revoke_dispatched"
}

Poistettuja viestejä ei poisteta keskusteluhistoriasta. Ne säilyvät kohdassa GET /contacts/{contactId}/messages, jossa on is_deleted: true sekä tyhjä body ja media_url.

Poista useita viestejä kerralla #

POST /contacts/{contactId}/messages/bulk-delete

Tyhjentää viestierän vain omalta puoleltasi. Viestien sisältö ja liitteet tyhjennetään, mutta mitään ei peruta yhteyshenkilön laitteelta – jos haluat myös peruuttaa viestin, poista se yksitellen yllä olevan yksittäisen viestin päätepisteen kautta.

cURL

curl -X POST "https://api.youraiconnector.com/v1/contacts/contact123/messages/bulk-delete" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "message_ids": ["msg_1", "msg_2"] }'

JavaScript

const res = await fetch(
  "https://api.youraiconnector.com/v1/contacts/contact123/messages/bulk-delete",
  {
    method: "POST",
    headers: {
      "X-API-Key": "YOUR_API_KEY",
      "Content-Type": "application/json",
    },
    body: JSON.stringify({ message_ids: ["msg_1", "msg_2"] }),
  }
);
console.log((await res.json()).deleted);

Python

import requests

res = requests.post(
    "https://api.youraiconnector.com/v1/contacts/contact123/messages/bulk-delete",
    headers={
        "X-API-Key": "YOUR_API_KEY",
        "Content-Type": "application/json",
    },
    json={"message_ids": ["msg_1", "msg_2"]},
)
print(res.json()["deleted"])

Vastaus (200 OK):

{
  "success": true,
  "contact_id": "contact123",
  "deleted": 2
}

Reagoi viestiin #

POST /contacts/{contactId}/messages/{messageId}/react

Lisää oman emojireaktiosi viestiin tai poista se lähettämällä tyhjä merkkijono. Yhteyshenkilön omia reaktioita ei koskaan muuteta.

Muokkaamisen tavoin tämä epäonnistuu sen sijaan, että näyttäisi reaktion, jota yhteyshenkilö ei koskaan saanut, ja virheilmoitus kertoo, kannattaako yrittää uudelleen:

• 422 — viestiä ei voi koskaan toimittaa tässä keskustelussa: kanava ei tue reaktioita, viestillä ei ole kanavapuolen tunnistetta tai emoji ei kuulu kanavan sallimiin merkkeihin.
• 409 — kanava ei ollut hetkellisesti tavoitettavissa. Uudelleenyritys saattaa toimia.

cURL

curl -X POST "https://api.youraiconnector.com/v1/contacts/contact123/messages/msg_1/react" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "emoji": "👍" }'

JavaScript

const res = await fetch(
  "https://api.youraiconnector.com/v1/contacts/contact123/messages/msg_1/react",
  {
    method: "POST",
    headers: {
      "X-API-Key": "YOUR_API_KEY",
      "Content-Type": "application/json",
    },
    body: JSON.stringify({ emoji: "👍" }),
  }
);
const data = await res.json();
console.log(data.reactions);

Python

import requests

res = requests.post(
    "https://api.youraiconnector.com/v1/contacts/contact123/messages/msg_1/react",
    headers={
        "X-API-Key": "YOUR_API_KEY",
        "Content-Type": "application/json",
    },
    json={"emoji": "👍"},
)
print(res.json()["reactions"])

Vastaus (200 OK):

{
  "success": true,
  "contact_id": "contact123",
  "message_id": "msg_1",
  "reaction_supported": true,
  "reaction_reason": "reaction_dispatched",
  "reactions": [
    {
      "emoji": "👍",
      "from_phone_number": "+31612345678",
      "from_me": true,
      "reacted_at": "2026-06-01T10:05:00.000Z"
    }
  ]
}

reactions-taulukko sisältää kaikki viestin reaktiot, sekä sinun että yhteyshenkilön. 409- tai 422-tilanteessa se palautetaan muuttumattomana, joten suoraan siitä renderöivä asiakasohjelma ei koskaan näytä reaktiota, jota ei ole toimitettu.

Arvioi tai tähditä viesti #

PATCH /contacts/{contactId}/messages/{messageId}

Arvioi viestin peukalolla ylös tai alas ja/tai merkitse se tähdellä tärkeäksi. Tämä on kirjanpitoa vain omalla puolellasi – mitään ei lähetetä yhteyshenkilölle.

Lähetä vähintään toinen näistä, muuten saat 400-virheen. Vain lähetetyt tiedot kirjoitetaan, joten viestin tähdittäminen ei koskaan poista sen arviota ja päinvastoin – ja vastaus palauttaa vain lähettämäsi kentät.

cURL

curl -X PATCH "https://api.youraiconnector.com/v1/contacts/contact123/messages/msg_1" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "score": 1, "is_important": true }'

JavaScript

await fetch("https://api.youraiconnector.com/v1/contacts/contact123/messages/msg_1", {
  method: "PATCH",
  headers: {
    "X-API-Key": "YOUR_API_KEY",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({ score: 1, is_important: true }),
});

Python

import requests

requests.patch(
    "https://api.youraiconnector.com/v1/contacts/contact123/messages/msg_1",
    headers={"X-API-Key": "YOUR_API_KEY"},
    json={"score": 1, "is_important": True},
)

Vastaus (200 OK):

{
  "success": true,
  "contact_id": "contact123",
  "message_id": "msg_1",
  "score": 1,
  "is_important": true
}

Merkitse viestit luetuiksi #

Voit poistaa lukemattoman tilan joko tietyiltä viesteiltä tai koko keskustelulta.

Merkitse tietyt viestit luetuiksi #

POST /contacts/{contactId}/messages/mark-read

Välitä niiden viestien tunnukset, jotka haluat merkitä luetuiksi.

cURL

curl -X POST "https://api.youraiconnector.com/v1/contacts/contact123/messages/mark-read" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "message_ids": ["aB3dE5fG7hI9jK1lM2nO", "cD4eF6gH8iJ0kL2mN3oP"]
  }'

JavaScript

const res = await fetch(
  "https://api.youraiconnector.com/v1/contacts/contact123/messages/mark-read",
  {
    method: "POST",
    headers: {
      "X-API-Key": "YOUR_API_KEY",
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      message_ids: ["aB3dE5fG7hI9jK1lM2nO", "cD4eF6gH8iJ0kL2mN3oP"],
    }),
  }
);
const data = await res.json();
console.log(data.marked_read);

Python

import requests

res = requests.post(
    "https://api.youraiconnector.com/v1/contacts/contact123/messages/mark-read",
    headers={
        "X-API-Key": "YOUR_API_KEY",
        "Content-Type": "application/json",
    },
    json={"message_ids": ["aB3dE5fG7hI9jK1lM2nO", "cD4eF6gH8iJ0kL2mN3oP"]},
)
print(res.json()["marked_read"])

Vastaus (200 OK):

{
  "success": true,
  "contact_id": "contact123",
  "marked_read": 2
}

Merkitse koko chat luetuksi #

POST /contacts/{contactId}/mark-read

Poistaa lukemattomien viestien merkin yhteyshenkilön koko keskustelusta saapuneet-kansiossa. Pyyntörunkoa ei tarvita.

cURL

curl -X POST "https://api.youraiconnector.com/v1/contacts/contact123/mark-read" \
  -H "X-API-Key: YOUR_API_KEY"

JavaScript

const res = await fetch(
  "https://api.youraiconnector.com/v1/contacts/contact123/mark-read",
  { method: "POST", headers: { "X-API-Key": "YOUR_API_KEY" } }
);
const data = await res.json();
console.log(data.success);

Python

import requests

res = requests.post(
    "https://api.youraiconnector.com/v1/contacts/contact123/mark-read",
    headers={"X-API-Key": "YOUR_API_KEY"},
)
print(res.json()["success"])

Vastaus (200 OK):

{
  "success": true,
  "contact_id": "contact123"
}

Merkitse koko keskustelu lukemattomaksi #

POST /contacts/{contactId}/mark-unread

Palauttaa lukemattoman viestin merkin keskusteluun – kätevää, kun joku tiimistäsi on avannut keskustelun, mutta siirtää sen takaisin. Pyynnön runkoa ei tarvita.

Tämä on vain postilaatikkoa koskeva lippu: se ei muuta sitä, milloin keskustelu on viimeksi luettu, joten lukukuittausta ei lähetetä yhteyshenkilölle kanavilla, jotka tukevat niitä.

cURL

curl -X POST "https://api.youraiconnector.com/v1/contacts/contact123/mark-unread" \
  -H "X-API-Key: YOUR_API_KEY"

Vastaus (200 OK):

{
  "success": true,
  "contact_id": "contact123"
}

Vie keskustelu #

Viennit tarjoavat koko keskustelun luettavana litteraattina sen sijaan, että joutuisit selaamaan viestejä sivuittain. Jokainen vientirajapinta hyväksyy filter-parametrin, jonka arvo on all (oletus), text, media tai tool_use, vastaten viestilistan suodatinta.

Vie yhden yhteyshenkilön keskustelu #

GET /chat-exports/{contactId}

cURL

curl "https://api.youraiconnector.com/v1/chat-exports/contact123?format=json" \
  -H "X-API-Key: YOUR_API_KEY"

Python

import requests

res = requests.get(
    "https://api.youraiconnector.com/v1/chat-exports/contact123",
    headers={"X-API-Key": "YOUR_API_KEY"},
    params={"format": "json"},
)
print(res.json()["data"]["messages"])

Vastaus, jossa on format=json (200 OK):

{
  "success": true,
  "data": {
    "contact": {
      "id": "contact123",
      "name": "Jane Doe",
      "phone": "+31612345678",
      "email": "jane@example.com"
    },
    "messages": [
      {
        "body": "Hi! I have a question about my order.",
        "direction": "inbound",
        "timestamp": "2026-06-01T09:55:00.000Z",
        "type": "text",
        "media_url": null,
        "media_content_type": null,
        "name": null,
        "args": null
      }
    ]
  }
}

Kun käytössä on format=txt (oletus), data on sen sijaan latauslinkki luotuun litteraattitiedostoon:

{
  "success": true,
  "data": "https://storage.googleapis.com/.../chat-export-contact123-....txt"
}

Latauslinkki on lyhytikäinen. Hae tiedosto heti, kun saat linkin, sen sijaan että tallentaisit sen – pyydä uusi vienti, kun tarvitset litteraattia uudelleen.

Vie kaikki viimeaikaiset keskustelut #

GET /chat-exports/recent

Vie kaikkien niiden yhteystietojen keskustelut, jotka ovat olleet aktiivisia viimeisen X tunnin aikana, yhdellä kutsulla.

cURL

curl "https://api.youraiconnector.com/v1/chat-exports/recent?hours=24&limit=25" \
  -H "X-API-Key: YOUR_API_KEY"

Vastaus (200 OK):

{
  "success": true,
  "data": {
    "hours_ago": 24,
    "total_contacts": 2,
    "exports": [
      {
        "contactId": "contact123",
        "contactName": "Jane Doe",
        "phoneNumber": "+31612345678",
        "email": "jane@example.com",
        "messageCount": 12,
        "chatExport": "Acme Export - Jane Doe\nPhone: +31612345678\n..."
      }
    ]
  }
}

Kun käytössä on format=txt, vastaus on itse tekstitiedosto, joka lähetetään ladattavana tiedostona JSON-muodon sijaan.

Tämä yksi kutsu hakee kaikkien vastaavien yhteystietojen koko historian, joten pidä hours ja limit maltillisina kiireisillä tileillä.

Lähetä keskusteluhistoria sähköpostitse yhteystiedolle #

POST /chat-exports/{contactId}/email

Lähettää yhteystiedolle hänen oman keskusteluhistoriansa sähköpostitse – tämä on “lähetä tämä keskustelu minulle sähköpostilla” -toiminto, joka käynnistetään omasta järjestelmästäsi.

cURL

curl -X POST "https://api.youraiconnector.com/v1/chat-exports/contact123/email" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "note": "Here is a copy of our chat, as promised." }'

Vastaus (200 OK):

{
  "success": true,
  "data": {
    "via": "transactional",
    "recipientEmail": "jane@example.com",
    "messageCount": 42,
    "omittedCount": 0
  }
}

omittedCount kertoo, kuinka monta vanhinta viestiä jätettiin pois, jotta sähköpostin pituus pysyisi järkevänä. 200 tarkoittaa, että keskusteluhistoria luotiin ja asetettiin lähetysjonoon, ei sitä, että se olisi jo saapunut postilaatikkoon.

Tekoälyn keskeyttäminen tai jatkaminen yhdelle yhteyshenkilölle #

PUT /contacts/{contactId}

Aseta is_bot_active arvoon false, kun haluat estää tekoälyä vastaamasta yhdelle yhteyshenkilölle, ja takaisin arvoon true, kun haluat palauttaa keskustelun botille. Tämä on haltuunottokytkin, jota tarvitset, kun ihminen astuu keskusteluun: API:n kautta lähettämäsi viestit toimitetaan edelleen, vaikka botti olisi keskeytettynä.

cURL

curl -X PUT "https://api.youraiconnector.com/v1/contacts/contact123" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "is_bot_active": false }'

JavaScript

await fetch("https://api.youraiconnector.com/v1/contacts/contact123", {
  method: "PUT",
  headers: {
    "X-API-Key": "YOUR_API_KEY",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({ is_bot_active: false }),
});

Python

import requests

requests.put(
    "https://api.youraiconnector.com/v1/contacts/contact123",
    headers={"X-API-Key": "YOUR_API_KEY"},
    json={"is_bot_active": False},
)

Vastaus

{
  "success": true,
  "contact_id": "contact123"
}

Keskeyttäminen vastauksen yhteydessä

Jos ihminen ottaa keskustelun haltuunsa lähettämällä vastauksen, voit keskeyttää botin samassa pyynnössä sen sijaan, että tekisit toisen kutsun. POST /contacts/{contactId}/send-message hyväksyy nämä valinnaiset liput:

curl -X POST "https://api.youraiconnector.com/v1/contacts/contact123/send-message" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "body": "Hi, Sarah here - taking over from the assistant.",
    "pauseBot": true,
    "clearIncompleteReply": true,
    "human_reply": true
  }'

Vastaus sisältää kohdan "botPaused": true, kun keskeytys on otettu käyttöön.

Yhteyshenkilön merkitseminen yksityiseksi käyttämällä kohdetta POST /contacts/bulk-flag keskeyttää myös botin kyseisen henkilön kohdalla. Katso täydellinen kenttäluettelo kohdasta Yhteyshenkilöt.

Oman postilaatikon rakentaminen #

Kaikki postilaatikon tarvitsema tieto löytyy tältä sivulta ja kohdasta Yhteyshenkilöt:

Reaaliaikaisia päivityksiä varten tilaa tapahtumat New Message, Replies, Human Alerted ja Chat Concluded käyttämällä Webhookeja sen sijaan, että kyselisit tätä API:a ajastetusti.

Messages API -virheet #

Viestien päätepisteet palauttavat vakiomuotoisen virhekuoren:

{
  "success": false,
  "error": "Contact 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 #

• Webhooks — vastaanota toimitustilan päivitykset suoraan sen sijaan, että kyselisit niitä.
• Yhteystiedot — luo ja etsi yhteystietoja, joille lähetät viestejä.
• Ajanvaraukset — varaa ja hallinnoi yhteystietojesi ajanvarauksia.