Wprowadzenie do API #

REST API Your AI Connector umożliwia zbudowanie własnej integracji z Twoim kontem. Możesz tworzyć i wyszukiwać kontakty, zarządzać kampaniami, FAQ, zadaniami i spotkaniami, wysyłać wiadomości, rejestrować webhooki, odczytywać analitykę oraz łączyć kanały komunikacji — wszystko to, co oferuje pulpit nawigacyjny, sterowane za pomocą kodu.

To jest strona główna dokumentacji API. Jeśli łączysz Your AI Connector z narzędziem, które posiada już wbudowaną integrację, być może w ogóle nie potrzebujesz API. API jest przeznaczone do niestandardowych integracji i automatyzacji na dużą skalę.

Podstawowy adres URL #

Każde żądanie jest kierowane pod ten sam podstawowy adres internetowy, a wszystkie ścieżki w tej dokumentacji są względem niego relatywne:

https://api.youraiconnector.com/v1

Zatem punkt końcowy kampanii to https://api.youraiconnector.com/v1/campaigns, punkt końcowy kontaktów to https://api.youraiconnector.com/v1/contacts i tak dalej.

Wszystkie żądania muszą korzystać z bezpiecznego połączenia (HTTPS). Zwykłe żądania HTTP są odrzucane.

Uzyskiwanie klucza API #

Dostęp do API jest płatną funkcją. Jeśli Twój plan go nie obejmuje, każde żądanie zwróci 403 z następującą treścią:

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

Gdy dostęp do API zostanie włączony w Twoim planie, wygeneruj klucz z poziomu panelu nawigacyjnego. Pełna instrukcja krok po kroku znajduje się w Dostęp do API — w skrócie: przejdź do Ustawienia → Integracje → Klucz API, aby wygenerować lub wygenerować ponownie swój klucz. Klucz API stanowi osobną sekcję w ramach Integracji, oddzieloną od Webhooków, i pojawia się dopiero po włączeniu dostępu do API w Twoim planie. Traktuj ten klucz jak hasło: zapewnia on pełny dostęp do Twojego konta.

Uwierzytelnianie #

Możesz wysłać swój klucz API na cztery sposoby. Wszystkie działają w każdym punkcie końcowym, który akceptuje uwierzytelnianie kluczem API.

W środowisku produkcyjnym preferuj jedną z form nagłówka, aby klucz nigdy nie trafił do logów serwera ani historii przeglądarki. Forma parametru zapytania zawsze działa i jest najprostsza w przypadku jednorazowego testu.

Zobacz Uwierzytelnianie, aby uzyskać pełne zestawienie każdej metody wraz z przykładami i wskazówkami, kiedy której użyć.

Twoje pierwsze żądanie #

Oto kompletne, działające wywołanie, które wyświetla listę kampanii na Twoim koncie. Wykorzystuje ono Twój klucz API i zwraca najnowsze kampanie w pierwszej kolejności.

cURL

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

JavaScript

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

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

Python

import requests

res = requests.get(
    "https://api.youraiconnector.com/v1/campaigns",
    params={"limit": 10},
    headers={"X-API-Key": "YOUR_API_KEY"},
)

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

Poprawna odpowiedź wygląda następująco:

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

Odpowiedzi poprawne i błędy #

Każda odpowiedź w formacie JSON zawiera flagę success, dzięki czemu możesz podejmować decyzje bez konieczności analizowania kodów statusu.

Poprawna odpowiedź to success: true oraz dane dla danego punktu końcowego (nazwa pola jest zmienna — campaigns, contacts, data itd.):

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

Nieudana odpowiedź to success: false z czytelnym dla człowieka komunikatem error oraz numerycznym kodem error_code, który odpowiada statusowi HTTP:

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

Zawsze sprawdzaj success (lub status HTTP) przed odczytaniem danych. Zobacz Błędy i stronicowanie, aby uzyskać pełną tabelę kodów statusu oraz informacje o tym, jak poruszać się po dużych zbiorach wyników.

Limity zapytań #

Uwierzytelnione żądania są ograniczone do 300 żądań na minutę na klucz API. Istnieje również szerszy limit 1200 żądań na minutę na konto, obejmujący każde uwierzytelnione żądanie wykonane dla tego konta.

Jeśli przekroczysz którykolwiek z limitów, otrzymasz odpowiedź 429:

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

Wstrzymaj się i ponów próbę po krótkim czasie. Możesz również w dowolnym momencie sprawdzić swoje bieżące zużycie za pomocą GET https://api.youraiconnector.com/v1/api-keys/usage, co zwróci liczbę żądań wykorzystanych w bieżącym oknie oraz czas resetowania — jest to przydatne przy tworzeniu mechanizmów ograniczania liczby żądań po stronie klienta. Zobacz Klucze API.

Przewodniki po zasobach #

Poniższe grupy zasobów mają własne przewodniki z dokładnymi ścieżkami, polami żądań i strukturami odpowiedzi.

Agenci, Punkty wejścia i Transmisje #

Agenci AI, punkty wejścia i transmisje znajdują się w opublikowanej specyfikacji OpenAPI, dzięki czemu możesz przeglądać ich dokładne pola i wykonywać na nich aktywne żądania w eksploratorze API. Każdy z nich posiada własny przewodnik: Agenci AI, Punkty wejścia oraz Transmisje.

Czytanie tej dokumentacji w formacie Markdown #

Każda strona w tej dokumentacji posiada swój odpowiednik w czystym formacie Markdown: wystarczy wziąć adres strony i dodać na końcu /index.md. Ta strona jest więc również dostępna pod adresem https://docs.youraiconnector.com/api/getting-started/index.md i zwraca czysty tekst zamiast strony internetowej — jest to przydatne, gdy chcesz wkleić stronę do asystenta AI lub pobrać ją za pomocą skryptu.

Aby przejrzeć cały zestaw, zacznij od https://docs.youraiconnector.com/sitemap.xml, gdzie znajduje się lista wszystkich publikowanych przez nas stron. Pamiętaj, że dokumentacja jest celowo ukryta przed wyszukiwarkami, więc bezpośrednie pobieranie tych adresów jest najlepszym sposobem na uzyskanie do niej dostępu z poziomu kodu.

Nie istnieje jeszcze żaden punkt końcowy dokumentacji chroniony kluczem ani możliwość pobrania zbiorczego — odpowiedniki w formacie Markdown oraz mapa witryny stanowią cały interfejs i żaden z nich nie wymaga klucza API.

Następne kroki #

• Uwierzytelnianie — wybierz odpowiednią metodę uwierzytelniania dla swojej integracji.
• Błędy i stronicowanie — obsługuj błędy i przeglądaj wyniki strona po stronie.
• Dostęp do API — wygeneruj swój klucz i zobacz przykłady działania.