Beskeder & samtaler #

Messages API’et lader dig sende en besked til enhver kontakt, læse en samtale igennem, rette eller fjerne en besked, du allerede har sendt, reagere på en besked, hente en fuld chat-sessionstråd, eksportere en transskription og markere chats som læste eller ulæste — alt sammen uden at åbne indbakken.

Alle stier på denne side er relative til basis-URL’en https://api.youraiconnector.com/v1. Hver anmodning kræver din API-nøgle — se Godkendelse for den fulde liste over måder at sende den på. Eksemplerne nedenfor bruger X-API-Key-headeren, hvor et cURL-eksempel også viser ?apiKey=-forespørgselsformen.

Sådan fungerer levering: Afsendelse af en besked venter ikke på, at den når frem. API’et accepterer din besked, returnerer med det samme et besked-ID og leverer den derefter i baggrunden på kontaktens kanal (WhatsApp, SMS, Instagram osv.). For at spore, om en besked rent faktisk blev leveret eller læst, skal du lytte efter statusopdateringer med Webhooks — lad være med at polle. Svaret ved afsendelse bekræfter kun, at beskeden blev accepteret.

Send en besked #

Der er to måder at sende på. Vælg den, der passer til, hvordan du allerede identificerer kontakten:

• Send via kontakt-ID — du kender allerede kontaktens ID (f.eks. har du oprettet kontakten via API’et eller fået det fra en webhook). Brug POST /contacts/{contactId}/send-message.
• Send via kontaktidentitet — du kender kontaktens telefonnummer, Instagram-ID osv., men ikke deres interne ID. Brug POST /contacts/send og lad platformen finde den rigtige kontakt.

Begge køer beskeden på samme måde og leverer den på den kanal, kontakten befinder sig på. Du vælger ikke transport — platformen ruter WhatsApp-kontakter via WhatsApp, SMS-kontakter via SMS og så videre.

Begge finder også kun kontakter, der allerede eksisterer. Ingen af kaldene opretter en: et ID eller en identitet, som intet matcher, returneres som 404, den bliver ikke til en ny kontakt. Så hvis du sender en besked til nogen for første gang, skal du enten oprette kontakten først med POST /contacts, eller på WhatsApp Web bruge Send direkte til et WhatsApp Web-nummer herunder, hvilket opretter kontakten i samme kald.

Send via kontakt-ID #

POST /contacts/{contactId}/send-message

På LinkedIn leveres en besked, du sender på denne måde eller fra indbakken, selv mens en person håndterer tråden på LinkedIn-siden. AI’ens egne svar og dens opfølgninger tilbageholdes i en sådan tråd. Et tilbageholdt svar fjernes fra chatten i stedet for at blive vist som mislykket, fordi intet blev sendt, og der ikke bruges nogen kredit. AI’ens sidste svar, før den overdrager en tråd til en person, leveres stadig.

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

Svar (200 OK):

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

Send via kontaktidentitet #

POST /contacts/send

Brug denne, når du ikke har kontaktens interne ID. Angiv beskedens body plus enten en contact_id, eller en channel sammen med identitetsfeltet, der matcher den kanal.

Hvilke kanaler kan løses via identitet. Kun seks af de 14 accepterer et identitetsfelt i stedet for et contact_id: whatsapp, whatsapp_web og sms opslås via phone_number, instagram via instagram_id, messenger via messenger_id, og telegram via telegram_user_id. De andre otte — instagram_private, chat-widget, custom, email, line, imessage, linkedin og viber — har ingen offentlig identitet, der kan opslås, så afsendelse på disse kanaler kræver contact_id; hvis du kun sender channel, returneres en 400, der fortæller dig, at contact_id er påkrævet.

cURL (ved brug af ?apiKey= forespørgselsformen)

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

Svar (201 Created):

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

Hvorfor en besked kan blive afvist: En kontakt med forstyr-ikke eller privat tilstand aktiveret kan ikke modtage udgående beskeder — anmodningen fejler med en 422. Hvis ingen kontakt matcher det ID eller den identitet, du har angivet, får du en 404.

Afsendelse via WhatsApp Web: variationer og beskyttelse mod burst-afsendelse #

To ting gør sig gældende for body, når kontakten er på WhatsApp Web.

Spintax-parenteser udvides ved hver afsendelse. En body af {Hi|Hello|Hey} there, quick question sendes som en af de tre hilsner, valgt til den pågældende afsendelse — parenteserne når aldrig frem til kontakten. Brug det til at give hver kontakt en forskellig åbningsbesked fra den samme integrationskode. Tekst uden parenteser sendes præcis som skrevet.

Burst-afsendelser af identiske åbningsbeskeder afvises. Hvis ti næsten identiske åbningsbeskeder sendes fra ét WhatsApp Web-nummer inden for en time til kontakter, der aldrig har skrevet til dig, bliver efterfølgende beskeder ikke leveret: afsendelsen accepteres som normalt (du modtager stadig en messageId), og beskeden efterlades derefter med status: "failed" og error_code: "opener_burst", med en årsag, som kunden kan læse. Det hjælper ikke at forsøge igen med den samme tekst — varier teksten, vent en time, og send igen. Svar i eksisterende samtaler påvirkes aldrig. Begrundelsen findes i Identiske åbningsbeskeder fører til begrænsning af numre.

Send direkte til et WhatsApp Web-nummer #

POST /whatsapp-web/send

Send til et telefonnummer på WhatsApp Web uden først at slå en kontakt op. Hvis nummeret endnu ikke er en kontakt, oprettes kontakten i samme kald, med AI’en slået fra for den, så beskeden fremstår som en, du selv har sendt, og ingen assistent overtager samtalen bagefter. En eksisterende kontakt genbruges, som den er.

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

Et vellykket kald svarer med 202:

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

202 betyder accepteret, ikke leveret endnu. Uden for aktive timer holdes afsendelsen tilbage og sendes i det næste tilladte tidsrum, medmindre du angav ignoreActiveHours. Læs beskedens egen status tilbage med List en kontakts beskeder ved hjælp af det contactId, du fik her.

Når det ikke går igennem:

Et andet kald til den samme kontakt, mens en afsendelse stadig venter, svarer med 409, så der aldrig opbygges en kø bag én person.

Log en note i en samtale #

POST /contacts/notes

Tilføjer en linje til en kontakts samtale uden at sende den. Brug den til kontekst, som dit team og AI’en skal have, men som kontakten aldrig må modtage: et resumé af et telefonopkald, din stemmeassistent lige har foretaget, en bemærkning fra dit CRM eller en note fra en kollega. Det fungerer på alle kanaler (WhatsApp, SMS, Instagram, Messenger, Telegram, chat-widgetten, brugerdefinerede kanaler og så videre).

Hvad sker der med en note:

• Den vises i chatten i indbakken som et gult Note-kort med forfatteren, hvis du har angivet en.
• AI’en læser den som en del af samtaleloggen, markeret som en intern note, så dens næste svar tager højde for den.
• Den sendes aldrig til kontakten, koster ingen beskedkreditter og udløser intet: intet AI-svar, ingen automatisering, ingen webhook, ingen notifikation, intet ulæst-badge. Den sætter ikke AI’en på pause og tæller ikke som et svar fra dit team.

Find kontakten på samme måde som Send via kontaktidentitet: enten dens ID eller en channel plus den matchende identifikator. En note sendes kun til en kontakt, der allerede eksisterer; intet match er en 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"
  }'

Svar (201 eller 200 med duplicate: true, når external_id allerede var logget)

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

En note vises i List en kontakts beskeder med type: "note".

Generer et svarkladde med AI’en #

POST /contacts/{contactId}/draft-reply

Beder den AI-agent, der håndterer en samtale, om at skrive det næste svar og returnerer teksten til dig. Intet sendes. Det er den samme kladde, som knappen Generer svar i indbakken skriver: agenten bruger sin opsætning, sin vidensbase og samtalen indtil videre, og svarer på kontaktens sprog. Brug den til at placere et menneske (eller din egen app) mellem AI’en og kontakten: hent kladden, vis den til godkendelse, og send den derefter med Send via kontakt-id, enten ændret eller som den er.

• Kladden skrives af den agent, der er tildelt kontakten. En kontakt, der endnu ikke har en agent, får den agent, der ville besvare dens næste besked.
• Under udarbejdelsen af kladden kører agenten ingen værktøjer eller funktioner, så ingen booking, tagging, overdragelse eller andre handlinger finder sted.
• Intet gemmes i samtalen, og kontakten ser intet.
• En kladde koster det samme antal kreditter som ét AI-svar fra den pågældende agent i denne samtale, og intet når din egen AI-nøgle er tilsluttet.
• Samtalen skal indeholde mindst én besked.

Alle brødtekstfelter er valgfrie; en tom brødtekst (eller ingen brødtekst) genererer et udkast til det næste svar.

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

Svar (200)

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

En 400 betyder, at samtalen endnu ikke har nogen beskeder, dine kreditter er opbrugt, eller kontakten ikke har nogen agent eller kampagne at generere fra (error angiver hvilken). En 404 betyder, at kontakten ikke eksisterer, eller at et teammedlems nøgle er begrænset til kontakter, som vedkommende ikke kan se. Nøglen eller teammedlemmet skal have tilladelse til at redigere beskeder.

Bruger du en AI-klient via MCP? Den samme handling er tilgængelig som generate_reply_draft-værktøjet.

Vis en kontakts beskeder #

GET /contacts/{contactId}/messages

Returnerer en kontakts beskeder, nyeste først, med markør-baseret paginering.

Bemærkning om filtrering og paginering: filter- og direction-filtrene anvendes på hver side, efter den er læst, så en filtreret side kan indeholde færre elementer end limit. next_cursor bevæger sig stadig gennem hele samtalen, så fortsæt med at paginere, indtil next_cursor er 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"])

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

Beskedfelter #

Download en beskedvedhæftning #

POST /chat-exports/media/download-url

Giver dig et nyt downloadlink til filen, der er vedhæftet en besked: et billede, en talebesked, en video eller et dokument. Linket virker i 1 time. Brug det, når du vil gemme vedhæftede filer et andet sted (f.eks. arkivering af CV’er eller talebeskeder, som en kontakt har sendt), eller når media_url på en besked eller en New Message webhook ikke længere åbner.

For at finde beskeder med vedhæftede filer skal du liste en kontakts beskeder med filter=media. Hver beskeds id og kontaktens ID udgør messagePath.

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

Svar (200 OK):

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

Bruger du en AI-klient via MCP? Den samme handling er tilgængelig som get_chat_media_download_url-værktøjet.

List chat-sessioner #

En chatsession er ét samtalevindue med en kontaktperson. Det åbnes ved den første indgående besked, når ingen session er åben, og det lukkes automatisk 48 timer efter kontaktpersonens sidste indgående besked (hver ny indgående besked forlænger lukketidspunktet med yderligere 48 timer). Når AI’en afslutter en chat, lukkes sessionen ikke; den udløser kun webhooken Chat Concluded. Sessioner er måden, hvorpå du opdeler en lang historik i læsbare samtaler i stedet for én endeløs liste.

Seneste sessioner på tværs af alle kontakter #

GET /chat-sessions/recent

Returnerer de sessioner, der startede inden for de sidste X timer, nyeste først, på tværs af alle kontakter på kontoen.

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

Svar (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 sessioner for én kontakt #

GET /chat-sessions/{contactId}

Returnerer hver chat-session for en enkelt kontakt. Samme status, limit og includeMessages parametre som ovenfor — hours gælder ikke her.

cURL

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

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

Feltnavne for session-ID er forskellige mellem de to slutpunkter. Listen over seneste sessioner kalder det session_id (det indeholder også kontaktens detaljer, da sessioner kommer fra mange kontakter); listen pr. kontakt kalder det id. Begge værdier er det, du sender som {sessionId}, når du henter den fulde tråd nedenfor.

Når includeMessages=true, får hver session et messages-array, hvis poster indeholder id, body, direction, timestamp, type, channel og status.

Hent en chat-sessionstråd #

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

En chatsession grupperer en kontakts beskeder i ét samtalevindue. Dette slutpunkt returnerer hele tråden for en enkelt session, ældste først, sammen med sessionens metadata. Du kan finde sessions-id’er for en kontakt via slutpunkterne for chatsessioner.

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

Svar (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-objektet rapporterer status (ChatSessionOpened mens aktiv, ChatSessionClosed når afsluttet), start_date_time, end_date_time og et læsbart tag. messages-arrayet bruger de samme beskedfelter som listeslutpunktet.

Rediger, slet og reager på beskeder #

Disse slutpunkter ændrer en besked, efter den er blevet sendt. To af dem kontakter både modtagerens kanal og din egen kopi, så læs sektionsintroduktionen, før du implementerer dem — hvad der er muligt, afhænger udelukkende af den kanal, samtalen foregår på.

Hvad hver kanal tillader

På alle andre kanaler — WhatsApp Business API, SMS, Instagram, Messenger, e-mail, LINE, tilpassede kanaler — fjerner en sletning stadig beskeden fra din indbakke, men kontakten beholder sin kopi, og redigering eller reaktion er slet ikke muligt.

Rediger en besked #

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

Omskriver en besked, du allerede har sendt, på kontaktens enhed og i din kopi.

I modsætning til sletning fejler dette tydeligt, når kanalen afviser det: Du får en 409, og din kopi forbliver præcis, som kontakten har den, da det at vise en redigering, de aldrig har modtaget, ville bringe de to parter ud af takt. Feltet edit_reason fortæller dig hvorfor — kanalens redigeringsvindue er lukket, kanalen er afbrudt, beskeden har en vedhæftet fil, som kanalen ikke kan redigere (media_not_editable: på WhatsApp Web kan kun tekstbeskeder redigeres, ikke teksten under et billede, en video eller en fil), eller noget andet gik galt.

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

Svar (200 OK):

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

Hvis kanalen ikke vil acceptere redigeringen, får du en 409 i stedet, og intet blev ændret:

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

En besked, der allerede er slettet, en kanal, der slet ikke kan redigere, og en besked, der er for gammel til sin kanal, returnerer alle 400 — anmodningen når aldrig frem til kanalen.

Slet én besked #

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

Fjerner beskeden fra din samtale og trækker, hvor kanalen tillader det, også kontaktens kopi tilbage. Ingen anmodningstekst.

Dette svarer altid 200, når beskeden eksisterede, selvom kontaktens kopi ikke kunne trækkes tilbage — din kopi er væk, så en fejl ville være vildledende. Læs de tre felter i svaret for at fortælle brugeren, hvad der faktisk skete:

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

Svar (200 OK):

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

Slettede beskeder fjernes ikke fra samtaleloggen. De forbliver i GET /contacts/{contactId}/messages med is_deleted: true og en tom body og media_url.

Slet flere beskeder på én gang #

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

Rydder en gruppe beskeder kun fra din side. Indholdet og vedhæftede filer tømmes, men intet trækkes tilbage på kontaktens enhed — for også at trække en besked tilbage, skal du slette den én efter én med slutpunktet for enkelte beskeder ovenfor.

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

Svar (200 OK):

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

Reager på en besked #

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

Tilføjer din egen emoji-reaktion på en besked, eller fjerner den ved at sende en tom streng. Kontaktens egne reaktioner bliver aldrig berørt.

Ligesom ved redigering fejler dette frem for at vise en reaktion, som kontakten aldrig har modtaget, og fejlen fortæller dig, om det kan betale sig at prøve igen:

• 422 — den kan aldrig leveres i denne samtale: kanalen understøtter ikke reaktioner, beskeden har intet kanal-id, eller emojien er uden for det sæt, som kanalen tillader.
• 409 — kanalen var midlertidigt utilgængelig. Et nyt forsøg kan virke.

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

Svar (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-arrayet er det fulde sæt af reaktioner, der nu er på beskeden, både dine og kontaktens. Ved en 409 eller 422 returneres det uændret, så en klient, der renderer direkte ud fra det, aldrig viser en reaktion, der ikke blev leveret.

Bedøm eller stjernemarkér en besked #

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

Giver en besked en tommelfinger op eller ned og/eller markerer den som vigtig. Dette er kun bogføring på din side — intet sendes til kontakten.

Send mindst én af de to, ellers får du en 400. Kun det, du sender, bliver skrevet, så at markere en besked med stjerne rydder aldrig dens bedømmelse og omvendt — og svaret sender kun de felter tilbage, som du sendte.

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

Svar (200 OK):

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

Markér beskeder som læst #

Du kan fjerne ulæst-status enten for specifikke beskeder eller for hele samtalen.

Markér specifikke beskeder som læst #

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

Angiv id’erne for de beskeder, der skal markeres som læst.

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

Svar (200 OK):

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

Markér hele chatten som læst #

POST /contacts/{contactId}/mark-read

Fjerner ulæst-ikonet for kontaktens samlede samtale i indbakken. Der kræves ingen anmodningstekst.

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

Svar (200 OK):

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

Marker hele chatten som ulæst #

POST /contacts/{contactId}/mark-unread

Sætter det ulæste-badge tilbage på samtalen — praktisk når en person på dit team har åbnet en chat, men giver den videre. Der kræves ingen anmodningstekst.

Dette er et flag, der kun gælder indbakken: det ændrer ikke, hvornår samtalen sidst blev læst, så der sendes ingen læsekvittering til kontakten på kanaler, der understøtter dem.

cURL

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

Svar (200 OK):

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

Eksporter en samtale #

Eksport giver dig en hel samtale som en læsbar udskrift i stedet for at skulle bladre gennem beskeder. Hvert eksport-endepunkt accepterer en filter af all (standard), text, media eller tool_use, svarende til filteret på beskedlisten.

Eksporter én kontakts chat #

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

Svar med 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
      }
    ]
  }
}

Med format=txt (standard), er data i stedet et downloadlink til den genererede udskriftsfil:

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

Downloadlinket er kortvarigt. Hent filen så snart du får linket i stedet for at gemme det — anmod om en ny eksport, når du har brug for udskriften igen.

Eksporter alle nylige samtaler #

GET /chat-exports/recent

Eksporterer samtalerne for alle kontakter, der har været aktive inden for de sidste X timer, i ét kald.

cURL

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

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

Med format=txt er svaret selve tekstfilen, der sendes som en download i stedet for JSON.

Dette ene kald henter hele historikken for hver matchende kontakt, så hold hours og limit på et moderat niveau på travle konti.

Send en transskription til kontakten via e-mail #

POST /chat-exports/{contactId}/email

Sender kontakten deres egen samtaletransskription via e-mail — “send mig denne chat”-flowet, drevet fra dit eget system.

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

Svar (200 OK):

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

omittedCount fortæller dig, hvor mange af de ældste beskeder der blev udeladt for at holde e-mailen i en fornuftig længde. En 200 betyder, at transskriptionen blev oprettet og sat i kø til afsendelse, ikke at den er landet i indbakken endnu.

Sæt AI på pause eller genoptag for én kontakt #

PUT /contacts/{contactId}

Sæt is_bot_active til false for at stoppe AI’en i at svare en kontakt, og tilbage til true for at give samtalen tilbage. Dette er den overtagelseskontakt, du skal bruge, når et menneske træder ind i en samtale: udgående beskeder, du sender med API’en, leveres stadig, mens botten er sat på pause.

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

Svar

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

Pause som en del af svaret

Hvis et menneske overtager ved at sende et svar, kan du sætte botten på pause i den samme anmodning i stedet for at foretage et andet kald. POST /contacts/{contactId}/send-message accepterer disse valgfrie flag:

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

Svaret inkluderer "botPaused": true, når pausen blev anvendt.

Markering af en kontakt som privat med POST /contacts/bulk-flag sætter også botten på pause for dem. Se Kontakter for den fulde liste over felter.

Byg din egen indbakke #

Alt, hvad en indbakke har brug for, findes på denne side og i Kontakter:

For live-opdateringer, abonner på New Message, Replies, Human Alerted og Chat Concluded begivenhederne med Webhooks i stedet for at polle denne API på en timer.

Fejl i Messages API #

Besked-endpoints returnerer standardfejl-konvolutten:

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

De delte koder, som ethvert endpoint kan returnere — 401, 403 (din plan inkluderer ikke API-adgang), 429 (rate limit) og 500 — er angivet med vejledning om genforsøg i Errors & Pagination.

Næste skridt #

• Webhooks — få leveringsstatusopdateringer sendt til dig i stedet for at polle.
• Kontakter — opret og find de kontakter, du sender beskeder til.
• Aftaler — book og administrer aftaler for dine kontakter.