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

Zakresy i minimalne uprawnienia

Każdy klucz jest ograniczony do wybranych zakresów. Gdy to możliwe, używaj kluczy tylko do odczytu i osobnego klucza dla każdej integracji. Zakres zapisu nie przyznaje automatycznie odpowiadającego mu zakresu odczytu.

assistants:read
assistants:write
analytics:read
artifacts:read
artifacts:write
billing:read
bookings:read
bookings:write
chat:write
connectors:read
connectors:write
conversations:read
conversations:write
knowledge:read
knowledge:write
leads:read
leads:write
telephony:read
telephony:write
widget:write

API-key rate limit

Each developer key is limited to 300 requests per rolling minute by default. The limit is atomic across all application instances and can be changed by the platform with API_KEY_RATE_LIMIT_PER_MINUTE. A rejected request returns 429; retry only after the window resets.

Lista asystentów

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

Utwórz Asystenta

POST /api/assistants

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

DELETE /api/assistants/:id

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

Creation validation and quota safety

Creation allowance is reserved atomically before insertion, so concurrent requests cannot exceed the monthly quota. Database insertion failures refund that reservation. A created assistant starts inactive in developer mode; call the setup endpoint and wait for its successful terminal event before publishing it.

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: {}.

Upload, crawl, and index consistency

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

Send only the fields you want to change. The API rejects unknown keys and invalid nested data instead of silently storing configuration the widget cannot use.

{
  "designPreset": "corporate-soft",
  "primaryColor": "#1972F5",
  "theme": "dark",
  "bubbleStyle": "branded-drawer",
  "bubbleText": "Talk to our team",
  "welcomeMessages": [
    {
      "text": "Hello! How can I help?",
      "delay": 1.5
    }
  ],
  "welcomeSuggestions": [
    "View pricing",
    "Book a demo"
  ],
  "pageVisibility": {
    "mode": "exclude",
    "paths": [
      "/checkout/*"
    ]
  },
  "voiceEnabled": true,
  "voiceName": "Aoede",
  "copilotEnabled": true,
  "gdprConsentEnabled": true,
  "privacyPolicyUrl": "https://example.com/privacy"
}

Page visibility matching

Use exact paths such as /pricing, or append /* to include descendants such as /docs/*. include shows only matches; exclude hides matches; all ignores paths. Full URLs are normalized to their pathname by the widget.

Available voice names

Zephyr, Aoede, Kore, Leda, Callirrhoe, Despina, Erinome, Laomedeia, Achernar, Pulcherrima, Gacrux, Algenib, Sulafat, Puck, Charon, Fenrir, Orus, Enceladus, Iapetus, Umbriel, Algieba, Autonoe, Rasalgethi, Alnilam, Schedar, Sadachbia, Achird, Zubenelgenubi, Sadaltager

GET /api/assistants/:id/artifacts · PUT /api/assistants/:id/artifacts · PATCH /api/assistants/:id/artifacts

Artifacts are tool-driven UI. The model calls the enabled tool and Chirps renders it; integrations must send configuration JSON, never {{ARTIFACT: ...}} strings.

{
  "form": {
    "enabled": true,
    "title": "Request a quote",
    "description": "Collect the details needed for a quote.",
    "triggerRules": "When a visitor explicitly asks for a quote.",
    "fields": [
      {
        "key": "name",
        "label": "Full name",
        "type": "text",
        "required": true,
        "placeholder": "Jane Doe"
      },
      {
        "key": "email",
        "label": "Work email",
        "type": "email",
        "required": true
      }
    ],
    "submitLabel": "Request quote"
  },
  "booking": {
    "enabled": true,
    "title": "Book a consultation",
    "description": "Choose an available time.",
    "triggerRules": "When a visitor asks to book a meeting.",
    "services_enabled": false,
    "meetings_enabled": true,
    "requiresScheduling": true,
    "timezone": "Europe/Paris",
    "slotDuration": 30,
    "bufferMinutes": 10,
    "workingHours": {
      "monday": {
        "enabled": true,
        "start": "09:00",
        "end": "17:00"
      },
      "tuesday": {
        "enabled": true,
        "start": "09:00",
        "end": "17:00"
      },
      "wednesday": {
        "enabled": true,
        "start": "09:00",
        "end": "17:00"
      },
      "thursday": {
        "enabled": true,
        "start": "09:00",
        "end": "17:00"
      },
      "friday": {
        "enabled": true,
        "start": "09:00",
        "end": "17:00"
      },
      "saturday": {
        "enabled": false,
        "start": "10:00",
        "end": "14:00"
      },
      "sunday": {
        "enabled": false,
        "start": "10:00",
        "end": "14:00"
      }
    },
    "blockedDates": [
      "2026-12-25"
    ],
    "meeting_intake_fields": [
      {
        "key": "email",
        "label": "Email",
        "type": "email",
        "required": true
      }
    ],
    "submitLabel": "Book meeting"
  },
  "card": {
    "enabled": false,
    "ctaLabel": "View details",
    "ctaUrl": "",
    "description": "",
    "triggerRules": ""
  },
  "csat_survey": {
    "enabled": true,
    "title": "How was your experience?",
    "description": "One-click feedback.",
    "triggerRules": "Only after the request is resolved."
  },
  "custom": []
}

Field schema

Booking service schema

Validation limits and scheduling rules

Tool-call prefill behavior

Start with GET /api/marketplace/connectors. Its provider definitions are the source of truth for credential fields, configuration fields, available tools, defaults, and required values; this keeps custom and future providers discoverable without a documentation release.

{
  "provider": "shopify",
  "name": "Shopify",
  "credentials": {}
}

1. Install the workspace connector record with POST /api/assistants/:id/connectors; credentials must be omitted or {}.
2. Read its exact field schema from GET /api/marketplace/connectors and activate it with POST /api/assistants/:id/connectors/:connectorId/activate.
3. Send configValues, optional enabledTools, and optional instructions. Chirps verifies non-custom connectors and discovers the tools before saving the integration.
4. Rotate secrets by calling the activation endpoint again. PUT only renames a named Custom API.
5. Use DELETE /api/assistants/:id/connectors with { connectorId } to disable it for one assistant. Use the nested DELETE .../:connectorId only to permanently remove it from the workspace and every assistant.

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>
  window.chirpsConfig = { assistantId: "YOUR_ASSISTANT_ID" };
</script>
<script src="https://chirps.cc/embed.js" async></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

Ważne: wywołania headless i serwer-serwer muszą zawierać Authorization: Bearer <YOUR_CHIRPS_API_KEY>. Tylko zainstalowany widżet przeglądarkowy korzysta z publicznego przepływu powiązanego z origin. Nigdy nie umieszczaj klucza API w kodzie JavaScript frontendu.

{

  "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": "chunk"}. Wywoływany dla każdego fragmentu tekstu odpowiedzi AI.
• `event: status`: Zawiera {"text": "Searching knowledge base..."}. Reprezentuje stany wykonania narzędzia zaplecza.
• `event: done`: Zawiera {"messageId": "uuid", "conversationId": "uuid", "message": "full text"}. Wywoływany po całkowitym zakończeniu generowania.
• `event: error`: Zawiera {"error": "Error message"}. Uruchamiany w przypadku wystąpienia ograniczeń szybkości lub błędów.

Punkty końcowe przejęcia na żywo

GET /api/chat/sessions

Pobierz sesje historyczne.

POST /api/chat/toggle-agent

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

POST /api/chat/agent-messageść-agenta

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

Complete chat response contract

{
  "message": "I've opened the booking calendar for you.",
  "messageId": "uuid",
  "conversationId": "uuid",
  "artifacts": [
    {
      "type": "booking",
      "title": "Book a consultation"
    }
  ],
  "sources": []
}

A human takeover returns { message: null, conversationId, is_active_agent: true }. A streaming request can therefore return JSON before an SSE stream begins; check the response Content-Type.

Complete SSE event reference

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

DELETE /api/assistants/: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/:subscriptionId/assign assigns an already-purchased Chirps phone subscription to an assistant. Send { "assistantId": "uuid" }; send { "assistantId": null } to unassign it. This endpoint does not purchase or provision a new number.

POST /api/assistants/:id/outbound - Uruchom połączenie wychodzące. Ładunek: { "phoneNumber": "+123...", "callReason": "Confirm the requested appointment", "conversationId": "optional-uuid" }

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

Public lead response

Lead objects contain id, assistant_id, conversation_id, session_id, name, email, phone, status, notes, artifact_id, ai_score, ai_summary, form_data, created_at, and the assistant business name. Internal voice-confirmation/idempotency identifiers are never returned.

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

DELETE /api/bookings/cancel?id=bookingId - Anuluje aktywną rezerwację. Dodaj &silent=true tylko wtedy, gdy integracja celowo ma wyłączyć zapasową wiadomość e-mail o anulowaniu z Chirps.

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

Public booking response and time zones

Booking objects contain the public appointment, guest, status, notes, and timestamp fields plus business_timezone. Times are ISO-8601 instants; format them in the viewer's time zone while preserving the returned business zone for schedule context. Internal confirmation IDs, provider calendar-event IDs, and database range columns are omitted.

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

What belongs in the public developer API

These routes accept a scoped Chirps API key and enforce its workspace boundary. Dashboard-only billing/OAuth routes, browser widget callbacks, provider webhooks, cron jobs, and internal MCP routes are intentionally excluded.

Assistants

Knowledge and training

Widget, artifacts and connectors

Conversations, leads and bookings

Telephony and account