Berichten & Gesprekken #

Met de Messages API kun je een bericht naar elke contactpersoon sturen, een conversatie teruglezen, een reeds verzonden bericht corrigeren of verwijderen, op een bericht reageren, een volledige chat-sessie ophalen, een transcript exporteren en chats als gelezen of ongelezen markeren — en dat alles zonder de inbox te openen.

Alle paden op deze pagina zijn relatief ten opzichte van de basis-URL https://api.youraiconnector.com/v1. Voor elk verzoek is je API-sleutel vereist — zie Authenticatie voor de volledige lijst met manieren om deze te verzenden. De onderstaande voorbeelden gebruiken de X-API-Key-header, waarbij één cURL-voorbeeld ook de ?apiKey=-queryvorm laat zien.

Hoe aflevering werkt: Het verzenden van een bericht wacht niet tot het is aangekomen. De API accepteert je bericht, reageert onmiddellijk met een bericht-ID en levert het vervolgens op de achtergrond af via het kanaal van de contactpersoon (WhatsApp, SMS, Instagram, enzovoort). Om bij te houden of een bericht daadwerkelijk is afgeleverd of gelezen, kun je luisteren naar statusupdates met Webhooks — ga niet pollen. De verzendreactie bevestigt alleen dat het bericht is geaccepteerd.

Een bericht verzenden #

Er zijn twee manieren om te verzenden. Kies degene die past bij hoe je de contactpersoon al identificeert:

• Verzenden op contact-ID — je kent het ID van de contactpersoon al (je hebt de contactpersoon bijvoorbeeld via de API aangemaakt of via een webhook verkregen). Gebruik POST /contacts/{contactId}/send-message.
• Verzenden op contact-identiteit — je kent het telefoonnummer, Instagram-ID, enz. van de contactpersoon, maar niet hun interne ID. Gebruik POST /contacts/send en laat het platform de juiste contactpersoon vinden.

Beide methoden plaatsen het bericht op dezelfde manier in de wachtrij en leveren het af via het kanaal waarop de contactpersoon zich bevindt. Je kiest zelf geen transportmethode — het platform routeert WhatsApp-contacten via WhatsApp, SMS-contacten via SMS, enzovoort.

Verzenden op contact-ID #

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"])

Antwoord (200 OK):

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

Verzenden op contact-identiteit #

POST /contacts/send

Gebruik dit wanneer je niet over het interne ID van de contactpersoon beschikt. Geef de berichttekst body op, plus ofwel een contact_id, ofwel een channel samen met het identiteitsveld dat overeenkomt met dat kanaal.

Welke kanalen kunnen worden opgelost op basis van identiteit. Slechts zes van de 14 accepteren een identiteitsveld in plaats van een contact_id: whatsapp, whatsapp_web en sms worden opgezocht via phone_number, instagram via instagram_id, messenger via messenger_id, en telegram via telegram_user_id. De andere acht — instagram_private, chat-widget, custom, email, line, imessage, linkedin en viber — hebben geen openbare identiteit om op te zoeken, dus verzenden via die kanalen vereist contact_id; het alleen doorgeven van channel resulteert in een 400 die aangeeft dat contact_id vereist is.

cURL (met gebruik van de ?apiKey=-queryvorm)

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"])

Antwoord (201 Created):

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

Waarom een bericht kan worden geweigerd: Een contactpersoon met de modus ‘niet storen’ of privémodus ingeschakeld kan geen uitgaande berichten ontvangen — het verzoek mislukt met een 422. Als er geen contactpersoon overeenkomt met het ID of de identiteit die je hebt opgegeven, krijg je een 404.

Berichten van een contactpersoon weergeven #

GET /contacts/{contactId}/messages

Geeft de berichten van een contactpersoon terug, de nieuwste eerst, met cursor-gebaseerde paginering.

Opmerking over filteren en paginering: De filter- en direction-filters worden toegepast op elke pagina nadat deze is gelezen, dus een gefilterde pagina kan minder items bevatten dan limit. De next_cursor gaat nog steeds door het volledige gesprek, dus blijf pagineren totdat next_cursor gelijk is aan 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"])

Antwoord (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"
}

Berichtvelden #

Chatsessies weergeven #

Een chatsessie is één conversatievenster met een contactpersoon: het opent wanneer zij beginnen te praten en sluit wanneer de conversatie is afgerond. Sessies zijn de manier waarop je een lange geschiedenis opdeelt in leesbare conversaties in plaats van één eindeloze lijst.

Recente sessies voor alle contactpersonen #

GET /chat-sessions/recent

Geeft de sessies terug die in de afgelopen X uur zijn gestart, nieuwste eerst, voor elke contactpersoon in het account.

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"])

Antwoord (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"
      }
    ]
  }
}

Alle sessies voor één contactpersoon #

GET /chat-sessions/{contactId}

Geeft elke chatsessie voor één enkele contactpersoon terug. Dezelfde status, limit en includeMessages parameters als hierboven — hours is hier niet van toepassing.

cURL

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

Antwoord (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"
      }
    ]
  }
}

Veldnamen voor sessie-ID verschillen tussen de twee endpoints. De lijst met recente sessies noemt het session_id (het bevat ook de details van de contactpersoon, aangezien sessies van vele contactpersonen komen); de lijst per contactpersoon noemt het id. Beide waarden zijn wat je doorgeeft als {sessionId} bij het ophalen van de volledige thread hieronder.

Wanneer includeMessages=true, krijgt elke sessie een messages array waarvan de items id, body, direction, timestamp, type, channel en status bevatten.

Een chatsessie-thread ophalen #

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

Een chatsessie groepeert de berichten van een contactpersoon in één gespreksvenster. Dit eindpunt retourneert de volledige thread van een enkele sessie, oudste eerst, samen met de metagegevens van de sessie. U kunt sessie-ID’s voor een contactpersoon vinden via de chatsessie-eindpunten.

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"])

Antwoord (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
    }
  ]
}

Het session-object rapporteert status (ChatSessionOpened indien actief, ChatSessionClosed zodra beëindigd), start_date_time, end_date_time en een voor mensen leesbare tag. De messages-array gebruikt dezelfde berichtvelden als het lijst-eindpunt.

Berichten bewerken, verwijderen en erop reageren #

Deze endpoints wijzigen een bericht nadat het is verzonden. Twee ervan bereiken zowel het kanaal van de contactpersoon als je eigen kopie, dus lees de inleiding van de sectie voordat je ze implementeert — wat mogelijk is, hangt volledig af van het kanaal waarop de conversatie plaatsvindt.

Wat elk kanaal toestaat

Op elk ander kanaal — de WhatsApp Business API, SMS, Instagram, Messenger, e-mail, LINE, aangepaste kanalen — verwijdert een verwijdering het bericht nog steeds uit je inbox, maar behoudt de contactpersoon zijn kopie, en is bewerken of reageren helemaal niet mogelijk.

Een bericht bewerken #

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

Herschrijft een bericht dat je al hebt verzonden, op het apparaat van de contactpersoon en in jouw kopie.

In tegenstelling tot verwijderen, mislukt dit duidelijk wanneer het kanaal weigert: je krijgt een 409 en jouw kopie blijft precies zoals de contactpersoon deze heeft, omdat het tonen van een bewerking die zij nooit hebben ontvangen de twee kanten uit de pas zou laten lopen. Het veld edit_reason vertelt je waarom — het bewerkingsvenster van het kanaal is gesloten, het kanaal is losgekoppeld, of er is iets anders misgegaan.

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"))

Antwoord (200 OK):

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

Als het kanaal de bewerking niet accepteert, krijg je in plaats daarvan een 409 en is er niets gewijzigd:

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

Een bericht dat al is verwijderd, een kanaal dat helemaal niet kan bewerken, en een bericht dat te oud is voor zijn kanaal retourneren allemaal 400 — het verzoek bereikt het kanaal nooit.

Eén bericht verwijderen #

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

Verwijdert het bericht uit je gesprek en, waar het kanaal dit toestaat, trekt ook de kopie van de contactpersoon in. Geen verzoektekst.

Dit antwoordt altijd met 200 wanneer het bericht bestond, zelfs als de kopie van de contactpersoon niet kon worden ingetrokken — jouw kopie is weg, dus een foutmelding zou misleidend zijn. Lees de drie velden in het antwoord om de gebruiker te vertellen wat er daadwerkelijk is gebeurd:

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"])

Antwoord (200 OK):

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

Verwijderde berichten worden niet uit de gespreksgeschiedenis verwijderd. Ze blijven in GET /contacts/{contactId}/messages staan met is_deleted: true en een lege body en media_url.

Meerdere berichten tegelijk verwijderen #

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

Wist een reeks berichten alleen aan jouw kant. De inhoud en bijlagen worden geleegd, maar er wordt niets ingetrokken op het apparaat van de contactpersoon — om een bericht ook daar terug te halen, verwijder je het één voor één met het bovenstaande eindpunt voor losse berichten.

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"])

Antwoord (200 OK):

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

Reageren op een bericht #

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

Plaatst je eigen emoji-reactie op een bericht, of trekt deze in door een lege tekenreeks te sturen. De reacties van de contactpersoon zelf worden nooit aangepast.

Net als bij bewerken mislukt dit in plaats van een reactie te tonen die de contactpersoon nooit heeft ontvangen, en de foutmelding vertelt je of het de moeite waard is om het opnieuw te proberen:

• 422 — het kan nooit worden afgeleverd in dit gesprek: het kanaal ondersteunt geen reacties, het bericht heeft geen kanaal-ID, of de emoji valt buiten de set die het kanaal toestaat.
• 409 — het kanaal was tijdelijk onbereikbaar. Een nieuwe poging kan werken.

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"])

Antwoord (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"
    }
  ]
}

De reactions array is de volledige set reacties die nu op het bericht staan, zowel die van jou als die van de contactpersoon. Bij een 409 of 422 wordt deze ongewijzigd geretourneerd, zodat een client die direct op basis hiervan rendert nooit een reactie toont die niet is afgeleverd.

Een bericht beoordelen of een ster geven #

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

Geeft een bericht een duim omhoog of omlaag en/of markeert het als belangrijk met een ster. Dit is alleen administratie aan jouw kant — er wordt niets naar de contactpersoon verzonden.

Verstuur ten minste een van de twee, anders krijg je een 400. Alleen wat je verstuurt wordt geschreven, dus het toevoegen van een ster aan een bericht wist nooit de beoordeling en vice versa — en het antwoord bevat alleen de velden die je hebt verstuurd.

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},
)

Antwoord (200 OK):

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

Berichten als gelezen markeren #

U kunt de ongelezen status wissen voor specifieke berichten of voor het hele gesprek.

Specifieke berichten als gelezen markeren #

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

Geef de ID’s door van de berichten die als gelezen moeten worden gemarkeerd.

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"])

Antwoord (200 OK):

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

De hele chat als gelezen markeren #

POST /contacts/{contactId}/mark-read

Wist de ongelezen-badge voor het volledige gesprek van de contactpersoon in de inbox. Er is geen verzoektekst vereist.

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"])

Antwoord (200 OK):

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

Markeer de hele chat als ongelezen #

POST /contacts/{contactId}/mark-unread

Plaatst de ongelezen-badge terug op het gesprek — handig wanneer iemand in je team een chat heeft geopend maar deze weer overdraagt. Er is geen aanvraagtekst vereist.

Dit is een vlag die alleen voor de inbox geldt: het verandert niet wanneer het gesprek voor het laatst is gelezen, dus er wordt geen leesbevestiging verstuurd naar de contactpersoon op kanalen die dit ondersteunen.

cURL

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

Antwoord (200 OK):

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

Exporteer een gesprek #

Exportbestanden geven je een volledig gesprek als een leesbaar transcript, in plaats van door berichten te bladeren. Elk export-eindpunt accepteert een filter van all (standaard), text, media of tool_use, overeenkomend met het filter op de berichtenlijst.

Exporteer de chat van één contactpersoon #

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"])

Antwoord met 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
      }
    ]
  }
}

Met format=txt (de standaard), is data in plaats daarvan een downloadlink naar het gegenereerde transcriptbestand:

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

De downloadlink is tijdelijk. Haal het bestand op zodra je de link ontvangt in plaats van deze op te slaan — vraag een nieuwe export aan wanneer je het transcript opnieuw nodig hebt.

Exporteer elk recent gesprek #

GET /chat-exports/recent

Exporteert de gesprekken van alle contacten die in de afgelopen X uur actief waren, in één aanroep.

cURL

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

Antwoord (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..."
      }
    ]
  }
}

Met format=txt is het antwoord het tekstbestand zelf, verzonden als een download in plaats van JSON.

Deze ene aanroep haalt de volledige geschiedenis op van elk overeenkomend contact, dus houd hours en limit bescheiden bij drukke accounts.

E-mail een transcript naar de contactpersoon #

POST /chat-exports/{contactId}/email

Verstuurt de contactpersoon zijn eigen gespreksverslag per e-mail — de “e-mail mij deze chat”-flow, aangestuurd vanuit je eigen systeem.

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

Antwoord (200 OK):

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

omittedCount vertelt je hoeveel van de oudste berichten zijn weggelaten om de e-mail op een redelijke lengte te houden. Een 200 betekent dat het transcript is opgesteld en in de wachtrij is geplaatst voor verzending, niet dat het al in de inbox is aangekomen.

De AI voor één contact pauzeren of hervatten #

PUT /contacts/{contactId}

Zet is_bot_active op false om te stoppen met het beantwoorden van één contact door de AI, en terug op true om het gesprek weer over te dragen. Dit is de overnameschakelaar die u wilt gebruiken wanneer een mens een gesprek overneemt: uitgaande berichten die u met de API verstuurt, worden nog steeds afgeleverd terwijl de bot is gepauzeerd.

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},
)

Antwoord

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

Pauzeren als onderdeel van het antwoord

Als een mens het overneemt door een antwoord te sturen, kunt u de bot in hetzelfde verzoek pauzeren in plaats van een tweede aanroep te doen. POST /contacts/{contactId}/send-message accepteert twee optionele vlaggen:

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

Het antwoord bevat "botPaused": true wanneer de pauze is toegepast.

Een contact markeren als privé met POST /contacts/bulk-flag pauzeert ook de bot voor hen. Zie Contacten voor de volledige lijst met velden.

Uw eigen inbox bouwen #

Alles wat een inbox nodig heeft, staat op deze pagina en in Contacten:

Voor live-updates abonneert u zich op de New Message, Replies, Human Alerted en Chat Concluded gebeurtenissen met Webhooks in plaats van deze API op een timer te pollen.

Fouten in de Messages API #

Bericht-endpoints retourneren de standaard fouten-envelop:

{
  "success": false,
  "error": "Contact not found"
}

De gedeelde codes die elk endpoint kan retourneren — 401, 403 (uw abonnement bevat geen API-toegang), 429 (snelheidslimiet) en 500 — worden vermeld met richtlijnen voor opnieuw proberen in Fouten & Paginering.

Volgende stappen #

• Webhooks — ontvang statusupdates over de bezorging in plaats van deze op te vragen.
• Contacten — maak contactpersonen aan en zoek ze op naar wie u berichten verstuurt.
• Afspraken — boek en beheer afspraken voor uw contactpersonen.