API Kalyvox : documentation (Zapier & webhooks)

URL de base et spécification

Toutes les requêtes se font en HTTPS sur :

https://auth.kalyvox.ai/functions/v1/zapier-api

Exemple 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.

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"}

Endpoints

curl -H "Authorization: Bearer kvx_live_xxx" \
  "https://auth.kalyvox.ai/functions/v1/zapier-api/v1/tickets/recent?limit=5"

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..."
}

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/..."}

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.