API de conectare a canalelor #

Acest ghid vă arată cum să conectați canalele de mesagerie la un cont folosind API-ul. Este scris pentru un dezvoltator care construiește o integrare sau un wrapper, așa că se concentrează pe cererile exacte, ordinea în care trebuie făcute și răspunsurile pe care le primiți.

Există un tipar pe care trebuie să îl înțelegeți de la început, deoarece se aplică aproape fiecărui canal de aici.

Tiparul de conectare urmată de interogare (poll) #

Majoritatea canalelor nu pot fi conectate printr-un singur apel API. Conectarea WhatsApp, Instagram sau Messenger înseamnă că titularul contului trebuie să se conecteze la propriul cont de furnizor și să aprobe accesul. Nu există o cale headless (complet automatizată) pentru acea aprobare - o persoană reală trebuie să deschidă un URL într-un browser sau să scaneze un cod QR cu telefonul.

Așadar, fluxul este întotdeauna:

1. Inițiați conexiunea cu un POST. Răspunsul vă oferă fie un URL de deschis, fie un cod QR de afișat.
2. Transmiteți acest lucru utilizatorului final - deschideți URL-ul în browserul său sau afișați codul QR pe ecran pentru ca acesta să îl scaneze.
3. Interogați endpoint-ul de stare cu GET la un interval scurt (la fiecare câteva secunde) până când starea ajunge la una de conectat.

Sarcina integrării dvs. este să conduceți acea buclă: afișați URL-ul sau codul QR, apoi interogați până la finalizare. Planificați-vă interfața în jurul interogării - un indicator de încărcare cu un mesaj de tipul „așteptăm să finalizați în browser” funcționează bine.

Instagram + Messenger (Meta) #

Instagram și Messenger sunt conectate împreună într-un singur flux, deoarece ambele rulează pe o pagină de Facebook. Titularul contului autorizează prin Facebook, dvs. preluați lista de pagini pe care le administrează și alegeți ce pagină să conectați.

Pasul 1 - Inițiază conexiunea Instagram + Messenger #

POST /channels/meta/connect

Aceasta returnează un URL de consimțământ. Nu sunt trimise credențiale în această cerere - conexiunea este autorizată în întregime în browser.

cURL

curl -X POST "https://api.youraiconnector.com/v1/channels/meta/connect?apiKey=YOUR_API_KEY"

JavaScript

const res = await fetch("https://api.youraiconnector.com/v1/channels/meta/connect", {
  method: "POST",
  headers: { "X-API-Key": "YOUR_API_KEY" },
});
const data = await res.json();
// Open data.oauth_url in the end user's browser.

Python

import requests

res = requests.post(
    "https://api.youraiconnector.com/v1/channels/meta/connect",
    headers={"X-API-Key": "YOUR_API_KEY"},
)
data = res.json()
# Open data["oauth_url"] in the end user's browser.

Răspuns

{
  "success": true,
  "oauth_url": "https://www.facebook.com/v21.0/dialog/oauth?client_id=...&state=...",
  "state_token": "opaque-one-time-token",
  "connect_url": "https://api.youraiconnector.com/v1/channels/meta/connect/page?token=eyJhbGciOi...",
  "connect_url_expires_at": 1717000000000,
  "expires_at": "2026-06-10T12:30:00.000Z"
}

Deschideți oauth_url în browserul utilizatorului final pentru ca acesta să se poată conecta la Facebook și să aprobe accesul. Încercarea de conectare expiră la expires_at (aproximativ 30 de minute) - dacă expiră, luați-o de la capăt. Tratați state_token ca pe un secret cu durată scurtă de viață și nu îl înregistrați în log-uri.

Cea mai simplă opțiune pentru Instagram + Messenger: predarea connect_url #

Răspunsul include, de asemenea, o pagină connect_url gata de utilizare: o pagină găzduită care rulează întregul flux pentru titularul contului. Aceștia o deschid, se conectează la Facebook, iar când au mai mult de o pagină, aceasta afișează lista și le permite să aleagă pe care să o conecteze - apoi raportează succesul de la sine. Oferiți acest link titularului contului în loc să deschideți singur oauth_url, să construiți un selector de pagini și să interogați starea. Linkul funcționează timp de aproximativ 30 de minute (connect_url_expires_at); dacă expiră, începeți o nouă conexiune. Pașii manuali de mai jos sunt pentru integrările care doresc să gestioneze fluxul și să redea singure selectorul de pagini.

Pasul 2 - Interogați starea până la încărcarea paginilor #

GET /channels/meta/status

După ce utilizatorul finalizează autentificarea prin Facebook, interogați acest endpoint la fiecare câteva secunde. Câmpul status parcurge acești pași:

cURL

curl "https://api.youraiconnector.com/v1/channels/meta/status" \
  -H "X-API-Key: YOUR_API_KEY"

JavaScript

const res = await fetch("https://api.youraiconnector.com/v1/channels/meta/status", {
  headers: { "X-API-Key": "YOUR_API_KEY" },
});
const data = await res.json();
// Poll until data.status === "pages_loaded".

Python

res = requests.get(
    "https://api.youraiconnector.com/v1/channels/meta/status",
    headers={"X-API-Key": "YOUR_API_KEY"},
)
data = res.json()
# Poll until data["status"] == "pages_loaded".

Răspuns (după ce paginile s-au încărcat)

{
  "success": true,
  "status": "pages_loaded",
  "pages": [
    {
      "id": "1234567890",
      "name": "My Business Page",
      "category": "Local business",
      "instagram_business_account": {
        "id": "17890000000000000",
        "username": "mybusiness"
      }
    }
  ],
  "selected_page": null
}

Pasul 3 - Listați paginile (opțional) #

Dacă preferați să preluați lista de pagini separat (de exemplu, pentru a afișa un selector), utilizați:

GET /channels/meta/pages

curl "https://api.youraiconnector.com/v1/channels/meta/pages" \
  -H "X-API-Key: YOUR_API_KEY"

Returnează același tablou pages ca și endpoint-ul de stare. (Endpoint-ul status include deja paginile, deci acest apel este doar pentru comoditate.)

Pasul 4 - Selectați pagina pentru conectare #

POST /channels/meta/select-page

Trimiteți page_id paginii alese de utilizator. Contul de Instagram conectat la acea pagină este conectat automat; aveți nevoie de obiectul instagram doar dacă doriți să suprascrieți contul de Instagram utilizat.

cURL

curl -X POST "https://api.youraiconnector.com/v1/channels/meta/select-page" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "page_id": "1234567890" }'

JavaScript

const res = await fetch("https://api.youraiconnector.com/v1/channels/meta/select-page", {
  method: "POST",
  headers: {
    "X-API-Key": "YOUR_API_KEY",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({ page_id: "1234567890" }),
});
const data = await res.json();

Python

res = requests.post(
    "https://api.youraiconnector.com/v1/channels/meta/select-page",
    headers={"X-API-Key": "YOUR_API_KEY"},
    json={"page_id": "1234567890"},
)
data = res.json()

Răspuns

{
  "success": true,
  "page_id": "1234567890",
  "instagram_business_account_id": "17890000000000000"
}

Canalul este acum conectat. Un GET /channels/meta/status ulterior va raporta status: "connected".

Listează postările paginii conectate #

GET /channels/meta/posts?platform=instagram

Returnează postările recente ale paginii pe care ați conectat-o - conținut Instagram sau postări Facebook. Acesta este elementul din care redați un selector atunci când configurați un Punct de Intrare care reacționează la comentariile de la o anumită postare.

cURL

curl "https://api.youraiconnector.com/v1/channels/meta/posts?platform=instagram&limit=25" \
  -H "X-API-Key: YOUR_API_KEY"

Răspuns

{
  "success": true,
  "connected": true,
  "platform": "instagram",
  "posts": [
    {
      "id": "17900000000000000",
      "caption": "New spring menu is live",
      "thumbnailUrl": "https://scontent.cdninstagram.com/...",
      "permalink": "https://www.instagram.com/p/Cxxxxxxxxxx/",
      "createdAt": "2026-05-02T09:12:00.000Z",
      "mediaType": "REELS"
    }
  ],
  "nextCursor": "QVFIUkxxxxxxxx"
}

mediaType este eticheta proprie Instagram (REELS, FEED, STORY sau formatul - IMAGE, VIDEO, CAROUSEL_ALBUM); pentru Facebook este întotdeauna POST. nextCursor este null pe ultima pagină.

Dacă nu poate fi listat nimic, apelul returnează totuși 200 cu connected: false și un tablou posts gol, plus un reason care vă explică motivul:

Deconectează Instagram + Messenger #

DELETE /channels/meta

curl -X DELETE "https://api.youraiconnector.com/v1/channels/meta" \
  -H "X-API-Key: YOUR_API_KEY"

Răspuns

{ "success": true, "disconnected": true }

Aceasta oprește rutarea primită atât pentru Instagram, cât și pentru Messenger. Este idempotentă - apelarea acesteia când nimic nu este conectat va reuși în continuare.

WhatsApp Business #

Aceasta conectează un număr oficial WhatsApp Business. Numărul trebuie să existe deja în cont înainte de a apela funcția de conectare. La fel ca la Meta, titularul contului autorizează în browserul său, apoi interogați până când numărul raportează ONLINE.

Pasul 1 - Inițiază conexiunea WhatsApp Business #

POST /channels/whatsapp/connect

cURL

curl -X POST "https://api.youraiconnector.com/v1/channels/whatsapp/connect?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "phone_number": "+14155551234" }'

JavaScript

const res = await fetch("https://api.youraiconnector.com/v1/channels/whatsapp/connect", {
  method: "POST",
  headers: {
    "X-API-Key": "YOUR_API_KEY",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({ phone_number: "+14155551234" }),
});
const data = await res.json();
// Open data.oauth_url in the account holder's browser.

Python

res = requests.post(
    "https://api.youraiconnector.com/v1/channels/whatsapp/connect",
    headers={"X-API-Key": "YOUR_API_KEY"},
    json={"phone_number": "+14155551234"},
)
data = res.json()
# Open data["oauth_url"] in the account holder's browser.

Răspuns

{
  "success": true,
  "status": "pending",
  "oauth_url": "https://www.facebook.com/v21.0/dialog/oauth?client_id=...&state=...",
  "state_token": "opaque-one-time-token",
  "expires_at": "2026-06-10T12:30:00.000Z"
}

Deschideți oauth_url în browserul titularului contului pentru a autoriza. Odată ce aceștia aprobă, înregistrarea se finalizează în fundal.

Pasul 2 - Interogați starea până când este ONLINE #

GET /channels/whatsapp/connect/{phoneNumber}/status

Interogați acest lucru până când status este ONLINE.

cURL

curl "https://api.youraiconnector.com/v1/channels/whatsapp/connect/+14155551234/status" \
  -H "X-API-Key: YOUR_API_KEY"

JavaScript

const phone = encodeURIComponent("+14155551234");
const res = await fetch(
  `https://api.youraiconnector.com/v1/channels/whatsapp/connect/${phone}/status`,
  { headers: { "X-API-Key": "YOUR_API_KEY" } }
);
const data = await res.json();
// Poll until data.status === "ONLINE".

Python

import urllib.parse

phone = urllib.parse.quote("+14155551234")
res = requests.get(
    f"https://api.youraiconnector.com/v1/channels/whatsapp/connect/{phone}/status",
    headers={"X-API-Key": "YOUR_API_KEY"},
)
data = res.json()
# Poll until data["status"] == "ONLINE".

Răspuns

{
  "success": true,
  "phone_number": "+14155551234",
  "channel": "whatsapp",
  "status": "ONLINE",
  "status_reason": null,
  "live": true
}

Câmpul status poate fi:

live: true înseamnă că starea a fost verificată în raport cu furnizorul în timp real; false înseamnă că provine din ultima stare stocată în cache.

Deconectează un număr WhatsApp Business #

DELETE /channels/whatsapp/{phoneNumber}

curl -X DELETE "https://api.youraiconnector.com/v1/channels/whatsapp/+14155551234" \
  -H "X-API-Key: YOUR_API_KEY"

Răspuns

{ "success": true, "phone_number": "+14155551234", "disconnected": true }

Numărul în sine rămâne în cont, astfel încât să îl puteți reconecta ulterior.

WhatsApp Web #

WhatsApp Web conectează un număr obișnuit de WhatsApp prin scanarea unui cod QR, exact ca la conectarea unui dispozitiv în aplicația WhatsApp. Fluxul este: pornește sesiunea, preia codul QR și afișează-l, apoi interoghează starea până când aceasta este connected.

Pasul 1 - Inițiază o sesiune de asociere WhatsApp Web #

POST /channels/whatsapp-web/connections

cURL

curl -X POST "https://api.youraiconnector.com/v1/channels/whatsapp-web/connections?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "phone_number": "+15551230000" }'

JavaScript

const res = await fetch("https://api.youraiconnector.com/v1/channels/whatsapp-web/connections", {
  method: "POST",
  headers: {
    "X-API-Key": "YOUR_API_KEY",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({ phone_number: "+15551230000" }),
});
const data = await res.json();

Python

res = requests.post(
    "https://api.youraiconnector.com/v1/channels/whatsapp-web/connections",
    headers={"X-API-Key": "YOUR_API_KEY"},
    json={"phone_number": "+15551230000"},
)
data = res.json()

Răspuns

{
  "success": true,
  "phone_number": "+15551230000",
  "session_id": "session-id",
  "status": "qr_pending",
  "connect_url": "https://api.youraiconnector.com/v1/channels/whatsapp-web/connect?token=eyJhbGciOi...",
  "connect_url_expires_at": 1717000000000,
  "poll_qr_path": "/v1/channels/whatsapp-web/connections/%2B15551230000/qr",
  "poll_status_path": "/v1/channels/whatsapp-web/connections/%2B15551230000/status"
}

Cea mai simplă opțiune pentru WhatsApp Web: predarea connect_url #

Răspunsul include un connect_url gata de utilizare: o pagină găzduită care afișează codul QR, îl reîmprospătează automat pe măsură ce se rotește și trece la un mesaj de succes în momentul în care numărul este conectat. Pur și simplu oferiți acest link titularului contului (deschideți-l într-un browser, trimiteți-l acestuia sau afișați-l ca un cod QR/buton) și rugați-l să îl scaneze cu WhatsApp - nu trebuie să preluați codul QR sau să interogați nimic pe cont propriu. Linkul funcționează timp de aproximativ 30 de minute (connect_url_expires_at); dacă expiră înainte ca aceștia să termine, începeți o nouă conexiune pentru a obține unul nou.

Aceasta este calea recomandată atunci când o persoană poate deschide un link. Pașii manuali de mai jos (preluarea codului QR de către dvs., interogarea stării) sunt destinați integrărilor care doresc să redea codul QR în propria interfață.

Răspunsul vă oferă, de asemenea, poll_qr_path și poll_status_path exacte pe care să le utilizați, astfel încât să nu fie nevoie să le construiți singur.

Pasul 2 - Preluarea și afișarea codului QR #

GET /channels/whatsapp-web/connections/{phoneNumber}/qr

cURL

curl "https://api.youraiconnector.com/v1/channels/whatsapp-web/connections/+15551230000/qr" \
  -H "X-API-Key: YOUR_API_KEY"

JavaScript

const phone = encodeURIComponent("+15551230000");
const res = await fetch(
  `https://api.youraiconnector.com/v1/channels/whatsapp-web/connections/${phone}/qr`,
  { headers: { "X-API-Key": "YOUR_API_KEY" } }
);
const data = await res.json();
// Render data.qr_data_url as an <img src> for the user to scan.

Python

import urllib.parse

phone = urllib.parse.quote("+15551230000")
res = requests.get(
    f"https://api.youraiconnector.com/v1/channels/whatsapp-web/connections/{phone}/qr",
    headers={"X-API-Key": "YOUR_API_KEY"},
)
data = res.json()
# Render data["qr_data_url"] for the user to scan.

Răspuns

{
  "success": true,
  "phone_number": "+15551230000",
  "status": "qr_pending",
  "qr_code": "2@raw-qr-payload-string...",
  "qr_data_url": "data:image/png;base64,iVBORw0KGgo...",
  "expires_at": "2026-06-10T12:05:00.000Z"
}

Redă codul QR pentru ca utilizatorul să îl scaneze cu telefonul (WhatsApp > Dispozitive conectate > Conectează un dispozitiv):

• qr_data_url este o imagine gata de utilizare - insereaz-o direct într-un <img src>.
• qr_code este sarcina utilă brută (raw payload) dacă preferi să generezi singur imaginea.

Codul QR are o durată de viață scurtă. Dacă apelezi acest lucru imediat după pornirea sesiunii, este posibil să primești un 404 cu mesajul “QR code not available yet” - așteaptă puțin și reîncearcă. Dacă primești un 410 (“QR code expired”), reia conexiunea de la început pentru a obține un cod nou.

Pasul 3 - Interogarea stării până la conectare #

GET /channels/whatsapp-web/connections/{phoneNumber}/status

cURL

curl "https://api.youraiconnector.com/v1/channels/whatsapp-web/connections/+15551230000/status" \
  -H "X-API-Key: YOUR_API_KEY"

JavaScript

const phone = encodeURIComponent("+15551230000");
const res = await fetch(
  `https://api.youraiconnector.com/v1/channels/whatsapp-web/connections/${phone}/status`,
  { headers: { "X-API-Key": "YOUR_API_KEY" } }
);
const data = await res.json();
// Poll until data.status === "connected" (or "open").

Python

import urllib.parse

phone = urllib.parse.quote("+15551230000")
res = requests.get(
    f"https://api.youraiconnector.com/v1/channels/whatsapp-web/connections/{phone}/status",
    headers={"X-API-Key": "YOUR_API_KEY"},
)
data = res.json()
# Poll until data["status"] == "connected" (or "open").

Răspuns

{
  "success": true,
  "phone_number": "+15551230000",
  "status": "connected",
  "has_qr": false,
  "qr_expires_at": null,
  "last_activity": null,
  "message_count": null,
  "proxy": null,
  "live": true
}

Deconectează o sesiune WhatsApp Web #

DELETE /channels/whatsapp-web/connections/{phoneNumber}

curl -X DELETE "https://api.youraiconnector.com/v1/channels/whatsapp-web/connections/+15551230000" \
  -H "X-API-Key: YOUR_API_KEY"

Răspuns

{ "success": true, "phone_number": "+15551230000", "status": "removed" }

Aceasta deconectează dispozitivul și elimină conexiunea. Curăță întotdeauna starea locală, deci este idempotentă chiar dacă sesiunea subiacentă a fost deja eliminată.

Telegram #

Disponibilitate: Telegram se conectează la fel ca orice alt canal și este deschis pentru fiecare cont — nu este necesar să fie activat pentru tine. Punctele finale Telegram de mai jos pot returna în continuare 403 dacă Telegram nu este inclus în planul contului, caz în care eroarea va fi "This channel is not included in your current plan. Upgrade to unlock it.".

Telegram conectează un cont personal prin număr de telefon plus un cod de autentificare unic (și o parolă cu doi factori, dacă contul are una setată). Fluxul este: porniți sesiunea, trimiteți codul, trimiteți opțional parola, apoi confirmați prin stare.

Pasul 1 - Inițiază o sesiune de conexiune Telegram #

POST /channels/telegram/connect

cURL

curl -X POST "https://api.youraiconnector.com/v1/channels/telegram/connect?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "phone_number": "+14155550100" }'

JavaScript

const res = await fetch("https://api.youraiconnector.com/v1/channels/telegram/connect", {
  method: "POST",
  headers: {
    "X-API-Key": "YOUR_API_KEY",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({ phone_number: "+14155550100" }),
});
const data = await res.json();

Python

res = requests.post(
    "https://api.youraiconnector.com/v1/channels/telegram/connect",
    headers={"X-API-Key": "YOUR_API_KEY"},
    json={"phone_number": "+14155550100"},
)
data = res.json()

Răspuns

{
  "success": true,
  "phone_number": "+14155550100",
  "status": "code_required",
  "session_id": "session-id",
  "connect_url": "https://api.youraiconnector.com/v1/channels/telegram/connect/page?token=eyJhbGciOi...",
  "connect_url_expires_at": 1717000000000
}

În modul code, contul primește un cod de autentificare în Telegram, iar status este code_required. (În modul qr, răspunsul include, de asemenea, login_token și qr_url pentru afișare în vederea scanării, iar status este qr_required.)

Cea mai simplă opțiune pentru Telegram: predarea connect_url #

Răspunsul include un connect_url gata de utilizare: o pagină găzduită care finalizează conexiunea de la sine. În modul code, titularul contului introduce codul de autentificare - și o parolă de verificare în doi pași, dacă contul are una. În modul qr, pagina afișează un cod QR care se actualizează automat pentru a fi scanat din aplicația Telegram. În ambele cazuri, pagina raportează succesul automat, așa că puteți pur și simplu să oferiți acest link titularului contului în loc să vă construiți propria interfață și să interogați starea. Linkul este valabil aproximativ 30 de minute (connect_url_expires_at); dacă expiră, începeți o conexiune nouă pentru a obține unul proaspăt.

Pașii manuali de mai jos (colectarea codului de către dvs., trimiterea acestuia, interogarea stării; sau randarea qr_url și interogarea) sunt destinați integrărilor care doresc să își randeze singure interfața.

Pasul 2 - Trimiterea codului de autentificare #

POST /channels/telegram/connect/{phoneNumber}/verify-code

cURL

curl -X POST "https://api.youraiconnector.com/v1/channels/telegram/connect/+14155550100/verify-code" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "code": "12345" }'

JavaScript

const phone = encodeURIComponent("+14155550100");
const res = await fetch(
  `https://api.youraiconnector.com/v1/channels/telegram/connect/${phone}/verify-code`,
  {
    method: "POST",
    headers: {
      "X-API-Key": "YOUR_API_KEY",
      "Content-Type": "application/json",
    },
    body: JSON.stringify({ code: "12345" }),
  }
);
const data = await res.json();

Python

import urllib.parse

phone = urllib.parse.quote("+14155550100")
res = requests.post(
    f"https://api.youraiconnector.com/v1/channels/telegram/connect/{phone}/verify-code",
    headers={"X-API-Key": "YOUR_API_KEY"},
    json={"code": "12345"},
)
data = res.json()

Răspuns

{
  "success": true,
  "phone_number": "+14155550100",
  "status": "connected",
  "telegram_user_id": "100000001",
  "username": "myhandle"
}

Dacă status este connected, ați terminat. Dacă contul are activată autentificarea cu doi factori, status va fi password_required - treceți la pasul 3.

Pasul 3 - Trimiterea parolei cu doi factori (doar dacă este necesar) #

POST /channels/telegram/connect/{phoneNumber}/verify-password

Apelați acest pas doar când pasul 2 a returnat password_required.

cURL

curl -X POST "https://api.youraiconnector.com/v1/channels/telegram/connect/+14155550100/verify-password" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "password": "the-2fa-password" }'

JavaScript

const phone = encodeURIComponent("+14155550100");
const res = await fetch(
  `https://api.youraiconnector.com/v1/channels/telegram/connect/${phone}/verify-password`,
  {
    method: "POST",
    headers: {
      "X-API-Key": "YOUR_API_KEY",
      "Content-Type": "application/json",
    },
    body: JSON.stringify({ password: "the-2fa-password" }),
  }
);
const data = await res.json();

Python

import urllib.parse

phone = urllib.parse.quote("+14155550100")
res = requests.post(
    f"https://api.youraiconnector.com/v1/channels/telegram/connect/{phone}/verify-password",
    headers={"X-API-Key": "YOUR_API_KEY"},
    json={"password": "the-2fa-password"},
)
data = res.json()

Răspuns

{
  "success": true,
  "phone_number": "+14155550100",
  "status": "connected",
  "telegram_user_id": "100000001",
  "username": "myhandle"
}

Verifică starea Telegram #

GET /channels/telegram/connect/{phoneNumber}/status

curl "https://api.youraiconnector.com/v1/channels/telegram/connect/+14155550100/status" \
  -H "X-API-Key: YOUR_API_KEY"

Răspuns

{
  "success": true,
  "phone_number": "+14155550100",
  "status": "connected",
  "telegram_user_id": "100000001",
  "live": true
}

status poate fi connected, code_required, password_required, initializing, disconnected, not_initialized sau error.

Deconectează Telegram #

DELETE /channels/telegram/{phoneNumber}

curl -X DELETE "https://api.youraiconnector.com/v1/channels/telegram/+14155550100" \
  -H "X-API-Key: YOUR_API_KEY"

Răspuns

{ "success": true, "phone_number": "+14155550100", "status": "removed" }

Idempotent - apelurile repetate reușesc.

Instagram (cont personal) #

Versiune beta cu disponibilitate limitată, activată per cont. Aceasta conectează un cont personal de Instagram prin autentificarea cu nume de utilizator și parolă (nu prin API-ul oficial Business). Dacă contul nu este activat pentru versiunea beta, apelul de conectare returnează o eroare de permisiune.

Deoarece acest lucru necesită propria autentificare Instagram a titularului contului, cea mai simplă cale este să le oferiți pagina găzduită connect_url și să îi lăsați să își introducă credențialele acolo - integrarea dvs. nu gestionează niciodată parola.

Pasul 1 - Inițiază o conexiune Instagram (personal) #

POST /channels/instagram-private/connect

Trimiteți username și password pentru Instagram.

Răspuns

{
  "success": true,
  "status": "connected",
  "connect_url": "https://api.youraiconnector.com/v1/channels/instagram-private/connect/page?token=eyJhbGciOi...",
  "connect_url_expires_at": 1717000000000
}

Dacă contul are autentificare cu doi factori sau Instagram prezintă un punct de verificare, status revine ca two_factor_required sau challenge_required - trimiteți codul către /connect/{id}/verify-2fa sau /connect/{id}/verify-challenge de mai jos, apoi interogați /connect/{id}/status până când connected. {id} este numele de utilizator Instagram normalizat returnat ca account_id/username în răspunsul de mai sus - utilizați-l la fiecare pas de mai jos.

Pasul 2 - Trimiteți codul de autentificare cu doi factori (dacă este solicitat) #

POST /channels/instagram-private/connect/{id}/verify-2fa

Apelați acest lucru doar atunci când pasul 1 (sau pasul 3) a returnat two_factor_required.

curl -X POST "https://api.youraiconnector.com/v1/channels/instagram-private/connect/yourbrand/verify-2fa" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "code": "123456" }'

Răspuns

{
  "success": true,
  "account_id": "yourbrand",
  "status": "connected",
  "ig_user_id": "17890000000000000",
  "username": "yourbrand"
}

status poate reveni ca connected (finalizat), two_factor_required (cod greșit, încercați din nou) sau challenge_required (Instagram solicită și un cod de verificare - mergeți la pasul 3).

Pasul 3 - Trimiteți codul de confirmare a punctului de verificare (dacă este solicitat) #

POST /channels/instagram-private/connect/{id}/verify-challenge

Apelați acest lucru doar atunci când un pas anterior a returnat challenge_required. Aceeași formă de cerere și răspuns ca la pasul 2 de mai sus.

curl -X POST "https://api.youraiconnector.com/v1/channels/instagram-private/connect/yourbrand/verify-challenge" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "code": "123456" }'

Verificați starea Instagram (personal) #

GET /channels/instagram-private/connect/{id}/status

Interogați acest lucru până când status este connected sau până când raportează o eroare terminală.

curl "https://api.youraiconnector.com/v1/channels/instagram-private/connect/yourbrand/status" \
  -H "X-API-Key: YOUR_API_KEY"

Răspuns

{
  "success": true,
  "account_id": "yourbrand",
  "status": "connected",
  "ig_user_id": "17890000000000000",
  "username": "yourbrand",
  "live": true
}

status poate fi connected, two_factor_required, challenge_required, initializing, disconnected, not_initialized sau error. live: true înseamnă că aceasta a fost citită în direct de la worker-ul de conexiune, în loc de o valoare memorată în cache.

Cea mai simplă opțiune pentru Instagram (personal): predarea connect_url #

Răspunsul include un connect_url: o pagină găzduită unde titularul contului își introduce numele de utilizator și parola de Instagram (precum și un cod 2FA sau de verificare dacă Instagram solicită unul), care raportează succesul de la sine. Credențialele merg direct la Instagram și nu sunt stocate. Oferiți acest link titularului contului în loc să colectați parola acestuia în propria interfață. Linkul funcționează timp de aproximativ 30 de minute (connect_url_expires_at).

Deconectare Instagram (personal) #

DELETE /channels/instagram-private/{id}

Idempotent - apelurile repetate reușesc.

Sincronizarea urmăritorilor #

POST /channels/instagram-private/{id}/sync-followers

Declanșează manual o sincronizare a urmăritorilor pentru un cont conectat - aceeași sarcină care rulează automat în fundal, expusă aici pentru o acțiune de tip „Reîmprospătare urmăritori” la cerere. Aceasta preia lista actuală de urmăritori a contului, înregistrează persoanele noi și (atunci când o campanie Live are activată funcția de contactare a urmăritorilor) trimite noilor urmăritori un mesaj direct de întâmpinare, până la o limită zilnică.

curl -X POST "https://api.youraiconnector.com/v1/channels/instagram-private/yourbrand/sync-followers" \
  -H "X-API-Key: YOUR_API_KEY"

Răspuns

{
  "success": true,
  "accountId": "yourbrand",
  "totalFollowers": 1204,
  "newFollowers": 6,
  "dmsSent": 6,
  "isBaselineSeed": false
}

Aceste cinci câmpuri sunt singurul loc de pe această pagină care returnează camelCase în loc de snake_case - așa este configurat acest endpoint în prezent, nu este o greșeală de tipar. isBaselineSeed: true înseamnă că aceasta a fost prima sincronizare după conectare, care doar înregistrează lista inițială de urmăritori și nu trimite niciodată mesaje directe de contactare (deci dmsSent este întotdeauna 0 la acea rulare).

Prima apelare pentru un cont poate dura ceva timp (parcurgerea întregii liste de urmăritori); apelările ulterioare sunt mai rapide, deoarece sunt procesate doar diferențele pentru noii urmăritori. 404 înseamnă că contul nu este conectat; 412 înseamnă că inițializarea conexiunii nu s-a finalizat încă - așteptați și reîncercați.

LINE #

LINE este cel mai simplu canal de conectat deoarece nu există nicio redirecționare prin browser sau interogare (polling). Clientul creează un canal Messaging API în consola LINE Developers, copiază două valori, iar tu le trimiți într-un singur apel. Apoi le oferi înapoi un URL de webhook pe care să îl lipească în consolă.

Pasul 1 - Conectarea cu credențialele canalului #

POST /channels/line

cURL

curl -X POST "https://api.youraiconnector.com/v1/channels/line?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "channel_access_token": "LONG_LIVED_CHANNEL_ACCESS_TOKEN",
    "channel_secret": "CHANNEL_SECRET"
  }'

JavaScript

const res = await fetch("https://api.youraiconnector.com/v1/channels/line", {
  method: "POST",
  headers: {
    "X-API-Key": "YOUR_API_KEY",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    channel_access_token: "LONG_LIVED_CHANNEL_ACCESS_TOKEN",
    channel_secret: "CHANNEL_SECRET",
  }),
});
const data = await res.json();

Python

res = requests.post(
    "https://api.youraiconnector.com/v1/channels/line",
    headers={"X-API-Key": "YOUR_API_KEY"},
    json={
        "channel_access_token": "LONG_LIVED_CHANNEL_ACCESS_TOKEN",
        "channel_secret": "CHANNEL_SECRET",
    },
)
data = res.json()

Răspuns

{
  "success": true,
  "status": "connected",
  "bot_user_id": "Uxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
  "basic_id": "@mybusiness",
  "display_name": "My Business",
  "picture_url": "https://...",
  "chat_mode": "bot",
  "chat_mode_ok": true,
  "webhook_url": "https://api.youraiconnector.com/line/webhook/..."
}

Două câmpuri contează pentru ceea ce faci în continuare:

• webhook_url - clientul trebuie să lipească acest lucru în câmpul Webhook URL al canalului său LINE din consola LINE Developers (și să activeze “Use webhook”). Până când nu fac acest lucru, nu vor sosi mesaje primite. Arată-le acest lucru în mod vizibil.
• chat_mode_ok - când false, Contul Oficial este în modul “chat” și nu va primi sau trimite mesaje până când nu este comutat în modul “bot” în LINE Official Account Manager. Condiționează procesul de onboarding de acest indicator și spune-i clientului să schimbe modul.

channel_access_token și channel_secret nu sunt returnate niciodată de niciun endpoint. Stochează-le de partea ta dacă ai nevoie de ele din nou; în caz contrar, lipește-le din nou din consola LINE.

bot_user_id returnat aici este identificatorul de conexiune pe care îl folosești în apelurile de stare, verificare și deconectare de mai jos.

Pasul 2 - Reverificarea după configurarea webhook-ului #

POST /channels/line/{botUserId}/verify-webhook

După ce clientul termină configurarea URL-ului webhook și trece la modul bot, apelați această funcție pentru a revalida tokenul stocat și a reîmprospăta modul de chat stocat în cache.

curl -X POST "https://api.youraiconnector.com/v1/channels/line/Uxxxxxxxx.../verify-webhook" \
  -H "X-API-Key: YOUR_API_KEY"

Răspuns

{
  "success": true,
  "token_valid": true,
  "chat_mode": "bot",
  "chat_mode_ok": true,
  "webhook_url": "https://api.youraiconnector.com/line/webhook/..."
}

Dacă token_valid este false, tokenul de acces stocat nu mai autentifică - solicitați clientului să îl emită din nou în consolă și apelați POST /channels/line din nou cu noul token.

Verificarea stării LINE #

GET /channels/line/{botUserId}/status

curl "https://api.youraiconnector.com/v1/channels/line/Uxxxxxxxx.../status" \
  -H "X-API-Key: YOUR_API_KEY"

Răspuns

{
  "success": true,
  "bot_user_id": "Uxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
  "channel": "line",
  "status": "connected",
  "basic_id": "@mybusiness",
  "display_name": "My Business",
  "picture_url": "https://...",
  "chat_mode": "bot",
  "is_active": true,
  "live": false
}

LINE nu are un flux de stare live, deci live este întotdeauna false aici - valorile reflectă starea capturată la momentul conectării (sau al ultimei verificări).

Deconectare LINE #

DELETE /channels/line/{botUserId}

curl -X DELETE "https://api.youraiconnector.com/v1/channels/line/Uxxxxxxxx..." \
  -H "X-API-Key: YOUR_API_KEY"

Răspuns

{ "success": true, "status": "removed", "bot_user_id": "Uxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" }

Viber #

Viber se conectează în același mod ca LINE - lipiți tokenul de autentificare al botului din Panoul de Administrare Viber într-un singur apel - cu o diferență importantă: conectarea ÎNREGISTREAZĂ totodată webhook-ul nostru pe botul dvs. în acel moment, deci nu există un pas separat în consolă ulterior. Acest lucru înseamnă, de asemenea, că o încercare de conectare poate eșua dacă sistemul nostru de intrare nu poate răspunde la verificarea sincronă a webhook-ului Viber, nu doar dacă tokenul în sine este incorect.

Pasul 1 - Conectați-vă cu tokenul de autentificare al botului #

POST /channels/viber

curl -X POST "https://api.youraiconnector.com/v1/channels/viber?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "auth_token": "444d5555e6666f7777a8888b9999c000" }'

Răspuns

{
  "success": true,
  "status": "connected",
  "bot_id": "botIdFromViber",
  "bot_name": "My Business Bot",
  "bot_avatar": "https://...",
  "bot_uri": "mybusinessbot",
  "subscribers_count": 0,
  "webhook_url": "https://api.youraiconnector.com/v1/incoming-viber-message/...",
  "event_types": ["delivered", "seen", "failed", "subscribed", "unsubscribed", "conversation_started"]
}

Tokenul de autentificare nu este niciodată returnat de niciun endpoint - stocați-l în partea dvs. dacă va trebui să îl lipiți din nou. bot_id este identificatorul de conexiune utilizat de apelurile de stare, verificare și deconectare de mai jos.

Verificarea stării Viber #

GET /channels/viber/{botId}/status

Raportează starea conexiunii stocate. Adăugați ?live=true pentru a verifica din nou botul față de Viber și a reîmprospăta înregistrarea webhook-ului stocată în cache - util înainte de a presupune că un bot silențios este într-adevăr defect.

curl "https://api.youraiconnector.com/v1/channels/viber/botIdFromViber/status?live=true" \
  -H "X-API-Key: YOUR_API_KEY"

Răspuns

{
  "success": true,
  "bot_id": "botIdFromViber",
  "channel": "viber",
  "status": "connected",
  "bot_name": "My Business Bot",
  "bot_avatar": "https://...",
  "bot_uri": "mybusinessbot",
  "webhook_url": "https://api.youraiconnector.com/v1/incoming-viber-message/...",
  "registered_webhook": "https://api.youraiconnector.com/v1/incoming-viber-message/...",
  "webhook_ok": true,
  "subscribers_count": 128,
  "is_active": true,
  "live": true
}

webhook_ok: false înseamnă că webhook-ul botului nu mai indică spre noi - mesajele primite sunt pierdute. Acest lucru înseamnă de obicei că un alt instrument a conectat același bot ulterior (înregistrarea webhook-ului Viber funcționează pe principiul „ultima scriere câștigă”). Remediați problema cu apelul de reverificare de mai jos, fără a fi nevoie să cereți clientului să lipească din nou tokenul. live este false atunci când răspunsul este ultima stare stocată în cache, în loc de o verificare proaspătă față de Viber.

Reînregistrarea webhook-ului #

POST /channels/viber/{botId}/verify-webhook

Acțiunea de reparare pentru webhook_ok: false - reînregistrează webhook-ul nostru pe bot folosind tokenul de autentificare deja stocat.

curl -X POST "https://api.youraiconnector.com/v1/channels/viber/botIdFromViber/verify-webhook" \
  -H "X-API-Key: YOUR_API_KEY"

Răspuns

{ "success": true, "token_valid": true, "webhook_ok": true, "webhook_url": "https://api.youraiconnector.com/v1/incoming-viber-message/...", "event_types": ["delivered", "seen", "failed", "subscribed", "unsubscribed", "conversation_started"] }

token_valid: false înseamnă că tokenul stocat nu mai funcționează - reconectați-vă cu POST /channels/viber și un token nou.

Deconectare Viber #

DELETE /channels/viber/{botId}

Anulează înregistrarea webhook-ului nostru de partea Viber (best-effort) și elimină conexiunea.

curl -X DELETE "https://api.youraiconnector.com/v1/channels/viber/botIdFromViber" \
  -H "X-API-Key: YOUR_API_KEY"

Răspuns

{ "success": true, "status": "removed", "bot_id": "botIdFromViber", "webhook_removed": true }

TikTok #

Disponibilitate: Versiune beta cu disponibilitate limitată, activată per cont. Conectarea TikTok returnează o eroare de permisiune până când contul este activat pentru aceasta.

TikTok Business Messaging este un canal OAuth complet, similar cu Meta, dar mai simplu în ceea ce privește interogarea (polling): nu există un pas dedicat de interogare a stării pentru implementare, deoarece contul conectat apare de la sine odată ce TikTok redirecționează înapoi și conexiunea este scrisă. Endpoint-ul de stare de mai jos există pentru confirmarea stării la cerere (instrumente de asistență, verificări de sănătate), nu ca ceva pe care trebuie să îl rulați în buclă în timpul conectării.

Pasul 1 - Inițierea conexiunii TikTok #

POST /channels/tiktok/connect

Nu necesită credențiale - titularul contului autorizează totul direct în browserul său.

curl -X POST "https://api.youraiconnector.com/v1/channels/tiktok/connect?apiKey=YOUR_API_KEY"

Răspuns

{
  "success": true,
  "status": "pending_authorization",
  "oauth_url": "https://www.tiktok.com/v2/auth/authorize?client_key=...&state=...",
  "state_token": "opaque-one-time-token",
  "expires_at": "2026-06-10T12:30:00.000Z"
}

Deschideți oauth_url în browserul titularului contului pentru ca acesta să se poată autentifica în TikTok și să aprobe accesul. Starea expiră la expires_at (aproximativ 30 de minute) - dacă expiră, luați-o de la capăt. Nu există nicio scurtătură connect_url pentru pagina găzduită pentru TikTok; deschiderea oauth_url pe cont propriu este singura cale.

Verificarea stării TikTok #

GET /channels/tiktok/{openId}/status

openId este open_id-ul contului TikTok Business, cunoscut odată ce callback-ul OAuth a fost executat.

curl "https://api.youraiconnector.com/v1/channels/tiktok/openIdFromTikTok/status" \
  -H "X-API-Key: YOUR_API_KEY"

Răspuns

{
  "success": true,
  "open_id": "openIdFromTikTok",
  "channel": "tiktok",
  "status": "connected",
  "business_id": "openIdFromTikTok",
  "username": "mybusiness",
  "display_name": "My Business",
  "avatar_url": "https://...",
  "status_reason": null,
  "is_active": true,
  "live": false
}

TikTok nu are o verificare de sănătate live ieftină, așa că live este întotdeauna false aici - câmpurile reflectă ceea ce a scris conexiunea (sau ultima reîmprospătare a token-ului). status: "reauth_required" cu status_reason setat înseamnă că contul trebuie să treacă din nou prin procesul de conectare; token-urile TikTok sunt reîmprospătate automat printr-o rotație anuală, iar aceasta este ceea ce apare dacă acea rotație eșuează vreodată.

Deconectare TikTok #

DELETE /channels/tiktok/{openId}

curl -X DELETE "https://api.youraiconnector.com/v1/channels/tiktok/openIdFromTikTok" \
  -H "X-API-Key: YOUR_API_KEY"

Răspuns

{ "success": true, "status": "removed", "open_id": "openIdFromTikTok" }

GoHighLevel #

GoHighLevel (GHL) este o integrare CRM, nu un canal de mesagerie - conectarea acestuia nu consumă un slot de canal din plan, deoarece utilizează canalele existente ale contului în loc să adauge unul nou. Este, de asemenea, singura integrare de pe această pagină care poate menține mai mult de o conexiune simultan: fiecare sub-cont GHL (“locație”) pe care clientul instalează aplicația primește propria intrare.

Pasul 1 - Inițierea conexiunii GHL #

POST /channels/ghl/connect

curl -X POST "https://api.youraiconnector.com/v1/channels/ghl/connect?apiKey=YOUR_API_KEY"

Răspuns

{
  "success": true,
  "status": "pending_authorization",
  "oauth_url": "https://marketplace.gohighlevel.com/oauth/chooselocation?client_id=...&state=...",
  "state_token": "opaque-one-time-token",
  "brand": "dmchamp",
  "expires_at": "2026-06-10T12:30:00.000Z"
}

Deschideți oauth_url în browserul titularului de cont pentru ca acesta să poată alege o locație GHL și să aprobe accesul. Starea expiră la expires_at (aproximativ 30 de minute).

Listarea conexiunilor GHL #

GET /channels/ghl/status

Spre deosebire de alte canale, aceasta nu reprezintă starea unei singure conexiuni - ci listează fiecare locație pe care contul a conectat-o.

curl "https://api.youraiconnector.com/v1/channels/ghl/status" \
  -H "X-API-Key: YOUR_API_KEY"

Răspuns

{
  "success": true,
  "connections": [
    {
      "location_id": "abc123location",
      "company_id": "xyz789company",
      "brand": "dmchamp",
      "status": "connected",
      "status_reason": null,
      "scopes": ["conversations.readonly", "conversations.write", "conversations/message.write"],
      "connected_at": "2026-06-01T10:00:00.000Z",
      "conversation_provider_id": "provider-id-in-ghl",
      "trigger_subscriptions": [
        { "id": "sub_1", "key": "InboundMessage", "workflow_id": "wf_123" }
      ]
    }
  ]
}

Deconectarea unei locații GHL #

DELETE /channels/ghl/{locationId}

Șterge conexiunea de aici, ceea ce oprește orice sincronizare și declanșator pentru acea locație. Această acțiune nu dezinstalează aplicația din partea GHL - clientul o elimină din instalările sale din marketplace-ul GHL dacă dorește și acest lucru.

curl -X DELETE "https://api.youraiconnector.com/v1/channels/ghl/abc123location" \
  -H "X-API-Key: YOUR_API_KEY"

Răspuns

{ "success": true, "status": "disconnected", "location_id": "abc123location" }

Numere de telefon (cumpărare și eliberare) #

În loc să conectați un număr existent, puteți cumpăra direct un număr nou compatibil cu WhatsApp. Căutați numere disponibile, cumpărați unul, apoi interogați până când finalizarea provizionării este completă.

Pasul 1 - Căutarea numerelor disponibile #

GET /phone-numbers/available?country_code=ISO2

cURL

curl "https://api.youraiconnector.com/v1/phone-numbers/available?country_code=US&apiKey=YOUR_API_KEY"

JavaScript

const res = await fetch(
  "https://api.youraiconnector.com/v1/phone-numbers/available?country_code=US",
  { headers: { "X-API-Key": "YOUR_API_KEY" } }
);
const data = await res.json();

Python

res = requests.get(
    "https://api.youraiconnector.com/v1/phone-numbers/available",
    params={"country_code": "US"},
    headers={"X-API-Key": "YOUR_API_KEY"},
)
data = res.json()

Răspuns

{
  "success": true,
  "phone_numbers": [
    {
      "phone_number": "+14155551234",
      "purchase_credits": 50,
      "monthly_credits": 50,
      "cost_usd": 1.15
    }
  ]
}

Fiecare rezultat afișează purchase_credits unic și monthly_credits recurent. Un număr furnizat de platformă costă cel puțin 50 de credite pe lună, crescând odată cu prețul lunar al operatorului, taxat la achiziție și la fiecare reînnoire. Citați purchase_credits / monthly_credits pe care îl returnează căutarea; nu derivați niciodată un preț pe cont propriu. Prima căutare pe un cont nou provisionează unele resurse subiacente, deci poate fi puțin mai lentă decât căutările ulterioare.

Pasul 2 - Cumpărați un număr #

POST /phone-numbers

Utilizați un phone_number din rezultatele căutării.

cURL

curl -X POST "https://api.youraiconnector.com/v1/phone-numbers" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "phone_number": "+14155551234",
    "country_code": "US",
    "display_name": "Support line"
  }'

JavaScript

const res = await fetch("https://api.youraiconnector.com/v1/phone-numbers", {
  method: "POST",
  headers: {
    "X-API-Key": "YOUR_API_KEY",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    phone_number: "+14155551234",
    country_code: "US",
    display_name: "Support line",
  }),
});
const data = await res.json();

Python

res = requests.post(
    "https://api.youraiconnector.com/v1/phone-numbers",
    headers={"X-API-Key": "YOUR_API_KEY"},
    json={
        "phone_number": "+14155551234",
        "country_code": "US",
        "display_name": "Support line",
    },
)
data = res.json()

Răspuns

{
  "success": true,
  "phone_number": "+14155551234",
  "channel": "whatsapp",
  "whatsapp_status": "PURCHASED",
  "outgoing_status": "PURCHASED",
  "status": "PURCHASED",
  "purchase_credits": 50,
  "monthly_credits": 50
}

Numărul începe în starea PURCHASED. Înregistrarea WhatsApp continuă apoi în fundal: PURCHASED -> PENDING -> ONLINE.

Dacă achiziția eșuează deoarece lipsește o adresă de afaceri sau un alt detaliu obligatoriu nu este setat, veți primi un 400 cu un error descriptiv. Configurați detaliul lipsă și încercați din nou.

Pasul 3 - Interogați până la starea ONLINE #

GET /phone-numbers/{phoneNumber}/status

Acesta este punctul final partajat pentru starea numărului de telefon - funcționează atât pentru numerele WhatsApp cumpărate, cât și pentru celelalte numere conectate.

cURL

curl "https://api.youraiconnector.com/v1/phone-numbers/+14155551234/status" \
  -H "X-API-Key: YOUR_API_KEY"

JavaScript

const phone = encodeURIComponent("+14155551234");
const res = await fetch(
  `https://api.youraiconnector.com/v1/phone-numbers/${phone}/status`,
  { headers: { "X-API-Key": "YOUR_API_KEY" } }
);
const data = await res.json();
// Poll until data.status === "ONLINE".

Python

import urllib.parse

phone = urllib.parse.quote("+14155551234")
res = requests.get(
    f"https://api.youraiconnector.com/v1/phone-numbers/{phone}/status",
    headers={"X-API-Key": "YOUR_API_KEY"},
)
data = res.json()
# Poll until data["status"] == "ONLINE".

Răspuns

{
  "success": true,
  "phone_number": "+14155551234",
  "channel": "whatsapp",
  "status": "ONLINE",
  "status_reason": null,
  "live": true
}

Pasul 4 - Eliberați un număr #

DELETE /phone-numbers/{phoneNumber}

curl -X DELETE "https://api.youraiconnector.com/v1/phone-numbers/+14155551234" \
  -H "X-API-Key: YOUR_API_KEY"

Răspuns

{ "success": true, "phone_number": "+14155551234", "released": true }

Ce face acest lucru depinde de cui aparține numărul.

Pentru un număr închiriat prin intermediul platformei, este o eliberare propriu-zisă: expeditorul WhatsApp este dezînregistrat, numărul este returnat operatorului și eliminat din cont, se aplică o perioadă de răcire de 7 zile în care numărul nu poate fi răscumpărat de nimeni și nu se rambursează credite.

Pentru un număr pe care contul l-a adus singur (propriul cont Twilio, propria aplicație Meta sau cont WhatsApp Business, sau un gateway SMS Android), același apel doar îl elimină din cont. Nimic nu este eliberat la furnizorul din amonte și nu este scris niciun timp de răcire, așa că numărul poate fi reconectat imediat. Înregistrarea expeditorului său WhatsApp, dacă a avut una, poate supraviețui sau nu: procesul de eliminare încearcă să șteargă expeditorul folosind credențialele Twilio gestionate de platformă ale contului. Pe un cont care este încă pe configurația gestionată, acele credențiale sunt valide și expeditorul este șters, deci reconectarea înseamnă înregistrarea lui din nou. Pe un cont care a trecut la propriul Twilio, ștergerea nu se poate autentifica, iar expeditorul rămâne înregistrat în acel cont — reconectarea este atunci doar reatașarea expeditorului existent.

Adăugarea unui număr pe care îl dețineți deja (BYO) #

POST /phone-numbers/byo

Omite complet fluxul de căutare și cumpărare de mai sus. Utilizați acest lucru atunci când contul își aduce propriul număr (propriul Twilio, propriul cont Meta WhatsApp Business sau un gateway SMS Android) în loc să închirieze unul prin intermediul platformei. Aceasta doar înregistrează numărul - nu se percep credite și nu se provisionează nimic la un furnizor aici. Numărul rămâne inactiv până când titularul contului finalizează OAuth pentru WhatsApp pentru a înregistra un Expeditor pe acesta (același flux pe care îl pornește butonul „Aduceți propriul număr” din tablou de bord).

curl -X POST "https://api.youraiconnector.com/v1/phone-numbers/byo?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "phone_number": "+14155551234",
    "country_code": "US",
    "display_name": "Support line"
  }'

Răspuns (201 Created):

{
  "success": true,
  "phone_number": "+14155551234",
  "channel": "whatsapp",
  "type": "BYO",
  "whatsapp_status": "ADDED",
  "outgoing_status": "ADDED",
  "is_active": false
}

Un phone_number care nu este un număr E.164 real (sau care arată ca numărul de test WhatsApp al Meta, care nu poate trimite niciodată mesaje clienților reali) returnează 400. Adăugarea unui număr care există deja în cont - chiar dacă este scris ușor diferit, cum ar fi formele +52 vs +521 din Mexic - returnează 409 în loc să creeze un rând duplicat.

Setarea unui număr ca principal #

POST /phone-numbers/{phoneNumber}/set-primary

Comută un număr la is_active: true și toate celelalte numere din cont la is_active: false, atomic - contul nu ajunge niciodată să aibă două numere active sau niciunul în timpul solicitării. is_active nu poate fi setat prin endpoint-ul general de actualizare în mod intenționat; acest apel dedicat este singura modalitate de a schimba numărul principal.

curl -X POST "https://api.youraiconnector.com/v1/phone-numbers/+14155551234/set-primary" \
  -H "X-API-Key: YOUR_API_KEY"

Răspuns

{
  "success": true,
  "phone_number": {
    "id": "+14155551234",
    "phone_number": "+14155551234",
    "display_name": "Support line",
    "channel": "whatsapp",
    "is_active": true,
    "whatsapp_status": "ONLINE"
  }
}

phone_number de aici este obiectul complet al numărului (aceeași formă pe care o returnează GET /phone-numbers), nu doar șirul. Un phoneNumber care nu se află în cont returnează 404.

Eliminarea înregistrării unui număr (fără a-l elibera) #

DELETE /phone-numbers/{phoneNumber}/record

O ștergere simplă a înregistrării numărului din acest cont - fără eliberare sau dezînregistrare din partea furnizorului și fără perioada de răcire de 7 zile care se aplică pasului de eliberare de mai sus. Utilizați acest lucru pentru a șterge înregistrările BYO, WhatsApp Web, Telegram sau LINE, sau o intrare învechită, fără a trece prin fluxul de eliberare gestionat. Spre deosebire de o eliberare, ștergerea unui număr care nu se află în cont este un 404, nu un succes silențios.

curl -X DELETE "https://api.youraiconnector.com/v1/phone-numbers/+14155551234/record" \
  -H "X-API-Key: YOUR_API_KEY"

Răspuns

{ "success": true, "phone_number": "+14155551234", "deleted": true }

Direcționați un canal către o campanie #

Conectarea unui canal aduce mesajele în cont. Aceasta nu decide ce Agent AI le răspunde.

Rutarea este gestionată de Puncte de Intrare (Entry Points) pe un Agent AI, nu de campanii. Fiecare canal are un Punct de Intrare implicit care numește Agentul ce răspunde contactelor noi, necunoscute, pe acel canal:

Până când un canal are un Punct de Intrare (Entry Point), un prim mesaj de la cineva cu care nu ați mai vorbit este stocat, dar nimic nu îl preia și niciun asistent nu răspunde. Acesta este pasul pe care majoritatea integrărilor îl omit: conectarea Instagram și crearea unui Agent nu sunt suficiente de la sine — trebuie, de asemenea, să direcționați canalul către Agent. Setul complet de apeluri — incluzând un Agent per număr de WhatsApp, cuvinte cheie și reguli pentru comentarii — se află în API-ul Punctelor de Intrare.

POST /channels/campaign scrie în continuare harta de rutare a campaniilor per-canal moștenită, documentată mai jos, dar acea hartă nu mai este consultată pentru rutarea de intrare pe niciun cont; este păstrată doar pentru rollback. Nu construiți pe baza ei.

Rutarea unuia sau mai multor canale (hartă de rutare a campaniilor moștenită) #

POST /channels/campaign

Câmpuri de solicitare

Slotul de direcționare și lista enabled_channels a campaniei sunt actualizate împreună într-o singură operațiune atomică, astfel încât să nu poată fi niciodată nealiniate. Un canal deja direcționat către o altă campanie este pur și simplu redirecționat către aceasta.

cURL

curl -X POST "https://api.youraiconnector.com/v1/channels/campaign?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "campaign_id": "NBCXrhqGPSFsd6MV7pRo",
    "channels": ["instagram", "messenger"]
  }'

JavaScript

const res = await fetch("https://api.youraiconnector.com/v1/channels/campaign", {
  method: "POST",
  headers: {
    "X-API-Key": "YOUR_API_KEY",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    campaign_id: "NBCXrhqGPSFsd6MV7pRo",
    channels: ["instagram", "messenger"],
  }),
});
const data = await res.json();

Python

import requests

res = requests.post(
    "https://api.youraiconnector.com/v1/channels/campaign",
    headers={"X-API-Key": "YOUR_API_KEY"},
    json={
        "campaign_id": "NBCXrhqGPSFsd6MV7pRo",
        "channels": ["instagram", "messenger"],
    },
)
data = res.json()

Răspuns

{
  "success": true,
  "campaign_id": "NBCXrhqGPSFsd6MV7pRo",
  "channels": ["instagram", "messenger"]
}

Ce trebuie să fie adevărat pentru ca direcționarea să funcționeze efectiv #

Pe un cont care încă citește harta de rutare a campaniilor moștenită, rutarea reușește ca apel API, dar trei lucruri din campanie decid dacă un mesaj real de intrare primește răspuns. Verificați toate cele trei aspecte atunci când un canal rutat rămâne tăcut.

Potrivirea cuvintelor cheie se află acum în Punctele de Intrare — creați un Punct de Intrare de tip keyword pe Agentul AI care ar trebui să răspundă.

O campanie per canal #

Fiecare canal deține exact un slot de rutare moștenit. Rutarea unei a doua campanii către același canal redirecționează silențios slotul și returnează 200 — nu există nicio eroare de conflict. Campania anterioară continuă să gestioneze contactele pe care le are deja; pur și simplu nu mai primește altele noi.

Șterge rutarea unui canal #

DELETE /channels/campaign/{channel}

Elimină rutarea pentru un singur canal, indiferent de campania către care indică în prezent, și elimină canalul din enabled_channels acelei campanii. Contactele noi necunoscute de pe canal nu mai sunt preluate de nicio campanie. Contactele deja aflate în campanie își continuă activitatea ca înainte.

curl -X DELETE "https://api.youraiconnector.com/v1/channels/campaign/instagram?apiKey=YOUR_API_KEY"

Răspuns

{
  "success": true,
  "channel": "instagram",
  "cleared": true,
  "campaign_id": "NBCXrhqGPSFsd6MV7pRo"
}

Este idempotentă: ștergerea unui canal care nu a fost niciodată rutat returnează de asemenea 200, cu cleared: false și campaign_id: null. Acest endpoint necesită funcționalitatea campanii primite în planul tău; fără aceasta, vei primi un 403.

Utilizați propria aplicație Meta (Instagram + Messenger) #

În mod implicit, conexiunea Instagram + Messenger rulează prin aplicația Meta a platformei, astfel încât numele acelei aplicații este ceea ce vede titularul contului pe ecranul de consimțământ Facebook. Dacă doriți ca ecranul de consimțământ să afișeze brandul dvs., puteți să vă înregistrați propria aplicație Meta și să direcționați întregul flux prin aceasta. Odată configurată, aceasta se aplică contului dvs. — nimic nu se schimbă în apelurile de conectare de mai sus, cu excepția brandingului.

Acest lucru acoperă doar Instagram + Messenger. Conexiunile WhatsApp, WhatsApp Web, Telegram și LINE nu sunt afectate de o aplicație Meta personalizată.

De ce are nevoie aplicația dumneavoastră mai întâi #

Aceasta este partea care necesită timp și se întâmplă în întregime pe partea Meta:

1. O aplicație de tip Business, cu produsele Messenger și Instagram adăugate.
2. Acces avansat (prin Meta App Review) pentru: pages_show_list, pages_messaging, pages_manage_metadata, pages_read_engagement, instagram_basic, instagram_manage_messages. Fără acces avansat, doar persoanele care dețin un rol în aplicația dumneavoastră pot finaliza conexiunea — conexiunile clienților dumneavoastră vor eșua. Revizuirea aplicației durează de obicei câteva săptămâni și necesită verificarea afacerii (Business Verification).
3. O configurație Facebook Login for Business creată în interiorul aplicației dumneavoastră, care acordă aceleași permisiuni. ID-ul său numeric de configurare este per aplicație, deci trebuie să îl creați pe al dumneavoastră.

Dacă aplicației dumneavoastră îi lipsește oricare dintre permisiunile necesare, conexiunea eșuează în momentul conectării cu o eroare clară care indică ce lipsește (vizibilă în sondajul /status ca byo_app_missing_permissions) — în loc să pară că funcționează și să eșueze la primul mesaj.

Pasul 1 - Salvați aplicația #

PUT /account-config/meta-app

Toate cele trei sunt necesare pentru fluxul de Autentificare Facebook. Dacă rulați doar calea de trimitere a tokenului pentru Autentificarea Instagram descrisă mai jos, le puteți omite complet.

curl -X PUT "https://api.youraiconnector.com/v1/account-config/meta-app?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "app_id": "1234567890123456",
    "app_secret": "your-app-secret",
    "config_id": "9876543210987654"
  }'

Răspuns

{
  "success": true,
  "app_id": "1234567890123456",
  "config_id": "9876543210987654",
  "verify_token": "1f4c…a9",
  "webhook_urls": {
    "instagram": "https://api.youraiconnector.com/v1/incoming-instagram-message/byo/YOUR_ACCOUNT_ID",
    "messenger": "https://api.youraiconnector.com/v1/incoming-messenger-message/byo/YOUR_ACCOUNT_ID"
  }
}

Pasul 2 - Configurați aplicația pentru a comunica cu noi #

În tabloul de bord al aplicației Meta:

1. Webhooks - atât pentru produsele Instagram, cât și pentru Messenger, setați URL-ul de callback la valoarea webhook_urls corespunzătoare din răspuns și tokenul de verificare la verify_token. Abonați-vă la câmpurile messages, messaging_postbacks și comments.
2. URI-uri de redirecționare OAuth valide - adăugați https://api.youraiconnector.com/v1/auth-meta-callback-handler pentru ca fluxul de consimțământ să poată reveni.

GET /account-config/meta-app returnează același material de configurare oricând; DELETE /account-config/meta-app elimină aplicația (conexiunile viitoare revin la aplicația platformei — eliminați, de asemenea, abonamentul webhook din interiorul aplicației dumneavoastră).

Pasul 3 - Conectați-vă ca de obicei #

Nimic altceva nu se schimbă. POST /channels/meta/connect (și pagina găzduită connect_url) utilizează automat aplicația dvs. pentru contul dvs.; uses_byo_meta_app: true din răspuns confirmă ce aplicație va afișa ecranul de consimțământ. Trimiterea mesajelor, selectarea paginii și deconectările funcționează identic.

Aduceți propria aplicație de autentificare Instagram (push de token) #

Secțiunea de mai sus acoperă fluxul de autentificare Facebook, unde contul se conectează printr-o pagină de Facebook. Meta oferă, de asemenea, API-ul Instagram cu autentificare Instagram (Business Login for Instagram): deținătorul contului se autentifică direct pe Instagram, fără a fi nevoie de un cont sau o pagină de Facebook.

Dacă platforma dvs. rulează deja propria aplicație Meta cu acel produs, nu aveți nevoie deloc de niciun flux OAuth din partea noastră. Clienții dvs. autorizează aplicația dvs., iar dvs. ne trimiteți (push) acreditările finalizate pentru fiecare cont:

1. Salvați acreditările aplicației dvs. Instagram o singură dată (pentru a putea verifica webhook-urile dvs.).
2. Pentru fiecare cont, trimiteți ID-ul contului profesional de Instagram + tokenul de utilizator Instagram pe termen lung obținut de aplicația dvs.
3. Direcționați webhook-ul de mesagerie Instagram al aplicației dvs. către noi. Evenimentele pentru conturile pe care nu le-ați trimis sunt confirmate și ignorate.
4. Dvs. dețineți ciclul de viață al tokenului: reîmprospătați tokenurile în propriul sistem și trimiteți fiecare token reîmprospătat cu același apel. Noi nu reîmprospătăm niciodată un token trimis prin push.

De ce are nevoie aplicația dumneavoastră mai întâi #

• Produsul Instagram („API setup with Instagram login”) adăugat la aplicația dvs. Meta. Acest produs are propria pereche de App ID și App Secret, separată de App ID/Secret-ul de Facebook — le găsiți în panoul de configurare al produsului.
• Acces avansat (prin Meta App Review) pentru instagram_business_basic și instagram_business_manage_messages (adăugați instagram_business_manage_comments dacă utilizați automatizări pentru comentarii). Fără acesta, doar persoanele cu un rol în aplicația dvs. o pot autoriza.

Pasul 1 - Salvați acreditările aplicației dvs. Instagram #

Același endpoint ca mai sus — trimiteți perechea Instagram către PUT /account-config/meta-app. Câmpurile Facebook nu sunt necesare pentru această cale: trimiteți perechea singură dacă rulați doar Autentificarea Instagram, sau împreună cu câmpurile Facebook dacă le rulați pe amândouă. O salvare descrie întotdeauna întreaga setare, deci orice set omiteți va fi eliminat.

curl -X PUT "https://api.youraiconnector.com/v1/account-config/meta-app?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "instagram_app_id": "1122334455667788",
    "instagram_app_secret": "your-instagram-app-secret"
  }'

Răspuns — conține URL-ul webhook-ului pentru Autentificarea Instagram (URL-urile instagram și messenger apar doar atunci când sunt stocate și câmpurile Facebook):

{
  "success": true,
  "instagram_app_id": "1122334455667788",
  "verify_token": "1f4c…a9",
  "webhook_urls": {
    "instagram_login": "https://api.youraiconnector.com/v1/incoming-instagram-login-message/byo/YOUR_ACCOUNT_ID"
  }
}

În panoul Webhooks al aplicației dvs. pentru produsul Instagram, setați Callback URL la webhook_urls.instagram_login, Verify token la verify_token și abonați-vă la câmpurile messages și comments.

Pasul 2 - Trimiteți (push) un token per cont #

PUT /channels/instagram-login/token

Funcționează cu sub_account_id ca orice altă rută, astfel încât o cheie de agenție poate furniza întreaga sa flotă.

curl -X PUT "https://api.youraiconnector.com/v1/channels/instagram-login/token?apiKey=YOUR_AGENCY_KEY&sub_account_id=CLIENT_ID" \
  -H "Content-Type: application/json" \
  -d '{
    "ig_user_id": "17841400000000000",
    "access_token": "IGAAR…",
    "expires_at": "2026-11-01T00:00:00Z"
  }'

Răspuns

{
  "success": true,
  "ig_user_id": "17841400000000000",
  "username": "acme.studio",
  "expires_at": "2026-11-01T00:00:00.000Z",
  "webhook_url": "https://api.youraiconnector.com/v1/incoming-instagram-login-message/byo/YOUR_ACCOUNT_ID"
}

Ca parte a procesului de push, abonăm aplicația dvs. la webhook-urile acelui cont (subscribed_apps cu tokenul trimis), astfel încât mesajele să înceapă să curgă fără niciun apel suplimentar din partea dvs.

Reîmprospătare - trimiteți jetonul reîmprospătat către același punct final cu același ig_user_id; acesta actualizează jetonul stocat și data expirării pe loc.

Conflicte - un cont de Instagram nu este niciodată activ pe două conexiuni. Dacă respectivul cont este deja conectat în altă parte sau prin acest cont prin fluxul Paginii de Facebook, cererea returnează un 409 care vă indică ce conexiune să deconectați mai întâi. O conexiune prin fluxul Facebook nu este niciodată înlocuită automat, deoarece poate deservi și Messenger.

Pasul 3 - Deconectați când un client pleacă #

DELETE /channels/instagram-login/token (aceeași autentificare și sub_account_id) dezabonează webhook-urile prin „best-effort” și elimină acreditarea stocată. Aceasta reușește întotdeauna, chiar și atunci când jetonul a expirat deja — iar odată ce acreditarea a fost eliminată, evenimentele webhook ale acelui cont sunt ignorate.

Sfaturi pentru construirea unui wrapper fiabil #

• Interogați cu moderație. La fiecare câteva secunde este suficient. Opriți-vă odată ce ajungeți la o stare terminală (connected / ONLINE sau o stare de eșec) și setați un timeout general rezonabil pentru buclă (pașii browser/QR expiră, consultați fiecare expires_at).
• Codificați URL-ul numerelor de telefon în cale. Simbolul + de la început ar trebui trimis ca %2B. Endpoint-urile recuperează și cifrele brute, dar codificarea este varianta implicită sigură.
• Nu vă așteptați niciodată să primiți secrete înapoi. Token-urile de acces, secretele canalului și token-urile de pagină sunt acceptate sau stocate, dar nu sunt niciodată returnate în niciun răspuns.
• Gestionați poarta de autentificare. Un 403 înseamnă că accesul API nu este inclus în plan sau că canalul pe care îl conectați nu este inclus în planul contului. Consultați Acces API.
• Atenție la limita de rată. Cererile autentificate sunt limitate la 300 pe minut; un 429 înseamnă să faceți o pauză și să reîncercați. Consultați Autentificare.

Pașii următori #

• Autentificare - cele patru forme de autentificare acceptate și formatul erorilor.
• Acces API - generarea și gestionarea cheii API.