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.

Skicka via kontakt-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"])

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.

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 #

Lista chattsessioner #

En chattsession är ett konversationsfönster med en kontakt: det öppnas när de börjar prata och stängs när konversationen är avslutad. Sessioner är hur 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 tog emot skulle göra att de två sidorna inte stämmer överens. Fältet edit_reason talar om varför — kanalens redigeringsfönster har stängts, kanalen är frånkopplad eller något annat gick 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 två 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
  }'

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.