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.

Lähetä yhteyshenkilön tunnisteella #

POST /contacts/{contactId}/send-message

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.

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 #

Listaa keskusteluistunnot #

Keskusteluistunto on yksi keskusteluikkuna yhteyshenkilön kanssa: se avautuu, kun he aloittavat keskustelun, ja sulkeutuu, kun keskustelu päättyy. Istuntojen avulla voit jakaa pitkän historian luettaviin keskusteluihin yhden loputtoman luettelon 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-vastauksen ja oma kopiosi jää täsmälleen sellaiseksi kuin se on yhteyshenkilöllä, koska sellaisen muokkauksen näyttäminen, jota he eivät koskaan vastaanottaneet, saisi osapuolet epäsynkroniin. edit_reason-kenttä kertoo syyn — kanavan muokkausaika on umpeutunut, kanava on katkaistu 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 kaksi valinnaista lippua:

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
  }'

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.