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.

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) #

The API enforces rate limits to ensure platform stability. Exceeding your limit returns 429 Too Many Requests — back off and retry after the time indicated in the response headers. For high-volume use cases (bulk imports), use the built-in import feature or email hi@youraiconnector.com for guidance.

Dobre praktyki #

• Przechowuj klucz API bezpiecznie — używaj menedżera haseł lub konfiguracji po stronie serwera, nigdy kodu po stronie klienta, który mógłby odczytać odwiedzający stronę.
• 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 wszelkie zwracane komunikaty o błędach.
• Obsługuj duplikaty — zduplikowany numer telefonu zwróci { "success": false, "error_code": 409 } zamiast nowego kontaktu. Jeśli musisz pracować z tym kontaktem, najpierw go wyszukaj.
• Przetestuj 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.