Полное руководство по API для разработчиков

Для всех конечных точек API требуется ключ API Chirps в заголовке Authorization. Вы можете сгенерировать ключ API в диспетчере API в [разделе «Разработчики» на панели управления] (https://chirps.cc/dashboard/developers).

Authorization: Bearer <YOUR_CHIRPS_API_KEY>

Пример запроса:

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

Стандартная обработка ошибок

Области доступа и минимальные привилегии

Каждый ключ ограничен выбранными областями доступа. По возможности используйте ключи только для чтения и отдельный ключ для каждой интеграции. Область записи не предоставляет соответствующую область чтения автоматически.

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.

Список помощников

Получает список всех помощников, связанных с рабочей областью ключа API.

Создать помощника

POST /api/assistants

Создает нового помощника со всеми базовыми конфигурациями.

{

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

Удалить помощника

DELETE /api/assistants/:id

Безвозвратно удаляет помощника и каскадно удаляет все его узлы знаний и историю. Полезная нагрузка не требуется.

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

Получите статистику использования, общее количество сообщений, привлеченных потенциальных клиентов и общие показатели вовлеченности для указанного помощника. Параметр range является необязательным (количество дней, минимум 7, максимум 365, по умолчанию 30).

Ожидаемый ответ

{

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

Управление узлами знаний

GET /api/assistants/:id/nodes — список всех узлов знаний для этого помощника.

POST /api/assistants/:id/nodes – вручную добавить новый блок знаний.

{

  "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 — изменение содержимого существующего узла или переключение его активного состояния.

{

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

DELETE /api/assistants/:id/nodes/:nodeId — полностью удалить блок знаний.

POST /api/assistants/:id/nodes/:nodeId/re-crawl — заставить парсер повторно сканировать URL-адрес, связанный с этим узлом, и обновить его содержимое. Полезная нагрузка: {}.

Обучение искусственному интеллекту

POST /api/assistants/:id/train — скомпилируйте все узлы знаний is_active и используйте оркестратор ИИ для динамического синтеза нового приглашения главной системы. Полезная нагрузка: {}.

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.

Вариант А: веб-встраивание (интерфейс)

Самый простой способ интегрировать помощника в стандартный сайт (WordPress, Shopify, React и т. д.). Код для внедрения является чисто детерминированным. Вам не нужна конечная точка для его получения. Просто добавьте это в <head> вашего сайта:

<script>
  window.chirpsConfig = { assistantId: "YOUR_ASSISTANT_ID" };
</script>
<script src="https://chirps.cc/embed.js" async></script>

Вариант Б: Безголовая интеграция (бэкэнд/CRM/боты)

Если вы создаете собственный клиент (например, бот Discord, интеграцию Telegram или собственное приложение для iOS), вы НЕ будете использовать Web Embed. Вместо этого вы будете напрямую взаимодействовать с конечной точкой /api/chat.

POST /api/chat или /api/chat?stream=true

Важно: headless-вызовы и запросы между серверами должны содержать Authorization: Bearer <YOUR_CHIRPS_API_KEY>. Только установленный браузерный виджет использует публичный поток с проверкой origin. Никогда не помещайте API-ключ во фронтенд JavaScript.

{

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

*(Также поддерживается multipart/form-data с полем file для вложений, если fileUploadEnabled имеет значение true).*

Режим 1: стандартный ответ JSON (по умолчанию)

Отправляя запрос POST в /api/chat (без параметра потока), вы ожидаете полного ответа AI и получаете стандартный объект JSON.

{

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

*(Если возвращается is_active_agent: true, управление чатом взял на себя человек, а message будет null.)*

Режим 2: потоковая передача событий, отправленных сервером (?stream=true)

Добавляя ?stream=true к URL-адресу, вы получаете поток событий, отправленных сервером (SSE) в реальном времени. Ваш код должен прослушивать следующие типы событий:

• `event: token`: Содержит {"text": "chunk"}. Запускается для каждого фрагмента текста ответа ИИ.
• `event: status`: Содержит {"text": "Searching knowledge base..."}. Представляет состояния выполнения серверного инструмента.
• `event: done`: Содержит {"messageId": "uuid", "conversationId": "uuid", "message": "full text"}. Запускается, когда генерация полностью завершена.
• `event: error`: Содержит {"error": "Error message"}. Вызывается при возникновении ограничений скорости или ошибок.

Конечные точки оперативного поглощения

GET /api/chat/sessions

Получить исторические сеансы.

POST /api/chat/toggle-agent

Приостановите ИИ для захвата человеком. Полезная нагрузка: { "sessionId": "...", "isActive": true }

POST /api/chat/agent-message

Отправьте человеческое сообщение. Полезная нагрузка: { "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

Обновить базовую конфигурацию

Измените основные настройки, личность и границы очистки помощника.

{

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

*Примечание: Все поля являются необязательными. Отправляйте только те поля, которые хотите обновить.*

Удалить помощника

DELETE /api/assistants/:id

Безвозвратно удаляет помощника и каскадно удаляет все узлы знаний, беседы и сообщения. Если помощник так и не был настроен полностью, будет возмещена ежемесячная квота создания.

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 – инициировать исходящий вызов. Полезная нагрузка: { "phoneNumber": "+123...", "callReason": "Confirm the requested appointment", "conversationId": "optional-uuid" }

GET /api/leads?id=leadId — получение подробной информации об одном интересе, включая полную стенограмму разговора.

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 — получение сведений об одном бронировании, включая стенограмму разговора.

DELETE /api/bookings/cancel?id=bookingId - Отменяет активное бронирование. Добавляйте &silent=true только если интеграция намеренно отключает резервное письмо Chirps об отмене.

POST /api/bookings/reschedule — корректировка бронирования. Полезная нагрузка: { "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.

Получите информацию об использовании платежного цикла рабочей области, ограничениях плана подписки и общем количестве помощников. Примечание. При использовании ключа API запрос автоматически ограничивается рабочей областью ключа API; вам не нужно указывать «teamId».

Ответ («200 ОК»):

{

  "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