Dostęp do API #

API (Application Programming Interface) to sposób, w jaki różne systemy oprogramowania mogą się ze sobą komunikować. API Your AI Connector pozwala Tobie (lub Twojemu programiście) automatycznie tworzyć kontakty, wysyłać wiadomości, zarządzać listami i odbierać przychodzące wiadomości z niestandardowych kanałów — wszystko to bez korzystania z panelu nawigacyjnego.

Dlaczego warto korzystać z API? Jeśli chcesz połączyć aplikację z narzędziem, które nie posiada wbudowanej integracji, lub musisz zautomatyzować powtarzalne zadania na dużą skalę, API jest najlepszym rozwiązaniem.

Generowanie klucza API #

1. W lewym pasku bocznym kliknij Ustawienia (ikona koła zębatego).
2. W pasku bocznym Ustawień, w grupie Integracje, kliknij Klucz API.

3. Jeśli nie masz jeszcze klucza, kliknij Wygeneruj klucz API.
4. Jeśli już go masz, jest on wyświetlany w formie zamaskowanej w sekcji Twój klucz. Jeśli Twój klucz na to pozwala, kliknij Pokaż, aby go odkryć, a następnie Kopiuj, aby go skopiować — zobaczysz komunikat potwierdzający.
5. Przechowuj klucz w bezpiecznym miejscu — będzie potrzebny do każdego żądania API.

Członkowie zespołu: klucz API należy do właściciela konta, więc jeśli jesteś zalogowany jako zaproszony członek zespołu (w tym administrator), w sekcji zamiast klucza wyświetli się stosowna informacja. Zaloguj się jako właściciel konta, aby wyświetlić, skopiować lub wygenerować go ponownie — dotyczy to również kluczy o ograniczonym zakresie.

Gdzie go znaleźć: Klucz API to osobna sekcja w Ustawienia → Integracje, oddzielona od Webhooków. Jeśli przewodnik lub współpracownik sugeruje szukanie klucza w sekcji “Webhooki”, sprawdź sekcję obok.

Klucze o ograniczonym zakresie: dodatkowe klucze do konkretnych zadań #

Twój główny klucz posiada pełne uprawnienia, dlatego nie należy go udostępniać raportom, pulpitom nawigacyjnym klientów ani oddzielnym środowiskom testowym czy programistycznym. W tym celu utwórz klucze o ograniczonym zakresie w karcie Klucze o ograniczonym zakresie, znajdującej się w tej samej sekcji Klucz API poniżej sekcji Twój klucz:

1. Kliknij Nowy klucz.
2. Nadaj mu Nazwę, którą łatwo rozpoznasz później, na przykład „Sandbox” lub „Pulpit klienta Acme”.
3. W sekcji Co może zobaczyć, zaznacz tylko te obszary, do których klucz potrzebuje dostępu.
4. W sekcji Co może zrobić, pozostaw opcję Tylko do odczytu, chyba że narzędzie musi wprowadzać zmiany. Klucz z uprawnieniami do wprowadzania zmian może wysyłać wiadomości i edytować Twoją konfigurację.
5. Opcjonalnie ustaw Żądania na minutę (własny limit, dzięki któremu klucz nigdy nie spowolni innych integracji) oraz datę Wygasa w dniu.
6. Kliknij Utwórz klucz i od razu go skopiuj. Klucze o ograniczonym zakresie są wyświetlane tylko raz; jeśli go zgubisz, unieważnij go i utwórz nowy.

Możesz utworzyć dowolną liczbę kluczy. Każdy klucz na liście pokazuje datę ostatniego użycia, a przycisk Unieważnij klucz natychmiast zatrzymuje jego działanie. Tworzenie lub unieważnianie klucza o ograniczonym zakresie nigdy nie wpływa na Twój główny klucz. Pełne opcje, w tym klucze ograniczone do konkretnych subkont, znajdują się na stronie kluczy API w dokumentacji API.

Podstawowy adres URL #

Wszystkie żądania API korzystają z następującego podstawowego adresu internetowego:

https://api.youraiconnector.com/v1/

Uwierzytelnianie #

Każde żądanie musi zawierać Twój klucz API, aby platforma wiedziała, że to Ty. Najprostszym sposobem jest dodanie go na końcu adresu internetowego:

https://api.youraiconnector.com/v1/contacts?apiKey=YOUR_API_KEY

Klucz możesz również wysłać w nagłówku żądania zamiast w adresie URL (zalecane w środowisku produkcyjnym, aby klucz nie trafiał do logów serwera):

X-API-Key: YOUR_API_KEY

Authorization: Bearer YOUR_API_KEY

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

Szukasz pełnych przewodników dla programistów? Ta strona to szybkie wprowadzenie obejmujące najczęstsze operacje. Pełne przewodniki krok po kroku — dotyczące każdego zasobu, z przykładami w cURL, JavaScript i Python — znajdziesz w sekcji Rozpoczęcie pracy z API oraz w Dokumentacji API.

Typowe operacje API #

Tworzenie kontaktu #

Żądanie:

POST https://api.youraiconnector.com/v1/contacts?apiKey=YOUR_API_KEY
Content-Type: application/json

{
  "firstName": "Jane",
  "lastName": "Smith",
  "phoneNumber": "+15551234567",
  "email": "jane@example.com"
}

Wymagane pola: phoneNumber (wraz z kodem kraju) jest zawsze wymagany do utworzenia kontaktu. Sam adres e-mail nie wystarczy — żądanie bez prawidłowego numeru telefonu zostanie odrzucone. Adres e-mail jest opcjonalny.

Odpowiedź:

{
  "success": true,
  "data": {
    "message": "Successfully created new contact",
    "contactId": "abc123xyz",
    "listsAdded": []
  }
}

Zapisz data.contactId — będzie Ci potrzebny do wywołania „Dodawanie kontaktu do listy”.

Dodawanie kontaktu do listy #

POST https://api.youraiconnector.com/v1/contacts/lists?apiKey=YOUR_API_KEY
Content-Type: application/json

{
  "contactId": "abc123xyz",
  "listId": "YOUR_LIST_ID"
}

Identyfikator listy znajdziesz w aplikacji w sekcji Kontakty → Listy, w menu wiersza danej listy (Kopiuj ID listy).

Aktualizacja kontaktu #

PUT https://api.youraiconnector.com/v1/contacts/YOUR_CONTACT_ID?apiKey=YOUR_API_KEY
Content-Type: application/json

{
  "customFields": { "company": "Acme Inc" }
}

Zmieniane są tylko uwzględnione pola. Jest to również sposób na masowe ładowanie wartości pól niestandardowych po imporcie — zobacz Pola niestandardowe, profil leada i notatki. Pełne szczegóły znajdują się w API kontaktów.

Wyślij wiadomość (kanał niestandardowy) #

POST https://api.youraiconnector.com/v1/send_custom_channel_message?apiKey=YOUR_API_KEY
Content-Type: application/json

{
  "customData": {
    "fromId": "external-contact-id",
    "customChannel": "my-channel",
    "body": "Hello Jane! Your order has been shipped.",
    "campaignId": "optional-campaign-id",
    "firstName": "Jane",
    "lastName": "Smith"
  }
}

Odbieranie wiadomości przychodzących (kanał niestandardowy) #

Odbieraj wiadomości z zewnętrznych systemów jako niestandardowy kanał. W ten sposób integracje takie jak GoHighLevel wysyłają wiadomości do Your AI Connector. Zobacz Kanały niestandardowe, aby uzyskać pełne szczegóły.

POST https://api.youraiconnector.com/v1/incoming_custom_channel_message?apiKey=YOUR_API_KEY
Content-Type: application/json

{
  "customData": {
    "messageSid": "unique-message-id",
    "fromId": "external-contact-id",
    "toId": "your-user-id",
    "body": "Customer's message here",
    "channel": "custom",
    "status": "received"
  },
  "messageType": "text"
}

Przegląd dostępnych operacji #

Limity szybkości (Rate Limiting) #

API wymusza limity szybkości, aby zapewnić stabilność platformy. Przekroczenie limitu skutkuje zwróceniem 429 Too Many Requests — należy wstrzymać się z zapytaniami i ponowić próbę po czasie wskazanym w nagłówkach odpowiedzi. W przypadku dużej liczby operacji (importy masowe) należy skorzystać z wbudowanej funkcji importu lub napisać na adres hi@youraiconnector.com, aby uzyskać wskazówki.

Dobre praktyki #

• Przechowuj swój klucz API bezpiecznie — w menedżerze haseł lub konfiguracji po stronie serwera, nigdy w kodzie po stronie klienta, który mógłby odczytać użytkownik przeglądarki.
• Zawsze podawaj kod kraju w numerach telefonów (+1 dla USA, +44 dla Wielkiej Brytanii, +31 dla Holandii).
• Obsługuj błędy w sposób elegancki — sprawdzaj kody statusu i czytaj wszystkie zwrócone komunikaty o błędach.
• Obsługuj duplikaty — zduplikowany numer telefonu zwraca { "success": false, "error_code": 409 } zamiast nowego kontaktu, z identyfikatorem istniejącego kontaktu w contactId.
• Testuj na małym zbiorze danych przed uruchomieniem operacji masowych.

Odpowiedzi o błędach #

{
  "error": {
    "code": "INVALID_PHONE",
    "message": "Phone number must include a valid country code."
  }
}

Następne kroki #

• Webhooks — otrzymuj powiadomienia w czasie rzeczywistym z aplikacji (osobna sekcja od Twojego klucza API).
• Połącz asystentów AI (MCP) — użyj tego samego klucza API, aby pozwolić Claude zarządzać Twoim kontem.
• Formularze kontaktowe Facebooka — używaj API z platformami automatyzacji do pozyskiwania leadów.
• Integracja z GoHighLevel — przykład pełnej dwukierunkowej integracji API.