# Wprowadzenie do API REST API DM Champ 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 DM Champ 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ę. ::: note **Uwaga:** Te strony są przeznaczone dla programistów. Jeśli nie jesteś programistą, udostępnij tę sekcję swojemu zespołowi technicznemu. ::: --- ## 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.dmchamp.com/v1 ``` Zatem punkt końcowy AI Agents to `https://api.dmchamp.com/v1/agents`, punkt końcowy kontaktów to `https://api.dmchamp.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ą: ```json { "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](../integrations/api-access.md) — 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. | Metoda | Jak | Najlepsze dla | |---|---|---| | Parametr zapytania | `?apiKey=YOUR_API_KEY` | Szybkie testy, adresy URL w przeglądarce, starsze konfiguracje | | Nagłówek | `X-API-Key: YOUR_API_KEY` | Integracje produkcyjne | | Nagłówek Bearer | `Authorization: Bearer YOUR_API_KEY` | Integracje produkcyjne | | Token ID Firebase | `Authorization: Bearer ` | Tylko sesje aplikacji własnych | 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](authentication.md), 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ę agentów AI na Twoim koncie. Używa ono Twojego klucza API i zwraca krótki wiersz dla każdego agenta, zaczynając od najnowszego. **cURL** ```bash curl "https://api.dmchamp.com/v1/agents?apiKey=YOUR_API_KEY&view=summary" ``` **JavaScript** ```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** ```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"]) ``` Poprawna odpowiedź wygląda następująco: ```json { "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.): ```json { "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: ```json { "success": false, "error": "Invalid cursor", "error_code": 400 } ``` Zawsze sprawdzaj `success` (lub status HTTP) przed odczytaniem danych. Zobacz [Błędy i stronicowanie](errors-and-pagination.md), 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. ::: master-only Agencje: to druga liczba jest tą, którą należy brać pod uwagę przy planowaniu. Żądania wykonywane za pomocą klucza agencji są wliczane do limitu konta agencji, nawet jeśli dotyczą subkonta z `sub_account_id`, więc nagły wzrost liczby zapytań dla wielu klientów korzysta z jednego budżetu. Jeśli klient potrzebuje własnego budżetu, użyj klucza API tego subkonta. ::: Jeśli przekroczysz którykolwiek z limitów, otrzymasz odpowiedź `429`: ```json { "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.dmchamp.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](api-keys.md). --- ## Przewodniki po zasobach Poniższe grupy zasobów mają własne przewodniki z dokładnymi ścieżkami, polami żądań i strukturami odpowiedzi. | Zasób | Co obejmuje | |---|---| | [Agenci AI](agents.md) | Tworzenie i konfigurowanie agentów AI: ustawienia, godziny aktywności, wiedza, reguły tagowania, narzędzia, multimedia i szkice | | [Punkty wejścia](entry-points.md) | Decydowanie, który agent AI odpowiada na nową konwersację: domyślne ustawienia kanałów, jeden agent na numer WhatsApp, słowa kluczowe, reguły komentarzy i obserwujących | | [Transmisje](broadcasts.md) | Tworzenie, wycenianie, uruchamianie, wstrzymywanie i duplikowanie jednorazowych wysyłek do listy kontaktów | | [Kampanie](campaigns.md) | Tworzenie, aktualizowanie, duplikowanie, włączanie, archiwizowanie i sprawdzanie kampanii oraz ich konfiguracji bota | | [Kontakty](contacts.md) | Tworzenie, wyszukiwanie, wyświetlanie, aktualizowanie, importowanie, tagowanie i usuwanie kontaktów | | [FAQ](faqs.md) | Zarządzanie wpisami pytań i odpowiedzi używanymi przez asystenta AI oraz łączenie ich z kampaniami | | [Baza wiedzy](knowledge-base.md) | Importowanie stron internetowych i dokumentów do wiedzy AI oraz grupowanie FAQ w zestawy | | [Zadania](tasks.md) | Tworzenie i zarządzanie zadaniami CRM, etapami tablicy i typami zadań | | [Wiadomości](messages.md) | Wysyłanie wiadomości wychodzących i odczytywanie historii konwersacji | | [Spotkania](appointments.md) | Rezerwowanie, zmienianie terminu, anulowanie i usuwanie spotkań | | [Kanały](channels.md) | Łączenie i rozłączanie kanałów komunikacji, kupowanie numerów oraz ustawianie, który agent AI odpowiada na nowe konwersacje w każdym kanale | | [Szablony](templates.md) | Tworzenie, przesyłanie i sprawdzanie statusu zatwierdzenia szablonów wiadomości WhatsApp | | [Analityka](analytics.md) | Odczytywanie dziennych statystyk zdarzeń wiadomości, zużycia kredytów i podsumowań kosztów AI | | [Webhooki](webhooks.md) | Rejestrowanie punktów końcowych w celu otrzymywania powiadomień o zdarzeniach w czasie rzeczywistym | | [Zespół](team.md) | Zarządzanie członkami zespołu, zaproszeniami, rolami, uprawnieniami i działami | | [Klucze API](api-keys.md) | Sprawdzanie, rotowanie i unieważnianie klucza API, sprawdzanie wykorzystania limitów oraz tworzenie dodatkowych kluczy z ograniczonym dostępem | ### 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](reference.md). Każdy z nich posiada własny przewodnik: [Agenci AI](agents.md), [Punkty wejścia](entry-points.md) oraz [Transmisje](broadcasts.md). ::: master-only Obecność w specyfikacji oznacza również, że te punkty końcowe pojawiają się jako narzędzia dla każdego asystenta AI, którego [połączysz przez MCP](../integrations/connect-ai-clients.md). ::: --- ## 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.dmchamp.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. Dla asystenta AI lub skryptu, który powinien odczytać cały zestaw, dostępne są dwa gotowe pliki: - `https://docs.dmchamp.com/llms.txt` — indeks: każda strona z podsumowaniem w jednym wierszu i linkiem do jej odpowiednika w formacie Markdown, pogrupowane tak samo jak na pasku bocznym. - `https://docs.dmchamp.com/llms-full.txt` — cała dokumentacja w jednym pliku Markdown. Każda strona zaczyna się od tytułu i wiersza `Source:` zawierającego adres strony, dzięki czemu asystent może zacytować źródło odpowiedzi. Oba pliki istnieją również dla każdego języka, pod prefiksem językowym (`https://docs.dmchamp.com/nl/llms.txt`, `https://docs.dmchamp.com/es/llms-full.txt` itd.). Podaj asystentowi adres `llms.txt`, a pobierze on potrzebne strony, lub przekaż mu `llms-full.txt`, gdy powinien mieć wszystko w kontekście jednocześnie. Są one przebudowywane przy każdej zmianie w dokumentacji, więc nigdy nie tracą aktualności. Jeśli wolisz samodzielnie przeglądać strony, `https://docs.dmchamp.com/sitemap.xml` zawiera listę wszystkich publikowanych przez nas stron. Dokumentacja jest celowo ukryta przed wyszukiwarkami, więc bezpośrednie pobieranie tych adresów jest sposobem na dotarcie do niej z poziomu kodu. Nic z tego nie wymaga klucza API: odpowiedniki w formacie Markdown, dwa pliki `llms` oraz mapa witryny stanowią cały interfejs. --- ## Następne kroki - [Uwierzytelnianie](authentication.md) — wybierz odpowiednią metodę uwierzytelniania dla swojej integracji. - [Błędy i stronicowanie](errors-and-pagination.md) — obsługuj błędy i przeglądaj wyniki strona po stronie. - [Dostęp do API](../integrations/api-access.md) — wygeneruj swój klucz i zobacz przykłady działania.