Полное руководство по 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"

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

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

Получает список всех помощников, связанных с рабочей областью ключа 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

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

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 и используйте оркестратор ИИ для динамического синтеза нового приглашения главной системы. Полезная нагрузка: {}.

Обновить внешний вид виджета

ИСПРАВЛЕНИЕ /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": []
  }
}

Доступные голосовые имена

• Самки: Зефир, Аоеде, Коре, Леда, Каллирро, Деспина, Эринома, Лаомедея, Ахернар, Пульчеррима, Гакрукс, Альгениб, Сульфат.
• Мужчины: Пак, Харон, Фенрир, Орус, Энцелад, Япет, Умбриэль, Альгиеба, Аутоное, Расалгети, Альнилам

Пользовательский логотип

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

Формат: multipart/form-data с полем file.

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

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

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

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

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

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

Примечание. Эта конечная точка является общедоступной и *не* требует заголовка API-ключа Authorization: Bearer. Аутентификация осуществляется неявно через assistantId.

{

  "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": "Поиск в базе знаний..."}. Представляет состояния выполнения серверного инструмента.
• `event: Done`: Содержит {"messageId": "uuid", "conversationId": "uuid", "message": "full text"}. Запускается, когда генерация полностью завершена.
• `event: error`: Содержит {"error": "Сообщение об ошибке"}. Вызывается при возникновении ограничений скорости или ошибок.

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

GET /api/chat/sessions

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

POST /api/chat/toggle-agent

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

POST /api/chat/agent-message

Отправьте человеческое сообщение. Полезная нагрузка: { "sessionId": "...", "message": "..." }

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

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

{

  "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/:id/assign — укажите номер. Полезная нагрузка: {}

POST /api/assistants/:id/outbound – инициировать исходящий вызов. Полезная нагрузка: { "to": "+123...", "message": "..." }

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

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

POST /api/bookings/cancel — Отменить активное бронирование. Полезная нагрузка: { "bookingId": "uuid" }

POST /api/bookings/reschedule — корректировка бронирования. Полезная нагрузка: { "bookingId": "uuid", "newTime": "ISO-8601" }

Получите информацию об использовании платежного цикла рабочей области, ограничениях плана подписки и общем количестве помощников. Примечание. При использовании ключа 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"
}