Najlepszy przewodnik po API dla programistów

Wszystkie punkty końcowe API wymagają klucza API Chirps w nagłówku „Authorization”. Możesz wygenerować klucz API z Menedżera API w sekcji dla programistów na pulpicie nawigacyjnym.

Authorization: Bearer <YOUR_CHIRPS_API_KEY>

Przykładowe żądanie:

curl -X GET https://chirps.cc/api/billing/usage \
  -H "Authorization: Bearer <YOUR_CHIRPS_API_KEY>" \
  -H "Content-Type: application/json"

Standardowa obsługa błędów

Lista asystentów

Pobiera listę wszystkich asystentów powiązanych z obszarem roboczym klucza API.

Utwórz Asystenta

POST /api/asystenci

Tworzy nowego asystenta ze wszystkimi konfiguracjami podstawowymi.

{

  "businessName": "Acme Corp",
  "businessUrl": "https://acme.com",
  "knowledgeBaseType": "both",
  "knowledgeBaseUrl": "https://acme.com/help",
  "knowledgeBaseText": "Raw text content of a document...",
  "knowledgeBaseFileName": "company_handbook.pdf",
  "language": "en",
  "isMultiLanguage": false,
  "tonePersonality": "professional",
  "isCustomPersonality": false,
  "supportEmail": "[email protected]",
  "maxPages": 5,
  "maxDepth": 2,
  "welcomeMessageDelay": 2
}

Usuń Asystenta

USUŃ /api/asystenci/:id

Trwale usuwa asystenta i kaskadowo usuwa wszystkie jego węzły wiedzy i historię. Nie jest wymagany żaden ładunek.

GET /api/analytics/overview?assistantId=uuid&range=30

Pobierz statystyki użytkowania, całkowitą liczbę wiadomości, przechwyconych potencjalnych klientów i ogólne wskaźniki zaangażowania dla określonego asystenta. Parametr „zakres” jest opcjonalny (liczba dni, min. 7, maks. 365, domyślnie 30).

Oczekiwana odpowiedź

{

  "totalConversations": 1245,
  "totalMessages": 8420,
  "totalLeads": 156,
  "totalBookings": 42,
  "satisfactionRate": 94,
  "avgMessagesPerSession": 6.7,
  "avgSessionsPerDay": 41.5,
  "liveNow": 3,
  "onlineNow": 12,
  "dailySeries": [
    {
      "date": "2026-07-15",
      "conversations": 45,
      "messages": 310,
      "leads": 5,
      "bookings": 2
    }
  ],
  "agentStats": [
    {
      "name": "Jane Doe",
      "messagesSent": 120,
      "csat": 98
    }
  ]
}

Zarządzanie węzłami wiedzy

GET /api/assistants/:id/nodes - Lista wszystkich węzłów wiedzy dla tego asystenta.

POST /api/assistants/:id/nodes - Ręcznie wstrzyknij nowy blok wiedzy.

{

  "title": "Return Policy",
  "refined_content": "We offer a 30-day return policy for all unused items...",
  "type": "text",
  "metadata": {}
}

PATCH /api/assistants/:id/nodes/:nodeId - Zmodyfikuj zawartość istniejącego węzła lub przełącz jego stan aktywny.

{

  "title": "Updated Return Policy",
  "refined_content": "We offer a 60-day return policy now...",
  "is_active": true
}

DELETE /api/assistants/:id/nodes/:nodeId - Całkowicie usuwa blok wiedzy.

POST /api/assistants/:id/nodes/:nodeId/re-crawl - Zmusza skrobak do ponownego przeszukania adresu URL powiązanego z tym węzłem i zaktualizowania jego zawartości. Ładunek: {}.

Szkolenie AI

POST /api/assistants/:id/train - Skompiluj wszystkie węzły wiedzy is_active i użyj orkiestratora AI do dynamicznej syntezy nowego głównego monitu systemowego. Ładunek: {}.

Zaktualizuj wygląd widgetu

PATCH /api/assistants/:id/widget-config

{

  "primaryColor": "#000000",
  "position": "bottom-right",
  "language": "en",
  "welcomeMessage": "Hi! How can I help you today?",
  "title": "Acme Support",
  "theme": "light",
  "fontFamily": "default",
  "bubbleStyle": "circle",
  "bubbleText": "Chat with us",
  "headerSubtitle": "We typically reply instantly",
  "inputPlaceholder": "Type your message...",
  "privacyPolicyUrl": "https://acme.com/privacy",
  "voiceEnabled": true,
  "voiceName": "Fenrir",
  "welcomeMessageDelay": 2,
  "fileUploadEnabled": true,
  "dictationEnabled": true,
  "copilotEnabled": true,
  "welcomeSuggestions": ["Pricing plans", "Contact sales"],
  "pageVisibility": {
    "mode": "all",
    "paths": []
  }
}

Dostępne nazwy głosów

• Samice: Zephyr, Aoede, Core, Leda, Callirrhoe, Despina, Erinome, Laomedeia, Achernar, Pulcherrima, Gacrux, Algenib, Sulfat
• Samce: Puck, Charon, Fenrir, Orus, Enceladus, Iapetus, Umbriel, Algieba, Autonoe, Rasalgethi, Alnilam

Niestandardowe logo

POST /api/assistants/:id/widget-logo

Format: multipart/form-data z polem file.

Opcja A: osadzanie w sieci Web (frontend)

Najprostszy sposób na integrację asystenta ze standardową stroną internetową (WordPress, Shopify, React itp.). Kod osadzania jest czysto deterministyczny. Aby go pobrać, nie potrzebujesz punktu końcowego. Po prostu upuść to w <head> swojej witryny:

<script src="https://chirps.cc/widget.js" data-assistant-id="YOUR_ASSISTANT_ID_HERE"></script>

Opcja B: Bezgłowe Integracje (Backend / CRM / Boty)

Jeśli tworzysz niestandardowego klienta (takiego jak bot Discord, integracja z Telegramem lub natywna aplikacja na iOS), NIE będziesz używać Web Embed. Zamiast tego będziesz mieć bezpośrednią interakcję z punktem końcowym /api/chat.

POST /api/chat lub /api/chat?stream=true

Uwaga: Ten punkt końcowy jest publiczny i *nie* wymaga nagłówka klucza API Authorization: Bearer. Uwierzytelnianie odbywa się niejawnie poprzez assistantId.

{

  "assistantId": "123e4567-e89b-12d3-a456-426614174000",
  "sessionId": "unique-session-id-for-user",
  "conversationId": "optional-uuid",
  "message": "Hello, I need help with my billing."
}

*(Obsługuje również multipart/form-data z polem file dla załączników, jeśli fileUploadEnabled ma wartość true).*

Tryb 1: Standardowa odpowiedź JSON (domyślnie)

Wysyłając żądanie POST do /api/chat (bez parametru stream), czekasz na pełną odpowiedź AI i otrzymujesz standardowy obiekt JSON.

{

  "message": "Here is the information you requested...",
  "conversationId": "uuid-of-conversation",
  "messageId": "uuid-of-message"
}

*(Jeśli zostanie zwrócone is_active_agent: true, oznacza to, że czat przejął człowiek, a message będzie miało wartość null.)*

Tryb 2: Przesyłanie strumieniowe zdarzeń wysyłanych przez serwer (?stream=true)

Dodając „?stream=true” do adresu URL, otrzymujesz strumień zdarzeń wysyłanych przez serwer (SSE) w czasie rzeczywistym. Twój kod powinien nasłuchiwać tych konkretnych typów zdarzeń:

• `event: token`: Zawiera {"text": "fragment"}. Wywoływany dla każdego fragmentu tekstu odpowiedzi AI.
• `event: status`: Zawiera {"text": "Przeszukiwanie bazy wiedzy..."}. Reprezentuje stany wykonania narzędzia zaplecza.
• `event: gotowe`: Zawiera {"messageId": "uuid", "conversationId": "uuid", "message": "pełny tekst"}. Wywoływany po całkowitym zakończeniu generowania.
• `zdarzenie: błąd`: Zawiera {"błąd": "Komunikat o błędzie"}. Uruchamiany w przypadku wystąpienia ograniczeń szybkości lub błędów.

Punkty końcowe przejęcia na żywo

GET /api/czat/sesje

Pobierz sesje historyczne.

POST /api/chat/toggle-agent

Wstrzymaj sztuczną inteligencję w celu przejęcia władzy przez ludzi. Ładunek: { "sessionId": "..." }

POST /api/chat/wiadomość-agenta

Wyślij ludzką wiadomość. Ładunek: { "sessionId": "...", "message": "..." }

Zaktualizuj konfigurację rdzenia

Zmodyfikuj podstawowe ustawienia, osobowość i granice skrobania asystenta.

{

  "business_name": "Acme Corp",
  "business_url": "acme.com",
  "business_description": "We sell anvils.",
  "system_prompt": "You are a helpful assistant.",
  "language": "en",
  "tone_personality": "Friendly",
  "support_email": "[email protected]",
  "additional_instructions": "Never mention the Roadrunner.",
  "is_multi_language": true,
  "is_dev_mode": false,
  "is_active": true,
  "max_pages": 15,
  "max_depth": 2,
  "widget_config_merge": {
    "rateLimitEnabled": true
  }
}

*Uwaga: wszystkie pola są opcjonalne. Wysyłaj tylko te pola, które chcesz zaktualizować.*

Usuń Asystenta

USUŃ /api/asystenci/:id

Trwale usuwa asystenta i kaskadowo usuwa wszystkie węzły wiedzy, rozmowy i wiadomości. Jeśli asystent nigdy nie został w pełni skonfigurowany, zwracany jest miesięczny limit tworzenia.

POST /api/phone-numbers/:id/sign - Podaj numer. Ładunek: {}

POST /api/assistants/:id/outbound - Uruchom połączenie wychodzące. Ładunek: { "do": "+123...", "wiadomość": "..." }

GET /api/leads?id=leadId - Pobierz szczegóły pojedynczego leada, łącznie z pełnym zapisem rozmowy.

GET /api/bookings?id=bookingId - Pobierz szczegóły pojedynczej rezerwacji, łącznie z transkrypcją rozmowy.

POST /api/bookings/cancel - Anuluj aktywną rezerwację. Ładunek: { "bookingId": "uuid" }

POST /api/bookings/reschedule - Dostosuj rezerwację. Ładunek: { "bookingId": "uuid", "newTime": "ISO-8601" }

Pobierz wykorzystanie cyklu rozliczeniowego obszaru roboczego, limity planu subskrypcji i łączną liczbę asystentów. Uwaga: w przypadku korzystania z klucza API żądanie jest automatycznie kierowane do obszaru roboczego klucza API; nie musisz podawać teamId.

Odpowiedź („200 OK”):

{

  "planName": "Pro",
  "periodStr": "2023-10-01",
  "assistantCount": 3,
  "usage": {
    "message_count": 1450,
    "harvest_count": 12,
    "recrawl_count": 5,
    "train_count": 2,
    "assistants_created_count": 1,
    "voice_minutes_used": 0,
    "sms_count": 0,
    "email_count": 0,
    "whatsapp_count": 0
  },
  "limits": {
    "messages": 5000,
    "assistants": 5,
    "training": 50,
    "recrawls": 20
  },
  "workspaceOwnerId": "uuid"
}