API Campanii #

O campanie reunește tot ce are nevoie botul AI pentru a comunica cu contactele tale: instrucțiunile sale, canalele pe care rulează, orele de activitate și comportamentul de follow-up. API-ul de Campanii îți permite să listezi, creezi, actualizezi, duplici, activezi, arhivezi și ajustezi campanii direct din codul tău, în loc să folosești tabloul de bord.

Toate endpoint-urile de mai jos sunt relative la URL-ul de bază https://api.youraiconnector.com/v1. Fiecare cerere trebuie autentificată — consultă Acces API și Autentificare pentru a afla cum să obții și să transmiți cheia API. Accesul la API este o funcționalitate plătită; fără acesta, cererile vor fi respinse cu un 403.

Atenție: Unele exemple arată forma simplă de interogare ?apiKey=YOUR_API_KEY, altele folosesc header-ul X-API-Key. Ambele funcționează peste tot — folosește-o pe cea care se potrivește configurației tale.

Tipuri de campanii #

Când creați o campanie, trebuie să alegeți unul dintre aceste tipuri:

Majusculele nu contează. type, status, booking_provider, first_response_mode, bot.anthropic_model și bot.ai_speed acceptă toate orice tip de scriere — "live", "Live" și "LIVE" sunt același lucru — iar valoarea este stocată în forma sa canonică, care este cea returnată atunci când citești campania. Singura excepție este perechea de pauză: "Paused" și "paused" sunt două stări cu adevărat diferite, așa că o scriere ambiguă precum "PAUSED" este respinsă cu o 400 care îți cere să alegi una.

Cele două stări de pauză #

Ambele opresc campania: rutarea mesajelor primite funcționează doar cât timp statusul este exact Live. Din API, folosiți Paused pentru a întrerupe și Live pentru a relua — perechea cu litere mici există pentru butonul din tabloul de bord și este menținută funcțională pentru acesta.

Niciuna dintre acestea nu reprezintă ceea ce se întâmplă când AI-ul încetează să mai răspundă în cadrul unei conversații. Acesta este un comutator per contact, is_bot_active pe contact — setat atunci când un om preia controlul, când contactul se dezabonează sau când AI-ul încheie chat-ul. Statusul propriu al campaniei rămâne neatins, iar toate celelalte conversații din cadrul acesteia continuă să ruleze. Consultați întreruperea sau reluarea AI-ului pentru un singur contact.

Crearea unei campanii nu decide cine răspunde pe un canal. Rutarea este gestionată de Puncte de Intrare pe un Agent AI, nu de campanii. Fiecare canal are un Punct de Intrare implicit care desemnează Agentul ce răspunde contactelor noi, necunoscute: setați-l cu PUT /entry-points/channel-defaults, verificați dacă ierarhia este activă pentru cont cu GET /entry-points/routing-status, ștergeți-l cu DELETE /entry-points/channel-defaults. POST /channels/campaign scrie în continuare harta de rutare a campaniilor per canal, dar acea hartă nu mai este consultată pentru rutarea de intrare pe niciun cont; este păstrată doar pentru rollback. Nu construiți soluții bazate pe aceasta. Consultați Rutarea unui canal către o campanie pentru a vedea ambele interfețe una lângă alta.

Listare campanii #

GET /campaigns

Returnează campaniile tale, începând cu cele mai noi. Campaniile arhivate sunt excluse, cu excepția cazului în care transmiți archived=true.

Parametri de interogare

cURL

curl "https://api.youraiconnector.com/v1/campaigns?limit=20&apiKey=YOUR_API_KEY"

JavaScript

const res = await fetch("https://api.youraiconnector.com/v1/campaigns?limit=20", {
  headers: { "X-API-Key": "YOUR_API_KEY" },
});
const data = await res.json();
console.log(data.campaigns, data.next_cursor);

Python

import requests

res = requests.get(
    "https://api.youraiconnector.com/v1/campaigns",
    params={"limit": 20},
    headers={"X-API-Key": "YOUR_API_KEY"},
)
data = res.json()
print(data["campaigns"], data["next_cursor"])

Răspuns

{
  "success": true,
  "campaigns": [
    {
      "id": "NBCXrhqGPSFsd6MV7pRo",
      "name": "Inbound WhatsApp Leads",
      "type": "Incoming from Unknown Contacts",
      "status": "Live",
      "enabled": true,
      "archived": false,
      "created_at": 1700000000000,
      "ai_mode": true,
      "language": "en",
      "enabled_channels": ["whatsapp", "instagram"]
    }
  ],
  "next_cursor": "NBCXrhqGPSFsd6MV7pRo"
}

Când next_cursor este null, ați ajuns la ultima pagină.

Obținerea unei campanii #

GET /campaigns/{campaignId}

Returnează documentul complet al campaniei, incluzând configurația botului live (bot), setările de follow-up, canalele activate și orice cuvinte cheie. Marcajele temporale sunt returnate sub formă de milisecunde epoch.

cURL

curl "https://api.youraiconnector.com/v1/campaigns/NBCXrhqGPSFsd6MV7pRo?apiKey=YOUR_API_KEY"

JavaScript

const res = await fetch(
  "https://api.youraiconnector.com/v1/campaigns/NBCXrhqGPSFsd6MV7pRo",
  { headers: { "X-API-Key": "YOUR_API_KEY" } }
);
const { campaign } = await res.json();

Python

import requests

res = requests.get(
    "https://api.youraiconnector.com/v1/campaigns/NBCXrhqGPSFsd6MV7pRo",
    headers={"X-API-Key": "YOUR_API_KEY"},
)
campaign = res.json()["campaign"]

Răspuns

{
  "success": true,
  "campaign": {
    "id": "NBCXrhqGPSFsd6MV7pRo",
    "name": "Inbound WhatsApp Leads",
    "type": "Incoming from Unknown Contacts",
    "status": "Live",
    "language": "en",
    "ai_mode": true,
    "enabled": true,
    "archived": false,
    "created_at": 1700000000000,
    "enabled_channels": ["whatsapp", "instagram"],
    "bot": {
      "instructions": "Greet warmly and ask about their goals.",
      "goal": "Book a discovery call.",
      "ai_speed": "balanced",
      "anthropic_model": "standard",
      "max_messages": 20
    }
  }
}

Crearea unei campanii #

POST /campaigns

Creează o campanie nouă. name și type sunt obligatorii; restul sunt opționale. Puteți include orice alt câmp de campanie în aceeași cerere — de exemplu language, ai_mode sau un obiect de configurare complet bot — și acesta va fi stocat împreună cu noua campanie. Proprietarul și timpul de creare sunt setate automat.

Câmpuri de solicitare

cURL

curl -X POST "https://api.youraiconnector.com/v1/campaigns?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Spring Promo",
    "type": "Outgoing",
    "language": "en",
    "ai_mode": true,
    "bot": {
      "instructions": "Greet warmly and ask about their goals.",
      "goal": "Book a discovery call."
    }
  }'

JavaScript

const res = await fetch("https://api.youraiconnector.com/v1/campaigns", {
  method: "POST",
  headers: {
    "X-API-Key": "YOUR_API_KEY",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    name: "Spring Promo",
    type: "Outgoing",
    language: "en",
    ai_mode: true,
    bot: {
      instructions: "Greet warmly and ask about their goals.",
      goal: "Book a discovery call.",
    },
  }),
});
const { campaign_id } = await res.json();

Python

import requests

res = requests.post(
    "https://api.youraiconnector.com/v1/campaigns",
    headers={"X-API-Key": "YOUR_API_KEY"},
    json={
        "name": "Spring Promo",
        "type": "Outgoing",
        "language": "en",
        "ai_mode": True,
        "bot": {
            "instructions": "Greet warmly and ask about their goals.",
            "goal": "Book a discovery call.",
        },
    },
)
campaign_id = res.json()["campaign_id"]

Răspuns

{
  "success": true,
  "campaign_id": "NBCXrhqGPSFsd6MV7pRo"
}

Actualizarea unei campanii #

PUT /campaigns/{campaignId}

Actualizează parțial o campanie — trimiteți doar câmpurile pe care doriți să le modificați. Acesta este singurul verb general de actualizare; nu există un PATCH /campaigns/{campaignId} (cele două rute PATCH sunt comutatoarele restrânse activare și arhivare).

Ce câmpuri puteți modifica. Tot ceea ce scrie editorul de campanii, inclusiv name, status, type, language, ai_mode, enabled_channels, setările de declanșare și drip, flag-urile de rezervare și follow-up, câmpurile de monitorizare Instagram/Facebook și întreaga configurație bot. Identitatea și proprietatea sunt blocate pe durata de viață a campaniei: user, id și created_at sunt respinse, la fel ca orice nume de câmp pe care endpoint-ul nu îl recunoaște. Respingerea se face per cerere, nu per câmp — o singură cheie necunoscută returnează un 400 și nimic din acea cerere nu este scris.

ai_mode într-o campanie susținută de un Agent reflectă Agentul. Când o campanie este preluată de un Agent AI, citirea campaniei returnează ai_mode derivat din comutatorul Activ al acelui Agent — singurul comutator care decide efectiv dacă AI-ul răspunde. Scrierea ai_mode într-o astfel de campanie este acceptată, dar nu va schimba ceea ce citiți ulterior; în schimb, activați sau dezactivați comutatorul Activ al Agentului (din tabloul de bord sau prin intermediul API-ului pentru Agenți). În campaniile clasice fără Agent, ai_mode citește și scrie valoarea stocată ca până acum.

Câmpurile bot-ului se îmbină, nu se suprascriu. Trimiteți setările bot-ului fie ca chei punctate ("bot.instructions": "..."), fie ca un obiect imbricat ("bot": { "instructions": "..." }) — ambele scriu element cu element, astfel încât câmpurile pe care le omiteți își păstrează valorile curente. bot.instructions, bot.goal, bot.rules și bot.personality sunt toate editabile în acest mod, la fel ca orice altă setare a bot-ului listată sub Câmpuri de configurare bot. Același lucru este valabil pentru test_bot, frequency și follow_up_config.

Pentru a înlocui complet o configurație de bot — ștergând orice câmp pe care nu îl trimiteți — folosiți bot_replace (sau test_bot_replace) cu obiectul complet. Nu puteți combina o înlocuire și o îmbinare pentru același obiect într-o singură cerere; acest lucru returnează un 400.

Câteva câmpuri sunt setate printr-o cheie dedicată în loc să fie scrise direct: utilizați list_id pentru lista de contacte, event_id pentru tipul de eveniment (sau event_ids, o matrice ordonată de ID-uri de tip eveniment, pentru a permite AI-ului să rezerve mai multe — primul este cel implicit; o matrice goală le deconectează pe toate) și contact_ids (o matrice de ID-uri de contact) pentru contactele campaniei. Intrările din baza de cunoștințe sunt gestionate prin API-ul FAQ, nu prin acest endpoint.

Etichetele înlocuiesc, nu se îmbină. Trimite tags ca matrice completă și aceasta devine setul de etichete al campaniei — consultă Etichete campanie pentru câmpuri și pentru punctele finale care adaugă sau editează o singură etichetă.

cURL

curl -X PUT "https://api.youraiconnector.com/v1/campaigns/NBCXrhqGPSFsd6MV7pRo?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "name": "Spring Promo v2", "enabled_channels": ["whatsapp"] }'

JavaScript

const res = await fetch(
  "https://api.youraiconnector.com/v1/campaigns/NBCXrhqGPSFsd6MV7pRo",
  {
    method: "PUT",
    headers: {
      "X-API-Key": "YOUR_API_KEY",
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      name: "Spring Promo v2",
      enabled_channels: ["whatsapp"],
    }),
  }
);
const data = await res.json();

Python

import requests

res = requests.put(
    "https://api.youraiconnector.com/v1/campaigns/NBCXrhqGPSFsd6MV7pRo",
    headers={"X-API-Key": "YOUR_API_KEY"},
    json={"name": "Spring Promo v2", "enabled_channels": ["whatsapp"]},
)
data = res.json()

Răspuns

{
  "success": true,
  "campaign_id": "NBCXrhqGPSFsd6MV7pRo"
}

Ștergerea unei campanii #

DELETE /campaigns/{campaignId}

Șterge definitiv o campanie. Această acțiune nu poate fi anulată — dacă s-ar putea să mai ai nevoie de campanie, arhiveaz-o în schimb.

cURL

curl -X DELETE "https://api.youraiconnector.com/v1/campaigns/NBCXrhqGPSFsd6MV7pRo?apiKey=YOUR_API_KEY"

JavaScript

const res = await fetch(
  "https://api.youraiconnector.com/v1/campaigns/NBCXrhqGPSFsd6MV7pRo",
  { method: "DELETE", headers: { "X-API-Key": "YOUR_API_KEY" } }
);
const data = await res.json();

Python

import requests

res = requests.delete(
    "https://api.youraiconnector.com/v1/campaigns/NBCXrhqGPSFsd6MV7pRo",
    headers={"X-API-Key": "YOUR_API_KEY"},
)
data = res.json()

Răspuns

{
  "success": true
}

Duplică o campanie #

POST /campaigns/{campaignId}/duplicate

Creează o copie a campaniei cu toate setările păstrate. Copia pornește în starea dezactivată, iar numele său primește sufixul (copy), astfel încât să nu trimită niciodată mesaje până când nu o activezi în mod explicit.

cURL

curl -X POST "https://api.youraiconnector.com/v1/campaigns/NBCXrhqGPSFsd6MV7pRo/duplicate?apiKey=YOUR_API_KEY"

JavaScript

const res = await fetch(
  "https://api.youraiconnector.com/v1/campaigns/NBCXrhqGPSFsd6MV7pRo/duplicate",
  { method: "POST", headers: { "X-API-Key": "YOUR_API_KEY" } }
);
const { campaign_id } = await res.json();

Python

import requests

res = requests.post(
    "https://api.youraiconnector.com/v1/campaigns/NBCXrhqGPSFsd6MV7pRo/duplicate",
    headers={"X-API-Key": "YOUR_API_KEY"},
)
new_campaign_id = res.json()["campaign_id"]

Răspuns

{
  "success": true,
  "campaign_id": "aZ9plnewCopyId01234"
}

Copii duplicate în cadrul aceluiași cont.

Activează sau dezactivează o campanie #

PATCH /campaigns/{campaignId}/enabled

Pornește sau oprește o campanie. O campanie dezactivată încetează să mai interacționeze cu contactele, dar își păstrează întreaga configurație.

Câmpuri de solicitare

cURL

curl -X PATCH "https://api.youraiconnector.com/v1/campaigns/NBCXrhqGPSFsd6MV7pRo/enabled?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "enabled": true }'

JavaScript

const res = await fetch(
  "https://api.youraiconnector.com/v1/campaigns/NBCXrhqGPSFsd6MV7pRo/enabled",
  {
    method: "PATCH",
    headers: {
      "X-API-Key": "YOUR_API_KEY",
      "Content-Type": "application/json",
    },
    body: JSON.stringify({ enabled: true }),
  }
);
const data = await res.json();

Python

import requests

res = requests.patch(
    "https://api.youraiconnector.com/v1/campaigns/NBCXrhqGPSFsd6MV7pRo/enabled",
    headers={"X-API-Key": "YOUR_API_KEY"},
    json={"enabled": True},
)
data = res.json()

Răspuns

{
  "success": true,
  "campaign_id": "NBCXrhqGPSFsd6MV7pRo",
  "enabled": true
}

Arhivarea sau restaurarea unei campanii #

PATCH /campaigns/{campaignId}/archived

Arhivează sau restaurează o campanie. Campaniile arhivate sunt ascunse din lista implicită de campanii, dar își păstrează toate datele și pot fi restaurate oricând.

Câmpuri de solicitare

cURL

curl -X PATCH "https://api.youraiconnector.com/v1/campaigns/NBCXrhqGPSFsd6MV7pRo/archived?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "archived": true }'

JavaScript

const res = await fetch(
  "https://api.youraiconnector.com/v1/campaigns/NBCXrhqGPSFsd6MV7pRo/archived",
  {
    method: "PATCH",
    headers: {
      "X-API-Key": "YOUR_API_KEY",
      "Content-Type": "application/json",
    },
    body: JSON.stringify({ archived: true }),
  }
);
const data = await res.json();

Python

import requests

res = requests.patch(
    "https://api.youraiconnector.com/v1/campaigns/NBCXrhqGPSFsd6MV7pRo/archived",
    headers={"X-API-Key": "YOUR_API_KEY"},
    json={"archived": True},
)
data = res.json()

Răspuns

{
  "success": true,
  "campaign_id": "NBCXrhqGPSFsd6MV7pRo",
  "archived": true
}

Actualizarea configurației botului #

PUT /campaigns/{campaignId}/bot-config

Aceasta este metoda sigură de a modifica setările individuale ale botului. Fiecare câmp pe care îl trimiți este îmbinat cu configurația existentă a botului, astfel încât orice câmp pe care îl omiți este păstrat. Folosește această metodă în locul endpoint-ului de actualizare a campaniei ori de câte ori dorești doar să ajustezi o parte a botului.

Cheile câmpurilor trebuie să conțină doar litere, cifre, caractere de subliniere și cratime.

cURL

curl -X PUT "https://api.youraiconnector.com/v1/campaigns/NBCXrhqGPSFsd6MV7pRo/bot-config?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "instructions": "Always answer in a friendly, concise tone.",
    "ai_speed": "balanced"
  }'

JavaScript

const res = await fetch(
  "https://api.youraiconnector.com/v1/campaigns/NBCXrhqGPSFsd6MV7pRo/bot-config",
  {
    method: "PUT",
    headers: {
      "X-API-Key": "YOUR_API_KEY",
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      instructions: "Always answer in a friendly, concise tone.",
      ai_speed: "balanced",
    }),
  }
);
const data = await res.json();

Python

import requests

res = requests.put(
    "https://api.youraiconnector.com/v1/campaigns/NBCXrhqGPSFsd6MV7pRo/bot-config",
    headers={"X-API-Key": "YOUR_API_KEY"},
    json={
        "instructions": "Always answer in a friendly, concise tone.",
        "ai_speed": "balanced",
    },
)
data = res.json()

Răspuns

{
  "success": true,
  "campaign_id": "NBCXrhqGPSFsd6MV7pRo"
}

Câmpurile configurației botului #

Toate câmpurile botului sunt opționale. Trimite doar pe cele pe care dorești să le setezi. Orice câmpuri suplimentare pentru bot, dincolo de cele enumerate aici, sunt acceptate și stocate ca atare.

Setarea orelor active ale botului #

PUT /campaigns/{campaignId}/active-hours

Setează programul de disponibilitate al botului. În afara ferestrelor configurate, botul nu răspunde automat. Această acțiune scrie câmpul availability din configurația botului.

Câmpuri de solicitare

Fiecare zi a săptămânii conține fie o singură fereastră de timp, fie o matrice de ferestre. O fereastră are un start_time și un end_time în format HH:MM de 24 de ore.

cURL

curl -X PUT "https://api.youraiconnector.com/v1/campaigns/NBCXrhqGPSFsd6MV7pRo/active-hours?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "availability": {
      "monday": { "start_time": "09:00", "end_time": "17:00" },
      "tuesday": [
        { "start_time": "09:00", "end_time": "12:00" },
        { "start_time": "13:00", "end_time": "17:00" }
      ]
    }
  }'

JavaScript

const res = await fetch(
  "https://api.youraiconnector.com/v1/campaigns/NBCXrhqGPSFsd6MV7pRo/active-hours",
  {
    method: "PUT",
    headers: {
      "X-API-Key": "YOUR_API_KEY",
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      availability: {
        monday: { start_time: "09:00", end_time: "17:00" },
        tuesday: [
          { start_time: "09:00", end_time: "12:00" },
          { start_time: "13:00", end_time: "17:00" },
        ],
      },
    }),
  }
);
const data = await res.json();

Python

import requests

res = requests.put(
    "https://api.youraiconnector.com/v1/campaigns/NBCXrhqGPSFsd6MV7pRo/active-hours",
    headers={"X-API-Key": "YOUR_API_KEY"},
    json={
        "availability": {
            "monday": {"start_time": "09:00", "end_time": "17:00"},
            "tuesday": [
                {"start_time": "09:00", "end_time": "12:00"},
                {"start_time": "13:00", "end_time": "17:00"},
            ],
        }
    },
)
data = res.json()

Răspuns

{
  "success": true,
  "campaign_id": "NBCXrhqGPSFsd6MV7pRo"
}

Listează funcțiile personalizate ale unei campanii #

GET /campaigns/{campaignId}/custom-functions

Returnează funcțiile personalizate legate de această campanie, rezolvate în definiții complete. Funcțiile personalizate sunt acțiuni HTTP externe pe care botul le poate apela în timpul unei conversații — de exemplu, verificarea stocului în magazinul dvs. sau crearea unei înregistrări în CRM-ul dvs.

cURL

curl "https://api.youraiconnector.com/v1/campaigns/NBCXrhqGPSFsd6MV7pRo/custom-functions?apiKey=YOUR_API_KEY"

JavaScript

const res = await fetch(
  "https://api.youraiconnector.com/v1/campaigns/NBCXrhqGPSFsd6MV7pRo/custom-functions",
  { headers: { "X-API-Key": "YOUR_API_KEY" } }
);
const { custom_functions } = await res.json();

Python

import requests

res = requests.get(
    "https://api.youraiconnector.com/v1/campaigns/NBCXrhqGPSFsd6MV7pRo/custom-functions",
    headers={"X-API-Key": "YOUR_API_KEY"},
)
custom_functions = res.json()["custom_functions"]

Răspuns

{
  "success": true,
  "custom_functions": [
    {
      "id": "fn_abc123",
      "name": "check_stock",
      "description": "Looks up whether a product is in stock.",
      "url": "https://example.com/api/stock",
      "method": "POST",
      "input": [
        { "name": "sku", "type": "string" }
      ],
      "ai_action": "Tell the customer whether the item is available.",
      "created_at": 1700000000000,
      "updated_at": 1700000500000
    }
  ]
}

Conectează o funcție personalizată la o campanie #

POST /campaigns/{campaignId}/custom-functions

Conectează o funcție personalizată existentă la această campanie, astfel încât botul să o poată apela în timpul unei conversații. Conectarea unei funcții care este deja conectată nu are niciun efect.

curl -X POST "https://api.youraiconnector.com/v1/campaigns/NBCXrhqGPSFsd6MV7pRo/custom-functions?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "custom_function_id": "fn_abc123" }'

Răspuns

{
  "success": true,
  "campaign_id": "NBCXrhqGPSFsd6MV7pRo",
  "custom_function_id": "fn_abc123"
}

Deconectează o funcție personalizată de la o campanie #

DELETE /campaigns/{campaignId}/custom-functions/{customFunctionId}

Deconectarea unei funcții care nu este conectată nu are niciun efect.

curl -X DELETE "https://api.youraiconnector.com/v1/campaigns/NBCXrhqGPSFsd6MV7pRo/custom-functions/fn_abc123?apiKey=YOUR_API_KEY"

Răspuns

{
  "success": true,
  "campaign_id": "NBCXrhqGPSFsd6MV7pRo",
  "custom_function_id": "fn_abc123"
}

Conectează o sursă de bază de cunoștințe la o campanie #

POST /campaigns/{campaignId}/kb-sources

Conectează o sursă de bază de cunoștințe (creată prin API-ul pentru întrebări frecvente) la această campanie, astfel încât botul să o poată utiliza atunci când răspunde. Conectarea unei surse care este deja conectată nu are niciun efect.

curl -X POST "https://api.youraiconnector.com/v1/campaigns/NBCXrhqGPSFsd6MV7pRo/kb-sources?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "kb_source_id": "kb_abc123" }'

Răspuns

{
  "success": true,
  "campaign_id": "NBCXrhqGPSFsd6MV7pRo",
  "kb_source_id": "kb_abc123"
}

Deconectează o sursă de bază de cunoștințe de la o campanie #

DELETE /campaigns/{campaignId}/kb-sources/{kbSourceId}

Deconectarea unei surse care nu este conectată nu are niciun efect.

curl -X DELETE "https://api.youraiconnector.com/v1/campaigns/NBCXrhqGPSFsd6MV7pRo/kb-sources/kb_abc123?apiKey=YOUR_API_KEY"

Răspuns

{
  "success": true,
  "campaign_id": "NBCXrhqGPSFsd6MV7pRo",
  "kb_source_id": "kb_abc123"
}

Conectează un server MCP la o campanie #

POST /campaigns/{campaignId}/mcp-servers

Conectează un server MCP la această campanie, oferind botului acces la instrumentele acelui server în timpul unei conversații. Conectarea unui server care este deja conectat nu are niciun efect.

curl -X POST "https://api.youraiconnector.com/v1/campaigns/NBCXrhqGPSFsd6MV7pRo/mcp-servers?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "mcp_server_id": "mcp_abc123" }'

Răspuns

{
  "success": true,
  "campaign_id": "NBCXrhqGPSFsd6MV7pRo",
  "mcp_server_id": "mcp_abc123"
}

Deconectarea unui server MCP de la o campanie #

DELETE /campaigns/{campaignId}/mcp-servers/{mcpServerId}

Deconectarea unui server care nu este conectat nu are niciun efect.

curl -X DELETE "https://api.youraiconnector.com/v1/campaigns/NBCXrhqGPSFsd6MV7pRo/mcp-servers/mcp_abc123?apiKey=YOUR_API_KEY"

Răspuns

{
  "success": true,
  "campaign_id": "NBCXrhqGPSFsd6MV7pRo",
  "mcp_server_id": "mcp_abc123"
}

Biblioteca media a campaniei #

Biblioteca media conține imagini, videoclipuri, documente și note vocale pe care botul le poate trimite în timpul unei conversații.

Listarea bibliotecii media a unei campanii #

GET /campaigns/{campaignId}/media-library

curl "https://api.youraiconnector.com/v1/campaigns/NBCXrhqGPSFsd6MV7pRo/media-library?apiKey=YOUR_API_KEY"

Răspuns

{
  "success": true,
  "campaign_id": "NBCXrhqGPSFsd6MV7pRo",
  "media_items": [
    {
      "id": "media_abc123",
      "item_id": "media_abc123",
      "title": "Pricing sheet",
      "description": "Send when the contact asks about pricing.",
      "media_url": "https://example.com/pricing.pdf",
      "media_content_type": "application/pdf",
      "type": "document",
      "agent_id": "",
      "campaign_id": "NBCXrhqGPSFsd6MV7pRo",
      "media_home": "campaign"
    }
  ]
}

media_url este un URL semnat capturat în momentul încărcării — este posibil să fi expirat deja până când îl citiți; tabloul de bord îl resemnează la cerere.

Încărcarea unui element media #

POST /campaigns/{campaignId}/media-library

curl -X POST "https://api.youraiconnector.com/v1/campaigns/NBCXrhqGPSFsd6MV7pRo/media-library?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "base64Data": "iVBORw0KGgoAAAANSUhEUgAA...",
    "mimeType": "image/png",
    "title": "Product photo",
    "description": "Send when the contact asks what the product looks like."
  }'

Răspuns

{
  "success": true,
  "itemId": "media_abc123",
  "mediaUrl": "https://example.com/product.png",
  "storagePath": "ai_media/campaigns/NBCXrhqGPSFsd6MV7pRo/media_abc123.png",
  "mediaContentType": "image/png",
  "type": "image",
  "isVoiceNote": false
}

Actualizarea unui element media #

PATCH /campaigns/{campaignId}/media-library/{itemId}

Editează doar metadatele elementului — pentru a înlocui fișierul propriu-zis, ștergeți elementul și încărcați unul nou.

curl -X PATCH "https://api.youraiconnector.com/v1/campaigns/NBCXrhqGPSFsd6MV7pRo/media-library/media_abc123?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "title": "Updated pricing sheet" }'

Răspuns

{
  "success": true,
  "campaign_id": "NBCXrhqGPSFsd6MV7pRo",
  "item_id": "media_abc123"
}

Ștergerea unui element media #

DELETE /campaigns/{campaignId}/media-library/{itemId}

Ștergerea unui element care a fost deja eliminat nu are niciun efect.

curl -X DELETE "https://api.youraiconnector.com/v1/campaigns/NBCXrhqGPSFsd6MV7pRo/media-library/media_abc123?apiKey=YOUR_API_KEY"

Răspuns

{ "success": true, "deleted": true }

Etichete campanie #

O etichetă de campanie este o etichetă pe care o înveți pe bot să o aplice unui contact în timpul unei conversații — hot-lead, not-interested, booked-a-call. Fiecare etichetă are trei părți:

Numele etichetelor trebuie să fie unice în cadrul unei campanii. Botul aplică etichetele după nume, deci două intrări care împart același nume nu au un câștigător definit.

Setează toate etichetele unei campanii #

PUT /campaigns/{campaignId} cu o matrice tags.

Aceasta înlocuiește etichetele campaniei cu exact ceea ce trimiți, ceea ce este același lucru pe care îl face fila Etichete din tabloul de bord atunci când o salvezi. Trimite matricea completă de fiecare dată — o etichetă pe care o omiți este o etichetă pe care ai șters-o. Trimiterea [] le șterge pe toate.

cURL

curl -X PUT "https://api.youraiconnector.com/v1/campaigns/NBCXrhqGPSFsd6MV7pRo?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "tags": [
      {
        "name": "hot-lead",
        "description": "The person confirms they want to buy, or asks how to get started right away.",
        "webhook": "https://example.com/hooks/campaign-events"
      },
      {
        "name": "not-interested",
        "description": "The person declines the offer or says they are not a fit."
      }
    ]
  }'

JavaScript

const res = await fetch(
  "https://api.youraiconnector.com/v1/campaigns/NBCXrhqGPSFsd6MV7pRo",
  {
    method: "PUT",
    headers: {
      "X-API-Key": "YOUR_API_KEY",
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      tags: [
        {
          name: "hot-lead",
          description:
            "The person confirms they want to buy, or asks how to get started right away.",
          webhook: "https://example.com/hooks/campaign-events",
        },
        {
          name: "not-interested",
          description: "The person declines the offer or says they are not a fit.",
        },
      ],
    }),
  }
);
const data = await res.json();

Python

import requests

res = requests.put(
    "https://api.youraiconnector.com/v1/campaigns/NBCXrhqGPSFsd6MV7pRo",
    headers={"X-API-Key": "YOUR_API_KEY"},
    json={
        "tags": [
            {
                "name": "hot-lead",
                "description": "The person confirms they want to buy, or asks how to get started right away.",
                "webhook": "https://example.com/hooks/campaign-events",
            },
            {
                "name": "not-interested",
                "description": "The person declines the offer or says they are not a fit.",
            },
        ]
    },
)
data = res.json()

Răspuns

{
  "success": true,
  "campaign_id": "NBCXrhqGPSFsd6MV7pRo"
}

Citește etichetele înapoi cu GET /campaigns/{campaignId}.

Adaugă o etichetă #

POST /campaigns/{campaignId}/tags

Adaugă o singură etichetă fără a retrimite restul. Folosește acest lucru atunci când adaugi la un set pe care nu l-ai construit în această cerere.

curl -X POST "https://api.youraiconnector.com/v1/campaigns/NBCXrhqGPSFsd6MV7pRo/tags?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "tag": { "name": "booked-a-call", "description": "The person confirms a booked time." } }'

Postarea exact aceleiași etichete de două ori nu face nimic a doua oară. Postarea aceluiași tag_id cu un nume sau o descriere diferită adaugă o a doua intrare în loc să o editeze pe prima — folosește punctul final de mai jos pentru a edita pe loc.

Actualizează sau elimină o etichetă #

PUT /campaigns/{campaignId}/tags/{tagId} DELETE /campaigns/{campaignId}/tags/{tagId}

Acestea adresează o singură intrare prin tag_id-ul său, deci funcționează doar pentru etichetele care au fost create cu unul. Dacă o etichetă nu are un tag_id, modificați-o cu PUT /campaigns/{campaignId}-ul pentru întreaga matrice de mai sus.

curl -X PUT "https://api.youraiconnector.com/v1/campaigns/NBCXrhqGPSFsd6MV7pRo/tags/tag_abc123?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "tag": { "name": "hot-lead", "description": "Updated instruction." } }'

Un tagId care nu se află în campanie returnează 404 cu "Tag not found in campaign tags".

Comutarea canalelor unei campanii #

POST /campaigns/{campaignId}/channels

Adaugă sau elimină canale din matricea enabled_channels a campaniei fără a retrimite întreaga matrice — mai sigur decât PUT /campaigns/{campaignId} atunci când altceva ar putea edita campania în același timp.

Trimiteți fie o singură comutare, fie un lot — nu ambele în aceeași cerere:

{ "channel": "whatsapp", "action": "add" }

{ "add": ["whatsapp", "instagram"], "remove": ["sms"] }

Canale valide: whatsapp, whatsapp_web, sms, instagram, messenger, facebook, chat_widget, custom_channel, imessage, telegram, instagram_private, line, viber, tiktok, email, linkedin, skool.

curl -X POST "https://api.youraiconnector.com/v1/campaigns/NBCXrhqGPSFsd6MV7pRo/channels?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "channel": "whatsapp", "action": "add" }'

Răspuns

{
  "success": true,
  "campaign_id": "NBCXrhqGPSFsd6MV7pRo",
  "added": ["whatsapp"],
  "removed": []
}

Aceasta modifică doar canalele prin care campania face publicitate — nu decide cine răspunde la un canal. Consultați Tipuri de campanii de mai sus și Direcționarea unei campanii către canalele primite de mai jos pentru acest aspect.

Comment-to-DM (Instagram și Facebook) #

Comment-to-DM transformă un comentariu la una dintre postările tale într-o conversație privată: cineva comentează, botul îi trimite un mesaj privat (DM), iar campania preia conversația de acolo. Este configurat în întregime prin obiectul campaniei, deci nu există nicio componentă care să țină doar de interfața utilizatorului.

Conectează mai întâi pagina de Facebook — consultă Conectarea canalului. Apoi setează câmpurile de mai jos cu PUT /campaigns/{campaignId}.

Campania trebuie să fie Live. Monitorizarea comentariilor preia doar campaniile a căror status este Live (orice scriere — vezi Tipuri de campanii). Orice altă stare o dezactivează silențios, iar una inventată precum "Active" este acum respinsă cu o 400 în loc să fie stocată. Stările valide includ Draft, Pending Approval, Scheduled, Live, Paused, Completed, Sent și Failed.

Câmpuri

Ștergerea unui câmp

Aceste câmpuri sunt eliminate mai degrabă decât setate la null atunci când trimiți null, astfel încât botul revine la valorile implicite: instagram_post_ids, facebook_post_ids, instagram_comment_delay_minutes, facebook_comment_delay_minutes, public_comment_reply_instructions, follower_outreach_instructions, first_response_exact_text, first_response_exact_text_variants, public_comment_reply_exact_text, public_comment_reply_exact_text_variants.

O singură cheie necunoscută respinge întreaga cerere. PUT /campaigns/{campaignId} validează întregul corp al cererii în raport cu o listă permisă. O cheie care nu este recunoscută returnează 400 pentru întreaga cerere — nu este ignorată silențios, iar niciunul dintre celelalte câmpuri din acel corp nu este scris.

cURL

curl -X PUT "https://api.youraiconnector.com/v1/campaigns/NBCXrhqGPSFsd6MV7pRo?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "status": "Live",
    "monitor_instagram_posts": true,
    "instagram_comment_delay_minutes": 2,
    "first_response_mode": "exact_text",
    "first_response_exact_text": "Hey! Sending the details over now.",
    "first_response_exact_text_variants": [
      "Hi there, here are the details you asked for.",
      "Thanks for commenting, here is what you need."
    ],
    "public_comment_reply_exact_text": "Just sent you a DM."
  }'

JavaScript

const res = await fetch(
  "https://api.youraiconnector.com/v1/campaigns/NBCXrhqGPSFsd6MV7pRo",
  {
    method: "PUT",
    headers: {
      "X-API-Key": "YOUR_API_KEY",
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      status: "Live",
      monitor_instagram_posts: true,
      instagram_comment_delay_minutes: 2,
      first_response_mode: "ai",
      public_comment_reply_instructions:
        "Tell them to check their message requests folder too.",
    }),
  }
);
const data = await res.json();

Python

import requests

res = requests.put(
    "https://api.youraiconnector.com/v1/campaigns/NBCXrhqGPSFsd6MV7pRo",
    headers={"X-API-Key": "YOUR_API_KEY"},
    json={
        "status": "Live",
        "monitor_facebook_posts": True,
        "facebook_post_ids": None,
        "facebook_comment_delay_minutes": 5,
    },
)
data = res.json()

Răspuns

{
  "success": true,
  "campaign_id": "NBCXrhqGPSFsd6MV7pRo"
}

Răspunsul vizibil lăsat la comentariu necesită funcția de răspuns la comentarii din planul tău. Fără aceasta, DM-ul se trimite în continuare, iar răspunsul public este omis.

Optimizarea unei campanii cu AI #

POST /campaigns/{campaignId}/optimize

Rulează aceeași rescriere AI ca fluxurile de feedback „Optimize” și „thumbs-down” din tabloul de bord: preia feedback-ul tău, rescrie instrucțiunile botului și pregătește rezultatul ca o nouă revizuire ciornă pe care să o poți examina.

curl -X POST "https://api.youraiconnector.com/v1/campaigns/NBCXrhqGPSFsd6MV7pRo/optimize?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "user_feedback": "Make the tone more casual and mention the free trial earlier." }'

Răspuns (202 — rescrierea rulează în fundal)

{ "success": true, "campaign_id": "NBCXrhqGPSFsd6MV7pRo" }

Interoghează GET /campaigns/{campaignId} și urmărește test_bot.status: se schimbă imediat în "Optimizing", apoi revine la "Draft" odată ce rescrierea ajunge în test_bot. De acolo, se comportă ca orice ciornă din tabloul de bord — examineaz-o, apoi public-o în tabloul de bord pentru a o face activă. Un 409 înseamnă că o optimizare rulează deja pentru această campanie.

Optimizarea consumă credite, la fel ca orice altă operațiune AI din contul tău.

Atribuie un contact unei campanii #

POST /campaigns/{campaignId}/contacts/{contactId}/assign

Introduce un contact existent într-o campanie și, dacă soliciți acest lucru, trimite imediat mesajul de deschidere al campaniei. Aceasta este metoda prin care poți trimite șablonul WhatsApp aprobat al unei campanii către un contact: șablonul cu care a fost aprobată o campanie aparține acelei campanii, deci nu apare în biblioteca Templates API și nu poate fi trimis prin /whatsapp-templates/send.

curl -X POST "https://api.youraiconnector.com/v1/campaigns/NBCXrhqGPSFsd6MV7pRo/contacts/contact_abc123/assign?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "sendOpeningMessage": true }'

Răspuns

{
  "success": true,
  "data": { "contactId": "contact_abc123", "campaignId": "NBCXrhqGPSFsd6MV7pRo" }
}

Credite: Trimiterea mesajului de deschidere într-o campanie WhatsApp este taxată ca orice trimitere de șablon, prețul fiind stabilit în funcție de țara destinatarului și categoria șablonului. Pe alte canale, mesajul de deschidere este un mesaj obișnuit de ieșire.

Direcționează o campanie către canalele de intrare #

Aceste endpoint-uri gestionează campania care răspunde contactelor noi, necunoscute, pe un canal. Preferă Punctele de Intrare pentru integrări noi (vezi nota de la Tipuri de campanii) — acestea rămân utile pentru lucrul cu campanii care utilizează metoda veche de direcționare și pentru rezolvarea unui conflict de proprietate a canalului între două campanii de intrare.

Alocă o campanie canalelor de intrare #

POST /campaigns/{campaignId}/incoming-routing

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

Răspuns

{
  "success": true,
  "uid": "abc123",
  "campaignId": "NBCXrhqGPSFsd6MV7pRo",
  "channels": ["whatsapp", "instagram"],
  "failed": []
}

channels listează doar canalele care au fost efectiv direcționate către această campanie; failed le listează pe cele care nu au fost. Dacă fiecare canal solicitat eșuează, cererea însăși eșuează.

Șterge direcționarea de intrare a unei campanii #

DELETE /campaigns/{campaignId}/incoming-routing

curl -X DELETE "https://api.youraiconnector.com/v1/campaigns/NBCXrhqGPSFsd6MV7pRo/incoming-routing?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "channelToUnassign": "instagram" }'

Răspuns

{
  "success": true,
  "uid": "abc123",
  "campaignId": "NBCXrhqGPSFsd6MV7pRo",
  "channelsRemoved": ["instagram"]
}

Reactivarea unei campanii inactive #

POST /campaigns/{campaignId}/reactivate

Readuce o campanie din starea Ended, Completed, Paused sau Draft și îi revendică canalele. Funcționează doar pentru campanii Incoming from Unknown Contacts sau Combined — o campanie care este deja Live este tratată ca un succes și nu necesită nicio acțiune.

curl -X POST "https://api.youraiconnector.com/v1/campaigns/NBCXrhqGPSFsd6MV7pRo/reactivate?apiKey=YOUR_API_KEY"

Răspuns

{
  "success": true,
  "data": {
    "success": true,
    "channelsReactivated": ["whatsapp"],
    "channelsBlockedByConflict": [],
    "campaignType": "Incoming from Unknown Contacts"
  }
}

Un canal deja revendicat de agentul unei alte campanii va apărea în channelsBlockedByConflict în loc să cauzeze eșecul întregului apel — folosiți oprirea unei campanii primite conflictuale de mai jos pentru a-l elibera mai întâi, dacă doriți ca această campanie să îl preia. Se returnează un 400 pentru un tip de campanie care nu suportă reactivarea sau pentru o stare care nu este una dintre cele inactive menționate mai sus.

Oprirea unei campanii primite conflictuale #

POST /campaigns/{campaignId}/stop-incoming

Eliberează canalele acestei campanii de la oricare ALTĂ campanie care le deține în prezent, astfel încât această campanie să le poată revendica ulterior. Aceasta este versiunea REST a acțiunii pe care tabloul de bord o efectuează automat atunci când lansați o campanie primită pe un canal la care răspunde deja altcineva.

curl -X POST "https://api.youraiconnector.com/v1/campaigns/NBCXrhqGPSFsd6MV7pRo/stop-incoming?apiKey=YOUR_API_KEY"

Răspuns

{
  "success": true,
  "campaign_id": "NBCXrhqGPSFsd6MV7pRo",
  "ended_campaign_ids": [],
  "released_channels": ["whatsapp"],
  "cleared_entire_field": false
}

released_channels revine gol atunci când această campanie deține deja toate canalele pe care le promovează — nu există nimic de preluat.

Estimări de costuri #

Estimați costul lansării unei campanii înainte de a o trimite.

Estimarea costului șablonului WhatsApp #

GET /campaigns/{campaignId}/template-cost-estimate

curl "https://api.youraiconnector.com/v1/campaigns/NBCXrhqGPSFsd6MV7pRo/template-cost-estimate?apiKey=YOUR_API_KEY"

Răspuns

{
  "success": true,
  "billing_mode": "credits",
  "data": {
    "countries": [
      {
        "countryCode": "1",
        "name": "United States",
        "iso": "US",
        "flag": "🇺🇸",
        "contactCount": 120,
        "costPerContact": 2,
        "subtotal": 240
      }
    ],
    "totalContacts": 120,
    "totalTemplateCost": 240,
    "templateCategory": "marketing",
    "billing_mode": "credits",
    "service_messages_billable_soon": false
  }
}

billing_mode este "credits" pe canalul WhatsApp gestionat. Pe un canal unde Meta facturează direct propriul dvs. cont WhatsApp Business, costPerContact, subtotal și totalTemplateCost revin ca null — niciodată 0, ceea ce ar fi interpretat ca fiind gratuit — deoarece nu există nicio cifră de credit de raportat.

Estimarea costului SMS #

GET /campaigns/{campaignId}/sms-cost-estimate

curl "https://api.youraiconnector.com/v1/campaigns/NBCXrhqGPSFsd6MV7pRo/sms-cost-estimate?apiKey=YOUR_API_KEY"

Răspuns

{
  "success": true,
  "billing_mode": "twilio_direct",
  "data": {
    "totalContacts": 120,
    "messageLength": 87,
    "segmentsPerMessage": 1,
    "totalSegments": 120,
    "estimatedCostUsd": 0.96,
    "priceUnit": "USD per segment",
    "billedByTwilio": true
  }
}

SMS-urile sunt întotdeauna trimise prin propriul dvs. cont Twilio (consultați furnizorul SMS), deci acest lucru este întotdeauna facturat direct de Twilio — estimatedCostUsd este o estimare a acelei facturi Twilio, nu o taxă de credit.

Verificări de limită #

Verificați o limită înainte de a lansa, în loc să aflați despre ea printr-o trimitere eșuată.

Verificări la nivel de campanie #

GET /campaigns/{campaignId}/limits/ai-credit-messaging — dacă lansarea sau programarea acestei campanii ar depăși limita de mesagerie a creditelor AI din contul dvs.

GET /campaigns/{campaignId}/limits/messaging — dacă ar depăși limita zilnică de mesagerie a contului dvs.

curl "https://api.youraiconnector.com/v1/campaigns/NBCXrhqGPSFsd6MV7pRo/limits/messaging?apiKey=YOUR_API_KEY"

Răspuns (limita nu a fost depășită)

{
  "success": true,
  "data": "Campaign is within the daily messaging limit."
}

În schimb, se returnează un 400 atunci când limita ar fi depășită, cu motivul în error.

Verificări la nivel de cont #

GET /campaigns/limits/campaigns — dacă ați atins limita lunară de creare a campaniilor a abonamentului dvs.

GET /campaigns/limits/contacts — dacă ați atins limita de contacte a abonamentului dvs.

curl "https://api.youraiconnector.com/v1/campaigns/limits/campaigns?apiKey=YOUR_API_KEY"

Răspuns

{
  "success": true,
  "data": "You can create 3 more campaigns this month."
}

Totaluri statistici campanie #

GET /campaigns/stats/totals

Totalurile pentru mesaje trimise și răspunsuri pentru fiecare campanie ȘI fiecare agent AI din contul dvs., pe o fereastră de timp ulterioară — aceleași numere pe care pagina cu lista de campanii le afișează lângă fiecare rând, într-un singur apel în loc de o cerere per campanie.

curl "https://api.youraiconnector.com/v1/campaigns/stats/totals?days=30&apiKey=YOUR_API_KEY"

Răspuns

{
  "success": true,
  "byCampaign": {
    "NBCXrhqGPSFsd6MV7pRo": { "sent": 1204, "replied": 318 }
  },
  "byAgent": {
    "agent_abc123": { "sent": 1204, "replied": 318 }
  },
  "windowDays": 30
}

byAgent este propria sa agregare, nu o sumă a byCampaign — traficul unui cont nativ de tip AI-Agent poate să nu aibă nicio campanie, deci altfel ar fi invizibil aici.

Testează o campanie în playground #

Playground-ul îți permite să porți o conversație cu botul unei campanii fără a atinge un canal real sau un contact real. Este același mediu de testare (sandbox) ca panoul de încercare din dashboard și este disponibil complet prin API.

Fluxul este: creează un contact de test ascuns, trimite un mesaj, apoi interoghează campania pentru răspunsul botului. Răspunsurile sunt generate asincron, deci sosesc în test_messages pe campanie, nu în corpul răspunsului.

Playground rulează folosind creditele de cost API. O conversație de testare începută cu o cheie API este taxată la tariful normal pentru mesaje AI, la fel ca un răspuns real, și apare în istoricul de utilizare ca o intrare obișnuită. Testarea din tabloul de bord rămâne gratuită. Diferența este deliberată: o rulare de test efectuează aceeași muncă AI ca una live, deci un playground API nemăsurat ar fi o modalitate de a rula AI nelimitat pe cheltuiala altcuiva.

Pasul 1 - Creează contactul de test #

POST /campaigns/{campaignId}/try-out/contact

Creează contactul de test ascuns și îl leagă de campanie. Toate câmpurile din corp sunt opționale; tot ceea ce omiteți va fi înlocuit cu o identitate eșantion încorporată (John Doe).

curl -X POST "https://api.youraiconnector.com/v1/campaigns/NBCXrhqGPSFsd6MV7pRo/try-out/contact?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "first_name": "Maria", "last_name": "Lopez" }'

Răspuns

{
  "success": true,
  "contactId": "8kQx1vNbA2fLpR7d"
}

Pasul 2 - Înregistrați mesajul primit #

POST /campaigns/{campaignId}/try-out/messages

Adaugă mesaje la firul de discuție de test. Trimiteți mai întâi mesajul vizitatorului aici, astfel încât să apară în istoricul conversației pe care îl citește botul.

curl -X POST "https://api.youraiconnector.com/v1/campaigns/NBCXrhqGPSFsd6MV7pRo/try-out/messages?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "messages": [
      {
        "body": "Do you ship to Belgium?",
        "direction": "inbound",
        "timestamp": "2026-07-22T09:30:00Z"
      }
    ]
  }'

Răspuns

{
  "success": true,
  "campaign_id": "NBCXrhqGPSFsd6MV7pRo",
  "appended": 1
}

Pasul 3 - Solicitați botului să răspundă #

POST /campaigns/{campaignId}/try-out/test-message

Trimite mesajul către fluxul AI. Acesta este apelul care generează efectiv un răspuns din partea botului.

curl -X POST "https://api.youraiconnector.com/v1/campaigns/NBCXrhqGPSFsd6MV7pRo/try-out/test-message?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "message": "Do you ship to Belgium?" }'

Răspuns

{
  "success": true,
  "data": "Published"
}

"Published" înseamnă că mesajul a fost trimis către fluxul AI. "Ignored" înseamnă că un mesaj de test mai nou l-a înlocuit pe acesta — mediul de testare (playground) grupează o serie rapidă de mesaje într-un singur răspuns, la aproximativ patru secunde după ultimul mesaj, la fel cum o conversație reală așteaptă ca cineva să termine de scris. Din cauza acestei ferestre de grupare, acest apel durează câteva secunde până la returnare.

Pasul 4 - Citiți răspunsul #

GET /campaigns/{campaignId}

Răspunsul botului este adăugat la matricea test_messages a campaniei. Interogați campania până când apare o nouă intrare outbound.

{
  "success": true,
  "campaign": {
    "id": "NBCXrhqGPSFsd6MV7pRo",
    "test_messages": [
      { "body": "Do you ship to Belgium?", "direction": "inbound" },
      { "body": "Yes, we ship across the EU.", "direction": "outbound" }
    ]
  }
}

Resetați mediul de testare #

POST /campaigns/{campaignId}/try-out/reset

Șterge întregul sandbox: elimină contactul de test, golește test_messages și eliberează blocajele de răspuns ale botului. Folosește acest lucru între rulările de test.

curl -X POST "https://api.youraiconnector.com/v1/campaigns/NBCXrhqGPSFsd6MV7pRo/try-out/reset?apiKey=YOUR_API_KEY"

Răspuns

{
  "success": true,
  "campaign_id": "NBCXrhqGPSFsd6MV7pRo"
}

Alte endpoint-uri pentru playground #

Erori API campanii #

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

{
  "success": false,
  "error": "Campaign 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.

Legate #

• Direcționează un canal către o campanie — direcționează Instagram, WhatsApp sau orice alt canal către Agentul AI care ar trebui să răspundă, folosind Puncte de Intrare.
• Generează șabloane de follow-up cu AI — pornește o sarcină de fundal care scrie șabloanele de follow-up WhatsApp pentru o campanie.
• API pentru Întrebări Frecvente — gestionează intrările de tip întrebare-răspuns pe care le folosesc campaniile tale.
• Acces API — generează cheia ta API.
• Autentificare — toate modalitățile de a transmite cheia ta.