Используйте контракт OpenAPI, чтобы сгенерировать клиент для интеграции. Публичный API, панель и управляющий endpoint MCP работают с одними и теми же ресурсами и правами рабочего пространства.
| Возможность | Endpoint |
|---|---|
| Многоразовые инструменты | GET / POST /api/v1/voice/tools |
| Прочитать / обновить / удалить инструмент | GET / PATCH / DELETE /api/v1/voice/tools/{id} |
| Предпросмотр или проверка инструмента | POST /api/v1/voice/tools/{id}/test |
| Привязать инструменты к агенту | PUT /api/v1/voice/agents/{id}/tools |
| Базы знаний | GET / POST /api/v1/voice/knowledge-bases |
| Прочитать / обновить / удалить базу знаний | GET / PATCH / DELETE /api/v1/voice/knowledge-bases/{id} |
| Добавить / вывести список документов | POST / GET /api/v1/voice/knowledge-bases/{id}/documents |
| Прочитать / удалить документ | GET / DELETE /api/v1/voice/knowledge-bases/{id}/documents/{doc_id} |
| Подписки на события звонков | GET / POST /api/v1/voice/webhooks |
| Прочитать / обновить / удалить подписку | GET / PATCH / DELETE /api/v1/voice/webhooks/{id} |
| Отправить подписанное тестовое событие | POST /api/v1/voice/webhooks/{id}/test |
| Обнаружить удалённые инструменты MCP | POST /api/v1/voice/mcp/discover |
| Управляющий endpoint MCP | /api/v1/voice/mcp |
Зарегистрируйте HTTP-инструмент, который обращается к вашему CRM-адаптеру:
{
"name": "lookup_customer",
"description": "Find a customer after confirming their customer ID.",
"kind": "http",
"url": "https://crm.example.com/customers/{{customer_id}}",
"method": "GET",
"read_only": true,
"credential_ref": "crm",
"input_schema": {
"type": "object",
"properties": { "customer_id": { "type": "string" } },
"required": ["customer_id"],
"additionalProperties": false
},
"response_path": "data"
}
POST /tools возвращает { "data": { "id": "TOOL_ID", ... } }. Привяжите его определение к агенту через PUT /agents/AGENT_ID/tools с { "tool_ids": ["TOOL_ID"] }. Это заменяет весь список инструментов снимками; привяжите заново, когда инструмент библиотеки изменится. Удаление определения из библиотеки сохраняет существующие снимки. Встроенные определения можно также читать и заменять через поле tools API агента. Через API агента задавайте analysis_config и widget_config для настройки анализа и виджета.
Инструмент может использовать GET, POST, PUT, PATCH или DELETE. query и request_body принимают вложенные JSON-шаблоны вроде { "customer": { "id": "{{customer_id}}" } }. Заполнитель, занимающий всё значение, сохраняет исходный тип JSON. Заполнители в URL кодируются и могут стоять только после фиксированного публичного HTTPS-хоста. Без request_body инструменты, отличные от GET, получают { "arguments": {...}, "call": { "callId": "...", "agentId": "...", "toolCallId": "...", "idempotencyKey": "..." } }. response_path выбирает поле в точечной нотации. Простые parameters по-прежнему принимаются; input_schema дополнительно поддерживает вложенные объекты, массивы, перечисления и числовые границы. Внешние ссылки на схемы и регулярные выражения не принимаются.
static_args: значения, отправляемые с каждым вызовом независимо от того, что напишет модель, например идентификатор магазина; они также подставляются в {{name}} в адресе и теле.extract: [{name, path}] сохраняет поля из ответа функции (data.id) для {{name}} в последующих функциях, так что customer_id из поиска можно передать в следующий заказ, не заставляя модель повторять его. Поля начального запроса сохраняются так же.reject_when: до 5 правил {on: caller|agent, pattern, negate}; пока все они выполняются для последних слов, функция не запускается, а агент получает reject_message.model_says: при каждом вызове модель пишет одну фразу, которая произносится, пока выполняется функция, вместо фиксированного speak_before.Подключите приложение в Интеграции → Вебхуки и уведомления → Подключённые приложения, затем используйте «Добавить готовую функцию» на вкладке «Знания и инструменты» агента; собственный endpoint не нужен:
check_availability (свободное время на дату) и book_appointment (записывает на время, выбранное звонящим). Время в Google Calendar следует заданным вами часовому поясу, рабочим дням, часам и длительности приёма; Cal.com использует собственную доступность типа события и запасной адрес электронной почты, который вы зададите, если звонящий его не назвал.save_to_sheet, которая дописывает строку с перечисленными вами столбцами, а также ID и временем звонка.notify_team, которая публикует в канале Slack (incoming webhook) сообщение, написанное агентом.Плоскость управления EvaSay выполняет эти функции с подключённым вами аккаунтом; ни воркер, ни определение агента не хранят учётные данные приложения. При чтении агента через API они отображаются как kind: "app" (с app, action, connection_id, app_config); отправляйте их обратно без изменений при замене tools, чтобы сохранить. Приложения подключаются только в панели.
Задайте run_at_start: true одному из инструментов агента, и он будет вызван при начале каждого звонка, до того как агент поздоровается или ответит. Параметры с именами caller_number, called_number, direction, channel или call_id заполняются для него автоматически. Возвращаемые им поля подставляются в {{variables}} в first_message, system_prompt и idle_messages (поля на уровень глубже — как {{customer.name}}), а весь ответ передаётся агенту как справочная информация. Приветствие с переменными ждёт ответа до 3 секунд; всё, что не найдено, остаётся пустым. При старте может запускаться один инструмент на агента.
Учётные данные настраиваются в окружении сервера для вашего рабочего пространства и адреса назначения; попросите support@evasay.com выделить credential_ref. Не помещайте API-ключи в определения агентов, заголовки, промпты и параметры инструментов. Ваш адаптер может хранить учётные данные CRM в собственном окружении.
Просмотрите инструмент, прежде чем отправлять запросы в бизнес-систему:
{
"arguments": { "customer_id": "customer-123" },
"dry_run": true,
"mock_result": { "name": "Alex", "order_status": "shipped" }
}
Предпросмотр проверяет параметры и показывает сформированный запрос; он не ведёт разговор и не обращается к бизнес-системе. Установите dry_run=false для реального выполнения. Реальная проверка записи также требует confirmed=true и idempotency_key (8–128 букв, цифр, точек, подчёркиваний, двоеточий или дефисов). Ответы тестов содержат ok, status, duration_ms и ограниченный по размеру результат. Учётные данные они не возвращают. Тесты чтения и записи требуют права записи в рабочем пространстве.
Во время звонка бизнес-запросы несут стабильный Idempotency-Key. Ваш бизнес-endpoint должен его соблюдать. Одинаковые операции записи в рамках звонка дедуплицируются, включая операции с неизвестным исходом после тайм-аута. Другая намеренная операция требует отдельного бизнес-аргумента, например operation_id. EvaSay не повторяет операции записи автоматически. События выполнения инструментов содержат статус и длительность; функция проверки разговора остаётся текстовой симуляцией, а не проверкой выполнения инструментов.
POST /mcp/discover принимает { "url": "https://crm.example.com/mcp", "credential_ref": "crm" } и возвращает инструменты и схемы сервера. Регистрируйте только выбранный инструмент:
{
"name": "lookup_customer",
"description": "Find a CRM customer by confirmed ID.",
"kind": "mcp",
"url": "https://crm.example.com/mcp",
"mcp_tool": "get_customer",
"credential_ref": "crm",
"read_only": true,
"input_schema": {
"type": "object",
"properties": { "customer_id": { "type": "string" } },
"required": ["customer_id"]
}
}
Агенту доступны только зарегистрированные инструменты. Удалённые подключения поддерживают Streamable HTTP с ответами JSON или SSE на запросы, публичные HTTPS-адреса и заранее настроенные учётные данные. Устаревшие SSE-endpoint, согласование OAuth, инициируемые сервером sampling и elicitation и бинарные вложения не поддерживаются. Обнаружение не даёт автоматически доступ ко всем инструментам сервера. Схема удалённого инструмента должна быть встроенной и использовать поддерживаемое подмножество JSON Schema.