API Kalyvox : documentation (Zapier & webhooks)
Endpoints, authentification, webhooks et spécification OpenAPI de l'API publique Kalyvox.
Kalyvox expose une API REST publique qui donne accès aux tickets d'appel de votre espace de travail et permet de recevoir un webhook à chaque nouvel appel. C'est l'API utilisée par l'intégration Zapier officielle ; vous pouvez aussi l'appeler directement depuis vos propres outils (Make, n8n, un back-office maison…).
URL de base et spécification
Toutes les requêtes se font en HTTPS sur :
https://auth.kalyvox.ai/functions/v1/zapier-apiExemple complet : https://auth.kalyvox.ai/functions/v1/zapier-api/v1/auth/test
La spécification OpenAPI 3.1 (schémas, paramètres, exemples, webhook) est publique : https://kalyvox.ai/openapi/kalyvox-zapier-v1.json. Vous pouvez l'importer dans Postman, Insomnia ou Swagger Editor.
Authentification
L'API s'authentifie avec une clé API d'espace de travail, transmise en en-tête Authorization: Bearer. La clé identifie l'espace de travail : aucun identifiant de compte n'est accepté dans les paramètres.
Créer une clé
Dans Kalyvox, allez dans Paramètres > Intégrations > Zapier, puis « Créer une clé ». La clé (format kvx_live_…) n'est affichée qu'une seule fois : copiez-la immédiatement. Vous pouvez révoquer une clé à tout moment depuis le même écran ; les requêtes suivantes renvoient alors une erreur 401.
curl -H "Authorization: Bearer kvx_live_xxx" \
https://auth.kalyvox.ai/functions/v1/zapier-api/v1/auth/test
{"id":"3f1c...","name":"Acme Plumbing","brand":"kalyvox"}Traitez la clé comme un mot de passe
Endpoints
| Méthode | Chemin | Description |
|---|---|---|
| GET | /v1/auth/test | Valide la clé API et renvoie l'espace de travail associé. |
| GET | /v1/tickets/recent?limit=3 | Derniers tickets d'appel (1 à 100), du plus récent au plus ancien. |
| GET | /v1/tickets/search | Recherche filtrée et paginée par curseur. |
| POST | /v1/webhook-subscriptions | Abonne une URL Zapier à un événement (REST hook). |
| DELETE | /v1/webhook-subscriptions/:id | Désactive l'abonnement. |
GET /v1/tickets/recent
Paramètre limit (entier, 1 à 100, défaut 3). Renvoie un tableau JSON de tickets, du plus récent au plus ancien.
curl -H "Authorization: Bearer kvx_live_xxx" \
"https://auth.kalyvox.ai/functions/v1/zapier-api/v1/tickets/recent?limit=5"GET /v1/tickets/search
Paramètres disponibles : limit (1-100, défaut 20), created_after et created_before (ISO 8601), status (open, in_progress, closed, pending, resolved), urgency (normal, high), intent (clé de scénario, 80 caractères max), caller_phone (E.164, 32 caractères max) et cursor.
curl -H "Authorization: Bearer kvx_live_xxx" \
"https://auth.kalyvox.ai/functions/v1/zapier-api/v1/tickets/search?status=open&urgency=high&limit=20"
{
"results": [ /* … tickets … */ ],
"next_cursor": "eyJjIjoiMjAyNi0wOC0y..."
}Pour la page suivante, renvoyez la valeur de next_cursor dans ?cursor=. Quand next_cursor vaut null, vous êtes sur la dernière page.
Abonnements webhook
POST /v1/webhook-subscriptions avec un corps JSON contenant target_url (URL https de hook Zapier ; alias acceptés : hookUrl, url) et éventuellement event (seule valeur supportée : ticket.created).
curl -X POST \
-H "Authorization: Bearer kvx_live_xxx" \
-H "Content-Type: application/json" \
-d '{"target_url":"https://hooks.zapier.com/hooks/standard/123/abc/","event":"ticket.created"}' \
https://auth.kalyvox.ai/functions/v1/zapier-api/v1/webhook-subscriptions
{"id":"9c1e...","event":"ticket.created","target_url":"https://hooks.zapier.com/..."}Pour se désabonner : DELETE /v1/webhook-subscriptions/{id}. L'abonnement est désactivé et les livraisons en attente sont annulées.
Webhook ticket.created
À chaque nouveau ticket d'appel, Kalyvox envoie un POST JSON à l'URL abonnée. Le corps est exactement le même objet que celui renvoyé par /v1/tickets/recent. Répondez avec un code 2xx : en cas d'échec, Kalyvox réessaie jusqu'à 5 fois (30 s, 2 min, 10 min, 1 h, 6 h).
Schéma d'un ticket
{
"id": "0f0a9f6c-4c4e-4f5f-9a2b-2a1f4c0f9a11",
"created_at": "2026-08-27T09:14:02.318Z",
"status": "open",
"intent": "new_lead",
"urgency": "high",
"caller_name": "Jane Cooper",
"caller_phone": "+13125550142",
"caller_email": "jane@example.com",
"summary": "Water heater leaking, asks for an emergency visit today.",
"call_id": "call_8fa2",
"appointment_booked": true,
"appointment_start": "2026-08-27T15:00:00.000Z",
"appointment_end": "2026-08-27T16:00:00.000Z",
"transcript": "assistant: Thanks for calling Acme Plumbing...\nuser: My water heater is leaking.",
"language": "en",
"metadata": {
"sub_intent_key": "emergency",
"is_escalated": false,
"assigned": false
}
}Les champs caller_email, appointment_start et appointment_end ne sont renseignés que lorsqu'un rendez-vous non annulé est rattaché à l'appel. transcript est une chaîne texte, une ligne par tour de parole.
Erreurs et quotas
Les erreurs suivent un format unique. L'identifiant request_id est aussi renvoyé dans l'en-tête x-request-id : communiquez-le au support pour toute investigation.
{
"error": {
"code": "invalid_request",
"message": "limit must be between 1 and 100.",
"request_id": "0d2f5b1e-9a2c-4a5f-9b71-6d0a1c93f2e4"
}
}400 invalid_request— paramètre ou corps invalide.401 unauthorized— clé absente, invalide ou révoquée.404 not_found— ressource inconnue pour cet espace de travail.429 rate_limited— plus de 120 requêtes par minute et par clé.500 internal_error— erreur côté Kalyvox, réessayez.
Disponibilité
Cet article vous a-t-il aidé ?
Pour aller plus loin
Prêt à automatiser votre accueil téléphonique ?
Créez votre compte Kalyvox gratuitement et testez votre assistant IA pendant 7 jours.