Meddelanden & konversationer #

Messages API låter dig skicka ett meddelande till vilken kontakt som helst, läsa en konversation, korrigera eller ta bort ett meddelande du redan skickat, reagera på ett, hämta en fullständig chatt-tråd, exportera en transkription och markera chattar som lästa eller olästa — allt utan att öppna inkorgen.

Alla sökvägar på denna sida är relativa till bas-URL:en https://api.youraiconnector.com/v1. Varje anrop kräver din API-nyckel — se Autentisering för en fullständig lista över hur den kan skickas. Exemplen nedan använder headern X-API-Key, där ett cURL-exempel även visar frågeformuläret ?apiKey=.

Hur leverans fungerar: Att skicka ett meddelande innebär inte att du väntar på att det ska komma fram. API:et tar emot ditt meddelande, svarar omedelbart med ett meddelande-ID och levererar det sedan i bakgrunden via kontaktens kanal (WhatsApp, SMS, Instagram, och så vidare). För att spåra om ett meddelande faktiskt har levererats eller lästs, lyssna efter statusuppdateringar med Webhooks — polla inte. Svaret vid sändning bekräftar endast att meddelandet har tagits emot.

Skicka ett meddelande #

Det finns två sätt att skicka. Välj det som passar hur du redan identifierar kontakten:

• Skicka via kontakt-ID — du känner redan till kontaktens ID (till exempel om du skapade kontakten via API:et eller fick det från en webhook). Använd POST /contacts/{contactId}/send-message.
• Skicka via kontaktidentitet — du känner till kontaktens telefonnummer, Instagram-ID, etc., men inte deras interna ID. Använd POST /contacts/send och låt plattformen hitta rätt kontakt.

Båda köar meddelandet på samma sätt och levererar det via den kanal kontakten använder. Du väljer inte transport — plattformen dirigerar WhatsApp-kontakter via WhatsApp, SMS-kontakter via SMS, och så vidare.

Båda hittar också bara kontakter som redan finns. Inget av anropen skapar en kontakt: ett ID eller en identitet som inte matchar något returneras som 404, den blir inte en ny kontakt. Så om du skickar meddelanden till någon för första gången, skapa antingen kontakten först med POST /contacts, eller använd Skicka direkt till ett WhatsApp Web-nummer nedan på WhatsApp Web, vilket skapar kontakten i samma anrop.

Skicka via kontakt-ID #

POST /contacts/{contactId}/send-message

På LinkedIn levereras ett meddelande som du skickar på detta sätt, eller från inkorgen, även medan en person hanterar tråden på LinkedIn-sidan. AI:ns egna svar och dess uppföljningar hålls tillbaka i en sådan tråd. Ett kvarhållet svar tas bort från chatten istället för att visas som misslyckat, eftersom ingenting skickades och ingen kredit förbrukades. AI:ns sista svar innan den lämnar över en tråd till en person levereras fortfarande.

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

Skicka via kontaktidentitet #

POST /contacts/send

Använd detta när du inte har kontaktens interna ID. Ange meddelandet body plus antingen ett contact_id, eller ett channel tillsammans med identitetsfältet som matchar den kanalen.

Vilka kanaler som kan identifieras via identitet. Endast sex av de 14 accepterar ett identitetsfält istället för ett contact_id: whatsapp, whatsapp_web och sms slås upp via phone_number, instagram via instagram_id, messenger via messenger_id, och telegram via telegram_user_id. De övriga åtta — instagram_private, chat-widget, custom, email, line, imessage, linkedin och viber — har ingen publik identitet att slå upp, så att skicka via dessa kanaler kräver contact_id; om du bara skickar channel returneras ett 400 som meddelar att contact_id krävs.

cURL (använder frågeformuläret ?apiKey=)

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

Varför ett meddelande kan avvisas: En kontakt med stör ej-läge eller privat läge aktiverat kan inte ta emot utgående meddelanden — begäran misslyckas med ett 422. Om ingen kontakt matchar ID:t eller identiteten du angav får du ett 404.

Skicka via WhatsApp Web: variationer och skydd mot massutskick #

Två saker gäller för body när kontakten använder WhatsApp Web.

Spintax-parenteser expanderas vid varje utskick. En body av {Hi|Hello|Hey} there, quick question skickas som en av de tre hälsningsfraserna, vald för just det utskicket — parenteserna når aldrig kontakten. Använd detta för att ge varje kontakt ett unikt öppningsmeddelande från samma integrationskod. Text utan parenteser skickas exakt som den är skriven.

Massutskick av identiska öppningsmeddelanden nekas. Om tio nästan identiska öppningsmeddelanden skickas från ett WhatsApp Web-nummer inom en timme till kontakter som aldrig har skrivit till dig, kommer efterföljande meddelanden inte att levereras: utskicket accepteras som vanligt (du får fortfarande en messageId), och meddelandet lämnas sedan med status: "failed" och error_code: "opener_burst", med en förklaring som är läsbar för kunden. Att försöka skicka samma text igen hjälper inte — variera texten, vänta en timme och skicka igen. Svar i befintliga konversationer påverkas aldrig. Motiveringen finns i Identiska öppningsmeddelanden leder till begränsade nummer.

Skicka direkt till ett WhatsApp Web-nummer #

POST /whatsapp-web/send

Skicka till ett telefonnummer på WhatsApp Web utan att först leta upp en kontakt. Om numret inte är en kontakt ännu, skapas kontakten i samma anrop, med AI:n avstängd för den, så att meddelandet ser ut som ett du skickat manuellt och ingen assistent tar över konversationen efteråt. En befintlig kontakt återanvänds som den är.

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

Ett lyckat anrop svarar med 202:

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

202 betyder accepterat, men ännu inte levererat. Utanför aktiva timmar hålls sändningen och skickas vid nästa tillåtna tidpunkt, såvida du inte skickade med ignoreActiveHours. Läs av meddelandets egen status med Lista en kontakts meddelanden genom att använda contactId som du fick här.

När det inte går igenom:

Ett andra anrop för samma kontakt medan en sändning fortfarande väntar svarar med 409, så en kö byggs aldrig upp bakom en person.

Logga en anteckning i en konversation #

POST /contacts/notes

Lägger till en rad i en kontakts konversation utan att skicka den. Använd den för kontext som ditt team och AI:n bör ha, men som kontakten aldrig bör se: en sammanfattning av ett telefonsamtal som din röstassistent precis genomfört, en kommentar från ditt CRM eller en anteckning från en kollega. Det fungerar i alla kanaler (WhatsApp, SMS, Instagram, Messenger, Telegram, chattwidgeten, anpassade kanaler och så vidare).

Vad händer med en anteckning:

• Den visas i chatten i inkorgen som ett gult Anteckning-kort, med författaren om du angav en.
• AI:n läser den som en del av konversationshistoriken, markerad som en intern anteckning, så att dess nästa svar tar hänsyn till den.
• Den skickas aldrig till kontakten, kostar inga meddelandekrediter och utlöser ingenting: inget AI-svar, ingen automatisering, ingen webhook, ingen avisering, ingen oläst-ikon. Den pausar inte AI:n och räknas inte som ett svar från ditt team.

Hitta kontakten på samma sätt som Skicka via kontaktidentitet: antingen dess ID, eller en channel plus den matchande identifieraren. En anteckning går endast till en kontakt som redan finns; om inget matchar är det ett 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 redan var loggad)

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

En anteckning visas i Lista en kontakts meddelanden med type: "note".

Generera ett svarsutkast med AI #

POST /contacts/{contactId}/draft-reply

Ber AI-agenten som hanterar en konversation att skriva nästa svar och returnerar texten till dig. Ingenting skickas. Det är samma utkast som knappen Generera svar i inkorgen skapar: agenten använder sin konfiguration, sin kunskapsdatabas och konversationen hittills, och svarar på kontaktens språk. Använd detta för att placera en människa (eller din egen app) mellan AI:n och kontakten: hämta utkastet, visa det för godkännande och skicka det sedan med Skicka via kontakt-ID, antingen ändrat eller som det är.

• Utkastet skrivs av agenten som är tilldelad kontakten. En kontakt som ännu inte har någon agent får den agent som skulle ha besvarat nästa meddelande.
• Under utkastprocessen kör agenten inga verktyg eller funktioner, så inga bokningar, taggar, överlämningar eller andra åtgärder utförs.
• Ingenting sparas i konversationen och kontakten ser ingenting.
• Ett utkast kostar lika många krediter som ett AI-svar från den agenten i denna konversation, och ingenting när din egen AI-nyckel är ansluten.
• Konversationen måste innehålla minst ett meddelande.

Alla brödtextfält är valfria; en tom brödtext (eller ingen brödtext) skapar ett utkast för nästa 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?"
}

Ett 400 innebär att konversationen ännu inte har några meddelanden, att dina krediter har tagit slut, eller att kontakten inte har någon agent eller kampanj att skapa utkast från (error anger vilken). Ett 404 innebär att kontakten inte finns, eller att en teammedlems nyckel är begränsad till kontakter som den inte kan se. Nyckeln eller teammedlemmen behöver behörighet att redigera meddelanden.

Använder du en AI-klient via MCP? Samma åtgärd finns tillgänglig som generate_reply_draft-verktyget.

Lista en kontakts meddelanden #

GET /contacts/{contactId}/messages

Returnerar en kontakts meddelanden, nyast först, med markörbaserad paginering.

Notering om filtrering och paginering: filter- och direction-filtren tillämpas på varje sida efter att den lästs, så en filtrerad sida kan innehålla färre objekt än limit. next_cursor fortsätter fortfarande genom hela konversationen, så fortsätt paginera tills next_cursor är 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"
}

Meddelandefält #

Ladda ner en bilaga till ett meddelande #

POST /chat-exports/media/download-url

Ger dig en ny nedladdningslänk för filen som bifogats ett meddelande: en bild, röstanteckning, video eller ett dokument. Länken fungerar i 1 timme. Använd den när du vill spara bilagor någon annanstans (till exempel för att arkivera CV:n eller röstanteckningar som en kontakt skickat), eller när media_url på ett meddelande eller en New Message webhook inte längre öppnas.

För att hitta meddelanden med bilagor, lista en kontakts meddelanden med filter=media. Varje meddelandes id och kontaktens ID utgö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
  }
}

Använder du en AI-klient via MCP? Samma åtgärd finns tillgänglig som get_chat_media_download_url-verktyget.

Lista chattsessioner #

En chattsession är ett konversationsfönster med en kontakt. Det öppnas vid det första inkommande meddelandet när ingen session är öppen, och det stängs automatiskt 48 timmar efter kontaktens senaste inkommande meddelande (varje nytt inkommande meddelande skjuter upp stängningen med ytterligare 48 timmar). Att AI:n avslutar en chatt stänger inte sessionen; den utlöser endast webbhooken Chat Concluded. Sessioner är sättet du delar upp en lång historik i läsbara konversationer istället för en oändlig lista.

Senaste sessioner för alla kontakter #

GET /chat-sessions/recent

Returnerar de sessioner som startade under de senaste X timmarna, nyast först, för varje kontakt på kontot.

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

Alla sessioner för en kontakt #

GET /chat-sessions/{contactId}

Returnerar varje chattsession för en enskild kontakt. Samma parametrar status, limit och includeMessages som ovan — hours gäller inte här.

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

Fältnamn för sessions-ID skiljer sig mellan de två slutpunkterna. Listan över senaste sessioner kallar det session_id (det innehåller även kontaktens detaljer, eftersom sessioner kommer från många kontakter); listan per kontakt kallar det id. Vilket värde som helst är det du skickar som {sessionId} när du hämtar hela tråden nedan.

När includeMessages=true, får varje session en messages-array vars poster innehåller id, body, direction, timestamp, type, channel och status.

Hämta en chatt-sessionstråd #

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

En chattsession grupperar en kontakts meddelanden i ett konversationsfönster. Denna slutpunkt returnerar hela tråden för en enskild session, äldst först, tillsammans med sessionens metadata. Du kan hitta sessions-ID:n för en kontakt via slutpunkterna för chattsessioner.

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

Objektet session rapporterar status (ChatSessionOpened medan aktiv, ChatSessionClosed när den avslutats), start_date_time, end_date_time och en läsbar tag. Matrisen messages använder samma meddelandefält som listslutpunkten.

Redigera, ta bort och reagera på meddelanden #

Dessa slutpunkter ändrar ett meddelande efter att det har skickats. Två av dem når ut till kontaktens kanal såväl som din egen kopia, så läs sektionsintroduktionen innan du kopplar ihop dem — vad som är möjligt beror helt på vilken kanal konversationen sker på.

Vad varje kanal tillåter

På alla andra kanaler — WhatsApp Business API, SMS, Instagram, Messenger, e-post, LINE, anpassade kanaler — tar en borttagning fortfarande bort meddelandet från din inkorg, men kontakten behåller sin kopia, och det är inte möjligt att redigera eller reagera alls.

Redigera ett meddelande #

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

Skriver om ett meddelande du redan har skickat, på kontaktens enhet och i din kopia.

Till skillnad från borttagning misslyckas detta tydligt när kanalen nekar: du får ett 409 och din kopia lämnas exakt som kontakten har den, eftersom att visa en redigering de aldrig tagit emot skulle göra att de två parterna inte är synkroniserade. Fältet edit_reason talar om varför — kanalens redigeringsfönster har stängts, kanalen är frånkopplad, meddelandet har en bilaga som kanalen inte kan redigera (media_not_editable: på WhatsApp Web kan endast textmeddelanden redigeras, inte texten under ett foto, en video eller en fil), eller så har något annat gått fel.

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

Om kanalen inte accepterar redigeringen får du ett 409 istället, och ingenting ändrades:

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

Ett meddelande som redan har tagits bort, en kanal som inte kan redigera alls, och ett meddelande som är för gammalt för sin kanal returnerar alla 400 — förfrågan når aldrig kanalen.

Ta bort ett meddelande #

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

Tar bort meddelandet från din konversation och, där kanalen tillåter det, drar även tillbaka kontaktens kopia. Ingen förfrågningskropp.

Detta svarar alltid 200 när meddelandet existerade, även om kontaktens kopia inte kunde dras tillbaka — din kopia är borta, så ett felmeddelande skulle vara missvisande. Läs de tre fälten i svaret för att berätta för användaren vad som faktiskt hände:

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

Borttagna meddelanden tas inte bort från konversationshistoriken. De stannar kvar i GET /contacts/{contactId}/messages med is_deleted: true och ett tomt body och media_url.

Ta bort flera meddelanden samtidigt #

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

Rensar en grupp meddelanden endast från din sida. Innehållet och bilagorna töms, men ingenting dras tillbaka på kontaktens enhet – för att även dra tillbaka ett meddelande, ta bort det ett i taget med slutpunkten för enstaka meddelanden ovan.

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
}

Reagera på ett meddelande #

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

Placerar din egen emoji-reaktion på ett meddelande, eller tar tillbaka den genom att skicka en tom sträng. Kontaktens egna reaktioner rörs aldrig.

Precis som vid redigering misslyckas detta hellre än att visa en reaktion som kontakten aldrig fick, och felet talar om för dig om det är värt att försöka igen:

• 422 — det kan aldrig levereras i denna konversation: kanalen stöder inte reaktioner, meddelandet har inget kanal-ID, eller emojin ligger utanför den uppsättning som kanalen tillåter.
• 409 — kanalen var tillfälligt oåtkomlig. Ett nytt försök kan fungera.

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

Matrisen reactions är den fullständiga uppsättningen reaktioner som nu finns på meddelandet, både dina och kontaktens. Vid ett 409 eller 422 returneras den oförändrad, så en klient som renderar direkt från den visar aldrig en reaktion som inte levererades.

Betygsätt eller stjärnmarkera ett meddelande #

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

Betygsätter ett meddelande med tumme upp eller tumme ner och/eller stjärnmarkerar det som viktigt. Detta är endast bokföring på din sida – ingenting skickas till kontakten.

Skicka minst ett av de två, annars får du ett 400. Endast det du skickar skrivs, så att stjärnmarkera ett meddelande rensar aldrig dess betyg och vice versa — och svaret återspeglar endast de fält du skickade.

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
}

Markera meddelanden som lästa #

Du kan rensa oläst-statusen antingen för specifika meddelanden eller för hela konversationen.

Markera specifika meddelanden som lästa #

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

Skicka med ID:n för de meddelanden som ska markeras som lästa.

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
}

Markera hela chatten som läst #

POST /contacts/{contactId}/mark-read

Rensar oläst-markeringen för kontaktens hela konversation i inkorgen. Ingen förfrågningskropp krävs.

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

Markera hela chatten som oläst #

POST /contacts/{contactId}/mark-unread

Sätter tillbaka oläst-markeringen på konversationen — praktiskt när någon i ditt team har öppnat en chatt men lämnar över den igen. Ingen förfrågningskropp krävs.

Detta är en flagga som endast gäller inkorgen: den ändrar inte när konversationen senast lästes, så inget läskvitto skickas till kontakten på kanaler som stöder 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"
}

Exportera en konversation #

Exporter ger dig en hel konversation som en läsbar transkription, istället för att bläddra igenom meddelanden. Varje export-endpoint accepterar en filter av all (standard), text, media eller tool_use, som matchar filtret i meddelandelistan.

Exportera en kontakts chatt #

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), är data istället en nedladdningslänk till den genererade transkriptionsfilen:

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

Nedladdningslänken är kortlivad. Hämta filen så snart du får länken istället för att lagra den — begär en ny export när du behöver transkriptionen igen.

Exportera alla senaste konversationer #

GET /chat-exports/recent

Exporterar konversationer för alla kontakter som varit aktiva under de senaste X timmarna, i ett anrop.

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 är svaret själva textfilen, som skickas som en nedladdning istället för JSON.

Detta anrop hämtar hela historiken för varje matchande kontakt, så håll hours och limit måttliga på konton med hög aktivitet.

E-posta en transkription till kontakten #

POST /chat-exports/{contactId}/email

Skickar kontaktens egen konversationstranskription via e-post — “e-posta mig denna chatt”-flödet, drivet från ditt 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 anger hur många av de äldsta meddelandena som utelämnades för att hålla e-postmeddelandet i en rimlig längd. Ett 200 innebär att transkriptionen skapades och köades för sändning, inte att den har landat i inkorgen än.

Pausa eller återuppta AI:n för en kontakt #

PUT /contacts/{contactId}

Sätt is_bot_active till false för att stoppa AI:n från att svara en kontakt, och tillbaka till true för att lämna tillbaka konversationen. Detta är växeln du vill använda när en människa kliver in i en konversation: utgående meddelanden som du skickar via API:et levereras fortfarande medan boten är pausad.

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

Pausa som en del av svaret

Om en människa tar över genom att skicka ett svar kan du pausa boten i samma anrop istället för att göra ett andra anrop. POST /contacts/{contactId}/send-message accepterar dessa valfria flaggor:

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 inkluderar "botPaused": true när pausen har tillämpats.

Att markera en kontakt som privat med POST /contacts/bulk-flag pausar även boten för dem. Se Kontakter för hela listan över fält.

Bygga din egen inkorg #

Allt en inkorg behöver finns på denna sida och i Kontakter:

För live-uppdateringar, prenumerera på händelserna New Message, Replies, Human Alerted och Chat Concluded med Webhooks istället för att polla detta API med en timer.

Fel i Messages API #

Meddelandeslutpunkter returnerar standardfel-kuvertet:

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

De delade koderna som alla slutpunkter kan returnera — 401, 403 (din plan inkluderar inte API-åtkomst), 429 (hastighetsbegränsning) och 500 — listas med vägledning för återförsök i Fel & Paginering.

Nästa steg #

• Webhooks — få uppdateringar om leveransstatus skickade till dig istället för att polla.
• Kontakter — skapa och slå upp kontakterna du skickar meddelanden till.
• Bokningar — boka och hantera bokningar för dina kontakter.