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.

Ambele găsesc doar contacte care există deja. Niciun apel nu creează unul: un ID sau o identitate care nu se potrivește cu nimic este returnat ca 404, acesta nu devine un contact nou. Așadar, dacă trimiți un mesaj cuiva pentru prima dată, fie creează contactul mai întâi cu POST /contacts, fie, pe WhatsApp Web, folosește Trimite direct la un număr WhatsApp Web de mai jos, care creează contactul în același apel.

Trimitere prin ID-ul contactului #

POST /contacts/{contactId}/send-message

Pe LinkedIn, un mesaj trimis în acest mod sau din căsuța de primire este livrat chiar și atunci când o persoană gestionează conversația pe platforma LinkedIn. Răspunsurile proprii ale AI-ului și mesajele sale ulterioare sunt reținute în cadrul unei astfel de conversații. Un răspuns reținut este eliminat din chat în loc să fie afișat ca eșuat, deoarece nu a fost trimis nimic și nu a fost utilizat niciun credit. Ultimul răspuns al AI-ului înainte de a preda conversația unei persoane este totuși livrat.

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.

Trimiterea pe WhatsApp Web: variații și protecția împotriva trimiterilor în masă #

Două aspecte se aplică pentru body atunci când contactul folosește WhatsApp Web.

Parantezele Spintax sunt extinse la fiecare trimitere. Un body de tipul {Hi|Hello|Hey} there, quick question este trimis ca unul dintre cele trei saluturi, ales pentru acea trimitere — parantezele nu ajung niciodată la contact. Folosește-le pentru a oferi fiecărui contact un mesaj de deschidere diferit din același cod de integrare. Textul fără paranteze este trimis exact așa cum a fost scris.

Trimiterile în masă de mesaje de deschidere identice sunt refuzate. Dacă zece mesaje de deschidere aproape identice sunt trimise de la un singur număr WhatsApp Web într-o oră, către contacte care nu ți-au scris niciodată, următoarele nu vor fi livrate: trimiterea este acceptată ca de obicei (primești în continuare un messageId), iar mesajul rămâne cu status: "failed" și error_code: "opener_burst", având un motiv lizibil pentru client atașat. Reîncercarea aceluiași text nu ajută — variază textul, așteaptă o oră și trimite din nou. Răspunsurile din cadrul conversațiilor existente nu sunt niciodată afectate. Raționamentul se află în Mesajele de deschidere identice duc la restricționarea numerelor.

Trimite direct la un număr WhatsApp Web #

POST /whatsapp-web/send

Trimite la un număr de telefon pe WhatsApp Web fără a căuta mai întâi un contact. Dacă numărul nu este încă un contact, acesta este creat în același apel, cu AI-ul dezactivat pentru el, astfel încât mesajul să apară ca unul trimis manual și niciun asistent să nu preia conversația ulterior. Un contact existent este refolosit așa cum este.

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

Un apel reușit răspunde cu 202:

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

202 înseamnă acceptat, nu livrat încă. În afara orelor active, trimiterea este reținută și se efectuează în următorul interval permis, cu excepția cazului în care ai transmis ignoreActiveHours. Verifică starea mesajului cu Listează mesajele unui contact folosind contactId pe care l-ai primit aici.

Când nu se finalizează:

Un al doilea apel pentru același contact în timp ce o trimitere reținută este încă în așteptare răspunde cu 409, astfel încât o coadă nu se acumulează niciodată pentru o singură persoană.

Înregistrează o notă într-o conversație #

POST /contacts/notes

Adaugă un rând la conversația unui contact fără a-l trimite. Folosește-l pentru contextul pe care echipa ta și AI-ul ar trebui să îl aibă, dar pe care contactul nu ar trebui să îl primească niciodată: un rezumat al unui apel telefonic pe care agentul tău vocal tocmai l-a efectuat, o observație din CRM-ul tău sau o notă de la un coleg. Funcționează pe orice canal (WhatsApp, SMS, Instagram, Messenger, Telegram, widget-ul de chat, canale personalizate și așa mai departe).

Ce se întâmplă cu o notă:

• Apare în chat-ul din inbox ca un card galben de Notă, cu autorul dacă ai trimis unul.
• AI-ul o citește ca parte a istoricului conversației, marcată ca notă internă, astfel încât următorul său răspuns să o ia în considerare.
• Nu este trimisă niciodată contactului, nu consumă credite de mesaje și nu declanșează nimic: niciun răspuns AI, nicio automatizare, niciun webhook, nicio notificare, niciun indicator de mesaje necitite. Nu întrerupe AI-ul și nu contează ca un răspuns din partea echipei tale.

Găsește contactul în același mod ca la Trimitere după identitatea contactului: fie prin ID-ul acestuia, fie printr-un channel plus identificatorul corespunzător. O notă ajunge doar la un contact care există deja; dacă nu există nicio potrivire, este o 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"
  }'

Răspuns (201, sau 200 cu duplicate: true când external_id a fost deja înregistrat)

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

O notă apare în Listarea mesajelor unui contact cu type: "note".

Generarea unei ciorne de răspuns cu AI #

POST /contacts/{contactId}/draft-reply

Solicită agentului AI care gestionează o conversație să scrie următorul răspuns și vă returnează textul. Nu se trimite nimic. Este aceeași ciornă pe care o scrie butonul Generare răspuns din inbox: agentul își folosește configurarea, baza de cunoștințe și conversația de până acum și răspunde în limba contactului. Folosiți-l pentru a introduce un om (sau propria aplicație) între AI și contact: preluați ciorna, afișați-o pentru aprobare, apoi trimiteți-o cu Trimitere prin ID contact, modificată sau ca atare.

• Ciorna este scrisă de agentul alocat contactului. Un contact care nu are încă un agent va primi agentul care ar răspunde la următorul său mesaj.
• În timpul redactării, agentul nu rulează niciun instrument sau funcție, deci nu se efectuează nicio rezervare, etichetare, transfer sau altă acțiune.
• Nu se stochează nimic în conversație, iar contactul nu vede nimic.
• O ciornă costă aceleași credite ca un răspuns AI de la acel agent în această conversație și nimic atunci când este conectată propria cheie AI.
• Conversația trebuie să aibă cel puțin un mesaj.

Toate câmpurile de corp sunt opționale; un corp gol (sau lipsa acestuia) generează ciorna pentru următorul răspuns.

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

Răspuns (200)

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

Un 400 înseamnă că conversația nu are încă mesaje, creditele dumneavoastră s-au epuizat sau contactul nu are niciun agent sau campanie din care să se redacteze (error specifică motivul). Un 404 înseamnă că contactul nu există sau cheia unui membru al echipei este limitată la contacte pe care nu le poate vedea. Cheia sau membrul echipei are nevoie de permisiunea de a edita mesaje.

Utilizați un client AI prin MCP? Aceeași acțiune este disponibilă ca instrument generate_reply_draft.

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 #

Descarcă atașamentul unui mesaj #

POST /chat-exports/media/download-url

Îți oferă un link de descărcare proaspăt pentru fișierul atașat unui mesaj: o imagine, o notă vocală, un videoclip sau un document. Linkul este valabil timp de 1 oră. Folosește-l atunci când dorești să salvezi atașamentele în altă parte (de exemplu, pentru a arhiva CV-uri sau note vocale trimise de un contact) sau când media_url de pe un mesaj ori un webhook pentru Mesaj Nou nu se mai deschide.

Pentru a găsi mesaje cu atașamente, listează mesajele unui contact cu filter=media. id fiecărui mesaj și ID-ul contactului formează 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"]

Răspuns (200 OK):

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

Folosești un client AI prin MCP? Aceeași acțiune este disponibilă ca instrument get_chat_media_download_url.

Listarea sesiunilor de chat #

O sesiune de chat este o fereastră de conversație cu un contact. Se deschide la primul mesaj primit când nicio sesiune nu este deschisă și se închide automat la 48 de ore după ultimul mesaj primit de la contact (fiecare mesaj nou primit amână închiderea cu încă 48 de ore). Încheierea unui chat de către AI nu închide sesiunea; aceasta doar declanșează webhook-ul Chat Concluded. Sesiunile reprezintă modul în care poț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ă vizibil atunci când canalul refuză: primești o 409 și 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 explică motivul — fereastra de editare a canalului s-a închis, canalul este deconectat, mesajul are un atașament pe care canalul nu îl poate edita (media_not_editable: pe WhatsApp Web pot fi editate doar mesajele text, nu și textul de sub o fotografie, un videoclip sau un fișier) 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ă aceste 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,
    "human_reply": 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.