Mesaje și conversații #

API-ul de mesaje vă permite să trimiteți un mesaj oricărui contact, să citiți o conversație, să corectați sau să ștergeți un mesaj deja trimis, să reacționați la acesta, să extrageți un fir complet de sesiune de chat, să exportați o transcriere și să marcați chat-urile ca citite sau necitite — totul fără a deschide inbox-ul.

Toate căile de pe această pagină sunt relative la URL-ul de bază https://api.youraiconnector.com/v1. Fiecare cerere necesită cheia dvs. API — consultați Autentificare pentru lista completă a modalităților de trimitere a acesteia. Exemplele de mai jos utilizează antetul X-API-Key, un exemplu cURL arătând și forma de interogare ?apiKey=.

Cum funcționează livrarea: Trimiterea unui mesaj nu așteaptă ca acesta să ajungă la destinație. API-ul acceptă mesajul dvs., returnează imediat un ID de mesaj și apoi îl livrează în fundal pe canalul contactului (WhatsApp, SMS, Instagram etc.). Pentru a urmări dacă un mesaj a fost livrat sau citit efectiv, ascultați actualizările de stare cu Webhooks — nu interogați (poll). Răspunsul de trimitere confirmă doar că mesajul a fost acceptat.

Trimiteți un mesaj #

Există două modalități de a trimite. Alegeți-o pe cea care se potrivește modului în care identificați deja contactul:

• Trimitere prin ID-ul contactului — cunoașteți deja ID-ul contactului (de exemplu, ați creat contactul prin API sau l-ați obținut dintr-un webhook). Utilizați POST /contacts/{contactId}/send-message.
• Trimitere prin identitatea contactului — cunoașteți numărul de telefon al contactului, ID-ul de Instagram etc., dar nu și ID-ul lor intern. Utilizați POST /contacts/send și lăsați platforma să găsească contactul potrivit.

Ambele pun mesajul în coadă în același mod și îl livrează pe canalul pe care se află contactul. Nu alegeți un transport — platforma direcționează contactele WhatsApp prin WhatsApp, contactele SMS prin SMS și așa mai departe.

Trimitere prin ID-ul contactului #

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

Răspuns (200 OK):

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

Trimitere prin identitatea contactului #

POST /contacts/send

Utilizați acest lucru atunci când nu aveți ID-ul intern al contactului. Furnizați body mesajului plus fie un contact_id, fie un channel împreună cu câmpul de identitate care corespunde acelui canal.

Ce canale pot fi identificate prin identitate. Doar șase din cele 14 acceptă un câmp de identitate în locul unui contact_id: whatsapp, whatsapp_web și sms sunt căutate prin phone_number, instagram prin instagram_id, messenger prin messenger_id, și telegram prin telegram_user_id. Celelalte opt — instagram_private, chat-widget, custom, email, line, imessage, linkedin și viber — nu au nicio identitate publică de căutat, deci trimiterea prin acele canale necesită contact_id; transmiterea doar a channel returnează un 400 care vă informează că contact_id este necesar.

cURL (folosind forma de interogare ?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"])

Răspuns (201 Created):

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

De ce un mesaj ar putea fi respins: Un contact care are activat modul „nu deranjați” sau modul privat nu poate primi mesaje de ieșire — cererea eșuează cu un 422. Dacă niciun contact nu corespunde ID-ului sau identității furnizate, veți primi un 404.

Listarea mesajelor unui contact #

GET /contacts/{contactId}/messages

Returnează mesajele unui contact, cele mai noi primele, cu paginare bazată pe cursor.

Notă despre filtrare și paginare: Filtrele filter și direction sunt aplicate fiecărei pagini după ce este citită, deci o pagină filtrată poate conține mai puține elemente decât limit. next_cursor avansează în continuare prin întreaga conversație, așa că continuați paginarea până când next_cursor este 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"])

Răspuns (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"
}

Câmpurile mesajului #

Listarea sesiunilor de chat #

O sesiune de chat este o fereastră de conversație cu un contact: se deschide când acesta începe să vorbească și se închide când conversația este încheiată. Sesiunile reprezintă modul în care puteți împărți un istoric lung în conversații lizibile, în loc de o listă nesfârșită.

Sesiuni recente pentru toate contactele #

GET /chat-sessions/recent

Returnează sesiunile care au început în ultimele X ore, cele mai noi primele, pentru fiecare contact din cont.

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

Răspuns (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"
      }
    ]
  }
}

Toate sesiunile pentru un singur contact #

GET /chat-sessions/{contactId}

Returnează fiecare sesiune de chat pentru un singur contact. Aceiași parametri status, limit și includeMessages ca mai sus — hours nu se aplică aici.

cURL

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

Răspuns (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"
      }
    ]
  }
}

Numele câmpurilor ID-ului de sesiune diferă între cele două endpoint-uri. Lista sesiunilor recente îl numește session_id (conține și detaliile contactului, deoarece sesiunile provin de la mai multe contacte); lista per-contact îl numește id. Oricare dintre aceste valori este cea pe care o transmiteți ca {sessionId} atunci când preluați firul complet de mai jos.

Când includeMessages=true, fiecare sesiune primește un tablou messages ale cărui intrări conțin id, body, direction, timestamp, type, channel și status.

Preluarea unui fir de conversație #

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

O sesiune de chat grupează mesajele unui contact într-o singură fereastră de conversație. Acest endpoint returnează întregul fir al unei singure sesiuni, de la cel mai vechi la cel mai nou, împreună cu metadatele sesiunii. Puteți găsi ID-urile sesiunilor pentru un contact prin intermediul endpoint-urilor pentru sesiuni de chat.

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

Răspuns (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
    }
  ]
}

Obiectul session raportează status (ChatSessionOpened cât timp este activ, ChatSessionClosed odată încheiat), start_date_time, end_date_time și un tag ușor de citit de către oameni. Matricea messages folosește aceleași câmpuri de mesaj ca și endpoint-ul de listare.

Editarea, ștergerea și reacționarea la mesaje #

Aceste endpoint-uri modifică un mesaj după ce a fost trimis. Două dintre ele interacționează atât cu canalul contactului, cât și cu propria dvs. copie, așa că citiți introducerea secțiunii înainte de a le implementa — ceea ce este posibil depinde în întregime de canalul pe care se desfășoară conversația.

Ce permite fiecare canal

Pe toate celelalte canale — WhatsApp Business API, SMS, Instagram, Messenger, e-mail, LINE, canale personalizate — o ștergere elimină mesajul din inbox-ul tău, dar contactul își păstrează copia, iar editarea sau reacționarea nu sunt posibile deloc.

Editarea unui mesaj #

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

Rescrie un mesaj pe care l-ai trimis deja, pe dispozitivul contactului și în copia ta.

Spre deosebire de ștergere, aceasta eșuează zgomotos atunci când canalul refuză: primești un 409, iar copia ta rămâne exact așa cum o are contactul, deoarece afișarea unei editări pe care aceștia nu au primit-o niciodată ar duce la o neconcordanță între cele două părți. Câmpul edit_reason îți spune de ce — fereastra de editare a canalului s-a închis, canalul este deconectat sau a apărut o altă eroare.

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

Răspuns (200 OK):

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

Dacă canalul nu acceptă editarea, primești în schimb un 409 și nimic nu a fost modificat:

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

Un mesaj care a fost deja șters, un canal care nu poate edita deloc și un mesaj care este prea vechi pentru canalul său returnează toate 400 — cererea nu ajunge niciodată la canal.

Ștergerea unui mesaj #

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

Elimină mesajul din conversația ta și, acolo unde canalul permite, retrage și copia contactului. Fără corp de cerere.

Aceasta răspunde întotdeauna cu 200 atunci când mesajul a existat, chiar dacă copia contactului nu a putut fi retrasă — copia ta este ștearsă, deci o eroare ar fi înșelătoare. Citește cele trei câmpuri din răspuns pentru a-i spune utilizatorului ce s-a întâmplat de fapt:

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

Răspuns (200 OK):

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

Mesajele șterse nu sunt eliminate din istoricul conversației. Acestea rămân în GET /contacts/{contactId}/messages cu is_deleted: true și un body gol și media_url.

Ștergeți mai multe mesaje simultan #

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

Șterge un lot de mesaje doar din partea ta. Conținutul și atașamentele sunt golite, dar nimic nu este retras de pe dispozitivul contactului — pentru a retrage și un mesaj, ștergeți-l pe rând folosind endpoint-ul pentru un singur mesaj de mai sus.

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

Răspuns (200 OK):

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

Reacționați la un mesaj #

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

Adaugă propria reacție emoji la un mesaj sau o retrage prin trimiterea unui șir gol. Reacțiile contactului nu sunt niciodată modificate.

La fel ca editarea, aceasta eșuează în loc să afișeze o reacție pe care contactul nu a primit-o niciodată, iar eșecul vă indică dacă merită să reîncercați:

• 422 — nu poate fi livrat niciodată în această conversație: canalul nu acceptă reacții, mesajul nu are un ID pe partea canalului sau emoji-ul este în afara setului permis de acel canal.
• 409 — canalul a fost temporar inaccesibil. O reîncercare ar putea funcționa.

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

Răspuns (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"
    }
  ]
}

Matricea reactions reprezintă setul complet de reacții existente acum pe mesaj, atât ale tale, cât și ale contactului. La un 409 sau 422, aceasta este returnată neschimbată, astfel încât un client care randează direct din ea nu va afișa niciodată o reacție care nu a fost livrată.

Evaluați sau marcați un mesaj cu stea #

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

Evaluează un mesaj cu degetul în sus sau în jos și/sau îl marchează ca important. Aceasta este o evidență doar pe partea ta — nimic nu este trimis contactului.

Trimite cel puțin unul dintre cele două, altfel vei primi o eroare 400. Doar ceea ce trimiți este scris, deci marcarea unui mesaj ca favorit nu îi șterge niciodată evaluarea și invers — iar răspunsul returnează doar câmpurile pe care le-ai trimis.

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

Răspuns (200 OK):

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

Marcarea mesajelor ca citite #

Puteți șterge starea de necitit fie pentru mesaje specifice, fie pentru întreaga conversație.

Marcarea mesajelor specifice ca citite #

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

Transmiteți ID-urile mesajelor care trebuie marcate ca citite.

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

Răspuns (200 OK):

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

Marcarea întregului chat ca citit #

POST /contacts/{contactId}/mark-read

Șterge insigna de necitit pentru întreaga conversație a contactului din inbox. Nu este necesar niciun corp de cerere.

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

Răspuns (200 OK):

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

Marchează întreaga conversație ca necitită #

POST /contacts/{contactId}/mark-unread

Pune din nou insigna de necitit pe conversație — util atunci când cineva din echipa ta a deschis un chat, dar îl predă înapoi. Nu este necesar un corp al cererii.

Acesta este un indicator valabil doar pentru inbox: nu modifică momentul în care conversația a fost citită ultima dată, deci nu este trimisă nicio confirmare de citire către contact pe canalele care le suportă.

cURL

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

Răspuns (200 OK):

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

Exportă o conversație #

Exporturile îți oferă o conversație întreagă sub formă de transcriere lizibilă, în loc să parcurgi mesajele pagină cu pagină. Fiecare endpoint de export acceptă un filter de tip all (implicit), text, media sau tool_use, corespunzător filtrului din lista de mesaje.

Exportă chat-ul unui singur contact #

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

Răspuns cu 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
      }
    ]
  }
}

Cu format=txt (implicit), data este în schimb un link de descărcare către fișierul de transcriere generat:

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

Linkul de descărcare are o durată scurtă de viață. Descarcă fișierul imediat ce primești linkul, în loc să îl stochezi — solicită un export nou atunci când ai din nou nevoie de transcriere.

Exportă toate conversațiile recente #

GET /chat-exports/recent

Exportă conversațiile tuturor contactelor care au fost active în ultimele X ore, într-un singur apel.

cURL

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

Răspuns (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..."
      }
    ]
  }
}

Cu format=txt, răspunsul este fișierul text propriu-zis, trimis ca descărcare în loc de JSON.

Acest apel unic extrage istoricul complet al fiecărui contact corespondent, așa că păstrați hours și limit la valori moderate în conturile ocupate.

Trimiteți o transcriere prin e-mail contactului #

POST /chat-exports/{contactId}/email

Trimite contactului propria transcriere a conversației prin e-mail — fluxul „trimite-mi acest chat prin e-mail”, gestionat din propriul sistem.

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

Răspuns (200 OK):

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

omittedCount vă spune câte dintre cele mai vechi mesaje au fost omise pentru a menține e-mailul la o lungime rezonabilă. Un 200 înseamnă că transcrierea a fost creată și pusă în coada de așteptare pentru trimitere, nu că a ajuns deja în căsuța poștală.

Suspendarea sau reluarea AI-ului pentru un contact #

PUT /contacts/{contactId}

Setați is_bot_active la false pentru a opri AI-ul din a răspunde unui contact și înapoi la true pentru a preda conversația. Acesta este comutatorul de preluare pe care îl doriți atunci când un operator uman intervine într-o conversație: mesajele trimise prin API sunt livrate în continuare în timp ce botul este suspendat.

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

Răspuns

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

Suspendarea ca parte a răspunsului

Dacă un operator uman preia conversația trimițând un răspuns, puteți suspenda botul în aceeași cerere, în loc să efectuați un al doilea apel. POST /contacts/{contactId}/send-message acceptă două opțiuni opționale:

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

Răspunsul include "botPaused": true atunci când suspendarea a fost aplicată.

Marcarea unui contact ca privat cu POST /contacts/bulk-flag suspendă, de asemenea, botul pentru acesta. Consultați Contacte pentru lista completă a câmpurilor.

Construirea propriei căsuțe de primire #

Tot ce are nevoie o căsuță de primire se află pe această pagină și în Contacte:

Pentru actualizări în timp real, abonați-vă la evenimentele New Message, Replies, Human Alerted și Chat Concluded folosind Webhooks în loc să interogați acest API la un anumit interval de timp.

Erori API mesaje #

Endpoint-urile de mesaje returnează plicul de eroare standard:

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

Codurile partajate pe care orice endpoint le poate returna — 401, 403 (planul dvs. nu include acces API), 429 (limită de rată) și 500 — sunt listate cu îndrumări pentru reîncercare în Erori și Paginare.

Pașii următori #

• Webhooks — primiți actualizări privind starea livrării în loc să interogați.
• Contacte — creați și căutați contactele cărora le trimiteți mesaje.
• Programări — rezervați și gestionați programările pentru contactele dvs.