Introducere în API #

API-ul REST DM Champ vă permite să construiți propria integrare pe baza contului dumneavoastră. Puteți crea și căuta contacte, gestiona campanii, întrebări frecvente (FAQ), sarcini și programări, trimite mesaje, înregistra webhook-uri, citi analize și conecta canale de mesagerie — tot ceea ce face tabloul de bord, controlat prin cod.

Aceasta este pagina centrală pentru documentația API. Dacă conectați DM Champ la un instrument care are deja o integrare încorporată, este posibil să nu aveți nevoie deloc de API. API-ul este destinat integrărilor personalizate și automatizării la scară largă.

URL de bază #

Fiecare cerere este trimisă la aceeași adresă web de bază, iar toate căile din aceste documente sunt relative la aceasta:

https://api.dmchamp.com/v1

Așadar, endpoint-ul pentru Agenții AI este https://api.dmchamp.com/v1/agents, endpoint-ul pentru contacte este https://api.dmchamp.com/v1/contacts și așa mai departe.

Toate cererile trebuie să utilizeze o conexiune securizată (HTTPS). Cererile HTTP simple sunt respinse.

Obținerea unei chei API #

Accesul la API este o funcționalitate plătită. Dacă planul dumneavoastră nu o include, fiecare cerere va returna un 403 cu acest conținut:

{
  "success": false,
  "error_code": 403,
  "error": "This action requires the \"api_access\" feature, which is not enabled for this account."
}

Odată ce accesul API este activat în planul tău, generează o cheie din tabloul de bord. Pașii detaliați se află în Acces API — pe scurt: mergi la Setări → Integrări → Cheie API pentru a genera sau regenera cheia. Cheia API are propria secțiune în cadrul Integrărilor, separată de Webhook-uri, și apare doar după ce accesul API este activat în planul tău. Tratează cheia ca pe o parolă: aceasta oferă acces complet la contul tău.

Autentificare #

Puteți trimite cheia API în patru moduri. Toate funcționează pe fiecare punct final care acceptă autentificarea prin cheie API.

Pentru producție, preferați una dintre formele de antet, astfel încât cheia dumneavoastră să nu ajungă niciodată într-un jurnal de server sau în istoricul browserului. Forma cu parametru de interogare funcționează întotdeauna și este cea mai simplă pentru un test rapid.

Consultați Autentificare pentru o detaliere completă a fiecărei metode, cu exemple și îndrumări despre când să utilizați fiecare variantă.

Prima dumneavoastră cerere #

Iată un apel complet și funcțional care listează Agenții AI din contul tău. Acesta utilizează cheia ta API și returnează un rând scurt pentru fiecare Agent, începând cu cel mai recent.

cURL

curl "https://api.dmchamp.com/v1/agents?apiKey=YOUR_API_KEY&view=summary"

JavaScript

const res = await fetch("https://api.dmchamp.com/v1/agents?view=summary", {
  headers: {
    "X-API-Key": "YOUR_API_KEY",
  },
});

const data = await res.json();
console.log(data.agents);

Python

import requests

res = requests.get(
    "https://api.dmchamp.com/v1/agents",
    params={"view": "summary"},
    headers={"X-API-Key": "YOUR_API_KEY"},
)

data = res.json()
print(data["agents"])

Un răspuns reușit arată astfel:

{
  "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": null
}

Răspunsuri de succes și de eroare #

Fiecare răspuns JSON conține un indicator success, astfel încât să poți ramifica logica fără a analiza codurile de stare.

Un răspuns reușit este success: true plus datele pentru acel endpoint (numele câmpului variază — campaigns, contacts, data și așa mai departe):

{
  "success": true,
  "campaigns": []
}

Un răspuns eșuat este success: false cu un mesaj error ușor de citit pentru oameni și un error_code numeric care corespunde stării HTTP:

{
  "success": false,
  "error": "Invalid cursor",
  "error_code": 400
}

Verifică întotdeauna success (sau starea HTTP) înainte de a citi datele. Consultă Erori și paginare pentru tabelul complet cu coduri de stare și pentru modul de paginare a seturilor mari de rezultate.

Limite de rată #

Cererile autentificate sunt limitate la 300 de cereri pe minut per cheie API. Există, de asemenea, o limită mai largă de 1.200 de cereri pe minut per cont, care contorizează fiecare cerere autentificată efectuată pentru acel cont.

Dacă depășiți oricare dintre limite, veți primi un răspuns 429:

{
  "success": false,
  "error_code": 429,
  "error": "Rate limit exceeded. Please try again later."
}

Redu frecvența și reîncearcă după o scurtă așteptare. De asemenea, poți verifica utilizarea curentă în orice moment cu GET https://api.dmchamp.com/v1/api-keys/usage, care returnează câte cereri ai utilizat în fereastra curentă și când se resetează — util pentru construirea limitării de rată (throttling) pe partea de client. Consultă Chei API.

Ghiduri de resurse #

Grupurile de resurse de mai jos au fiecare propriul ghid cu căile exacte, câmpurile de solicitare și formele de răspuns.

Agenți, puncte de intrare și difuzări #

Agenții AI, Punctele de intrare și Difuzările sunt toate incluse în specificația OpenAPI publicată, astfel încât puteți naviga prin câmpurile lor exacte și puteți rula cereri live împotriva acestora în exploratorul API. Fiecare are propriul ghid: Agenți AI, Puncte de intrare și Difuzări.

Citirea acestor documente ca Markdown #

Fiecare pagină din această documentație are o variantă Markdown simplă: luați adresa paginii și adăugați /index.md la final. Astfel, această pagină este disponibilă și la https://docs.youraiconnector.com/api/getting-started/index.md și este returnată ca text simplu, nu ca pagină web — util atunci când doriți să lipiți o pagină într-un asistent AI sau să o preluați într-un script.

Pentru un asistent AI sau un script care ar trebui să citească întregul set, există două fișiere gata pregătite:

• https://docs.youraiconnector.com/llms.txt — indexul: fiecare pagină cu un rezumat pe un singur rând și un link către varianta sa Markdown, grupate la fel ca în bara laterală.
• https://docs.youraiconnector.com/llms-full.txt — întreaga documentație într-un singur fișier Markdown. Fiecare pagină începe cu titlul său și o linie Source: care conține adresa paginii, astfel încât un asistent să poată cita sursa unui răspuns.

Ambele există și pentru fiecare limbă, sub prefixul lingvistic (https://docs.youraiconnector.com/nl/llms.txt, https://docs.youraiconnector.com/es/llms-full.txt și așa mai departe). Oferă asistentului tău adresa llms.txt și acesta va prelua paginile de care are nevoie, sau oferă-i llms-full.txt atunci când ar trebui să aibă totul în context deodată. Acestea sunt reconstruite la fiecare modificare a documentației, deci nu devin niciodată perimate.

Pentru a parcurge paginile pe cont propriu, https://docs.youraiconnector.com/sitemap.xml listează fiecare pagină pe care o publicăm. Documentația este păstrată în mod deliberat în afara motoarelor de căutare, așa că accesarea directă a acestor adrese este modalitatea de a ajunge la ea din cod.

Nimic din toate acestea nu necesită o cheie API: variantele Markdown, cele două fișiere llms și harta site-ului reprezintă întreaga interfață.

Pașii următori #

• Autentificare — alege metoda de autentificare potrivită pentru integrarea ta.
• Erori și paginare — gestionează eșecurile și parcurge rezultatele pagină cu pagină.
• Acces API — generează-ți cheia și consultă exemple practice.