Dla programistów i twórców agentów AI
Buduj na ZvonAI.
API REST do odczytu i zapisu, podpisane webhooki i hostowany serwer MCP. Twoje systemy i agenci AI pracują na tych samych połączeniach, wizytach i zamówieniach telefonicznych, które zespół widzi w panelu.
Klucze API, webhooki i serwer MCP są częścią planów Business i Enterprise. Klucz tworzysz w panelu: Ustawienia, Programiści. Klucz jest pokazywany tylko raz.
API v2
odczyt i zapis
Webhooki
23 typy zdarzeń, podpisane
Serwer MCP
12 narzędzi dla agentów
Klucze testowe
testy bez skutków ubocznych
Klucze i uwierzytelnianie
Klucz wysyłasz jako token Bearer. Klucz produkcyjny zaczyna się od zv_live_. Klucz testowy zaczyna się od zv_test_: czyta Twoje prawdziwe dane, a jego zapisy są sprawdzane, ale nigdy nie są utrwalane, więc nie wychodzi żaden SMS, kalendarz się nie zmienia i żaden webhook nie jest wysyłany. Każdy klucz ma uprawnienia (scopes), więc może tylko to, na co pozwolisz.
# Live key: zv_live_... Sandbox key: zv_test_... # The key is shown once. Store it as a secret and send it as a Bearer token. curl -s "https://api.zvonai.ai/v2/calls?limit=20" \ -H "Authorization: Bearer zv_live_..." # Every v2 response says which mode produced it: # body: "livemode": true | false # header: X-ZvonAI-Livemode: true | false
API v2: odczyt i zapis
Aktualny kontrakt. Listy używają paginacji kursorowej. Rezerwacja i zmiana wizyty oraz dodanie wiedzy wymagają nagłówka Idempotency-Key, więc ponowienie nigdy nie zarezerwuje dwa razy: ten sam klucz z tą samą treścią zwraca pierwszą odpowiedź, a ten sam klucz z inną treścią jest odrzucany z kodem 409. Błędy przychodzą w jednej kopercie ze stałym kodem. Limit to 100 zapytań na minutę na klucz, podawany w nagłówkach RateLimit.
| Metoda | Ścieżka | Uprawnienie |
|---|---|---|
| GET | /v2/calls | calls:read |
| GET | /v2/calls/{call_id} | calls:read |
| GET | /v2/appointments | appointments:read |
| GET | /v2/appointments/{appointment_id} | appointments:read |
| POST | /v2/appointments | appointments:write |
| PATCH | /v2/appointments/{appointment_id} | appointments:write |
| POST | /v2/appointments/{appointment_id}/cancel | appointments:write |
| GET | /v2/availability | appointments:read |
| GET | /v2/orders | orders:read |
| GET | /v2/orders/{order_id} | orders:read |
| PATCH | /v2/orders/{order_id} | orders:write |
| POST | /v2/orders/{order_id}/deposit | orders:write |
| GET | /v2/deposits | deposits:read |
| GET | /v2/deposits/{deposit_id} | deposits:read |
| GET | /v2/faq | faq:read |
| PUT | /v2/faq | faq:write |
| GET | /v2/knowledge | knowledge:read |
| POST | /v2/knowledge | knowledge:write |
| GET | /v2/voice-config | voice_config:read |
| PATCH | /v2/voice-config | voice_config:write |
| GET | /v2/analytics | analytics:read |
| GET | /v2/analytics/timeseries | analytics:read |
| GET | /v2/tenant | tenants:read |
| GET | /v2/billing/usage | billing:read |
| GET | /v2/webhook-endpoints | webhooks:manage |
| POST | /v2/webhook-endpoints | webhooks:manage |
| DELETE | /v2/webhook-endpoints/{endpoint_id} | webhooks:manage |
| POST | /v2/webhook-endpoints/{endpoint_id}/rotate-secret | webhooks:manage |
| POST | /v2/webhook-endpoints/{endpoint_id}/test | webhooks:manage |
# Book an appointment (scope: appointments:write).
# The Idempotency-Key makes a retry safe: the same key and body return
# the first result, the same key with another body returns 409.
curl -s -X POST "https://api.zvonai.ai/v2/appointments" \
-H "Authorization: Bearer zv_live_..." \
-H "Idempotency-Key: 6f1c2a9e-booking-0001" \
-H "Content-Type: application/json" \
-d '{
"patient_name": "Jan Kowalski",
"patient_phone": "+48500100200",
"start_time": "2026-12-03T09:00:00+01:00",
"end_time": "2026-12-03T09:30:00+01:00",
"service_type": "Konsultacja"
}'
# Errors always have the same shape. Branch on "code", not on the text.
# { "error": { "code": "...", "message": "...", "message_pl": "...",
# "field": "...", "request_id": "..." } }
# Rate limit: 100 requests per minute per key.
# RateLimit-Limit, RateLimit-Remaining, RateLimit-Reset on every response,
# Retry-After on 429.Pola i przykłady dla każdego endpointu: https://api.zvonai.ai/docs · /openapi.json
API v1: nadal wspierane
Tylko odczyt, paginacja przez offset. Istniejące integracje działają dalej. Do nowych prac używaj v2.
| Metoda | Ścieżka | Uprawnienie |
|---|---|---|
| GET | /v1/calls | calls:read |
| GET | /v1/calls/{call_id} | calls:read |
| GET | /v1/appointments | appointments:read |
| GET | /v1/analytics | analytics:read |
Webhooki
Adresy https rejestrujesz przez API. Każdy adres ma własny sekret podpisu, pokazywany raz przy utworzeniu i przy rotacji, oraz własną listę zdarzeń. Pusta lista oznacza wszystkie zdarzenia. Nieudana dostawa jest ponawiana.
# 1. Register an endpoint (scope: webhooks:manage). The secret comes back once.
curl -s -X POST "https://api.zvonai.ai/v2/webhook-endpoints" \
-H "Authorization: Bearer zv_live_..." \
-H "Content-Type: application/json" \
-d '{ "url": "https://example.com/zvonai", "events": ["call.completed"] }'
# 2. What arrives. Headers:
# X-ZvonAI-Event: call.completed
# X-ZvonAI-Signature: t={timestamp},v1={signature}
{
"event": "call.completed",
"tenant_id": "1b9d6bcd-bbfd-4b2d-9b5d-ab8dfbbd4bed",
"timestamp": "2026-12-03T08:14:09.000Z",
"data": {
"call_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
"from": "+48500100200",
"to": "+48221002030",
"duration_seconds": 87,
"outcome": "booked",
"callback_requested": false,
"summary": "..."
}
}
# 3. Verify (Node.js). Sign the RAW request body, not re-serialized JSON.
import crypto from "node:crypto";
function verify(rawBody, timestamp, signature, secret) {
const expected = crypto
.createHmac("sha256", secret)
.update(`${timestamp}.${rawBody}`)
.digest("hex");
if (signature.length !== expected.length) return false;
return crypto.timingSafeEqual(Buffer.from(signature), Buffer.from(expected));
}Zdarzenia, które możesz subskrybować
- call.completed
- message.left
- appointment.created
- appointment.requested
- appointment.updated
- appointment.cancelled
- order.created
- order.updated
- order.deposit_requested
- deposit.paid
- deposit.expired
- api_key.created
- api_key.revoked
- team.member_invited
- team.member_joined
- team.role_changed
- team.member_removed
- team.member_reactivated
- team.calendar_connected
- team.calendar_disconnected
- team.ownership_transferred
- knowledge.milestone_reached
- settings.fallback_updated
Treść zawiera dane dzwoniących, na przykład numer telefonu i podsumowanie rozmowy. Sprawdzaj podpis na surowej treści i chroń to, co zapisujesz.
Serwer MCP dla agentów AI
Hostowany serwer Model Context Protocol. Każdy klient MCP, który potrafi wysłać nagłówek Bearer, łączy się tym samym kluczem API. Każde narzędzie sprawdza uprawnienie klucza. Narzędzia, które coś zmieniają albo docierają do człowieka, są tak oznaczone, więc klient może zapytać przed ich uruchomieniem. Klucze testowe mogą wywoływać tylko narzędzia do odczytu.
# JSON-RPC over HTTP, protocol 2025-06-18.
# Methods: initialize, tools/list, tools/call, ping.
# https://mcp.zvonai.ai/v2/mcp and https://api.zvonai.ai/v2/mcp are the same server.
curl -s -X POST "https://mcp.zvonai.ai/v2/mcp" \
-H "Authorization: Bearer zv_live_..." \
-H "Content-Type: application/json" \
-d '{ "jsonrpc": "2.0", "id": 1, "method": "tools/list" }'
curl -s -X POST "https://mcp.zvonai.ai/v2/mcp" \
-H "Authorization: Bearer zv_live_..." \
-H "Content-Type: application/json" \
-d '{ "jsonrpc": "2.0", "id": 2, "method": "tools/call",
"params": { "name": "get_business_profile", "arguments": {} } }'Narzędzia
- list_callscalls:readodczyt
- list_appointmentsappointments:readodczyt
- get_open_slotsappointments:readodczyt
- list_ordersorders:readodczyt
- get_orderorders:readodczyt
- list_depositsdeposits:readodczyt
- get_call_statisticsanalytics:readodczyt
- get_faqfaq:readodczyt
- get_business_profiletenants:readodczyt
- update_order_statusorders:writezmienia dane
- request_order_depositorders:writezmienia dane
- handoff_callcalls:writezmienia dane
Dla systemów AI, które czytają sieć
Publiczna strona jest otwarta dla robotów asystentów AI i wyszukiwarek oraz udostępnia opisy napisane dla maszyn.
llms.txt
Krótki opis produktu dla okien kontekstowych AI
llms-full.txt
Pełny opis ze szczegółami API i webhooków
Asystentka mówi, kim jest
Na początku rozmowy asystentka przedstawia się jako asystent AI lub wirtualny asystent.
robots.txt wymienia i wpuszcza między innymi: GPTBot, ChatGPT-User, OAI-SearchBot, ClaudeBot, PerplexityBot, Google-Extended, MistralBot, Bingbot, Googlebot.
Dane przechowywane w UE
Baza danych i nagrania w GCP europe-central2 (Warszawa). Zgodność z RODO art. 9 dla danych zdrowotnych. Umowa powierzenia z każdą firmą, z pełną listą dostawców i miejsc przetwarzania.