Використовуйте контракт 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.