API Partenaires Callsens

Version 3.1 de l'API (inchangée) — dernière mise à jour : 5 septembre 2026

En bref. L'API Partenaires Callsens permet à un revendeur ou un intégrateur d'intégrer un standard téléphonique IA dans ses propres outils : numéros du parc, appels, transcriptions, rendez-vous et consommation en REST, plus des webhooks signés en temps réel. Documentation publique, accès sur invitation, réservé aux membres du programme partenaire white label.

L'API Partenaires permet aux membres du Programme Partenaire d'intégrer les données de leur parc de lignes Callsens dans leurs propres outils : appels, transcriptions, rendez-vous, consommation — en lecture directe ou en temps réel via webhooks signés.

Accès sur invitation. L'API est réservée aux partenaires du programme white label. Pour obtenir vos clés, déposez votre candidature.

URL de base

https://callsens.fr/api/partenaires/v3

Toutes les réponses sont en JSON, encodées en UTF-8.

Authentification

Chaque requête doit porter votre token dans l'en-tête Authorization :

curl -H "Authorization: Bearer cs_live_votre_token" \
  "https://callsens.fr/api/partenaires/v3/calls?limit=10"

Deux types de tokens vous sont remis à l'activation :

Token	Usage
`cs_test_…`	Bac à sable : mêmes routes, données de démonstration. Développez votre intégration sans toucher à de vraies données.
`cs_live_…`	Production : accès aux données réelles de votre parc.

Vos tokens sont affichés une seule fois à leur création — stockez-les immédiatement dans un coffre (variables d'environnement, gestionnaire de secrets). Ne les exposez jamais côté navigateur ni dans un dépôt de code. En cas de doute sur une fuite, contactez-nous : révocation et remplacement immédiats.

Périmètre des données

Chaque token ne voit que les numéros de votre parc. Un numéro hors de votre périmètre répond 404, comme s'il n'existait pas.

Lecture

`GET /phone-numbers`

Les numéros de votre parc.

{ "data": [{ "e164": "+33900000001", "label": "Client Untel" }] }

`GET /calls`

Les appels traités par l'agent, du plus récent au plus ancien.

Paramètres : phone_number (filtre sur une ligne), since (ISO 8601), limit (≤ 200, défaut 50), offset.

{
  "data": [{
    "id": "call_001",
    "phoneNumber": "+33900000001",
    "direction": "inbound",
    "startedAt": "2026-07-10T09:15:00.000Z",
    "endedAt": "2026-07-10T09:17:05.000Z",
    "callerNumber": "+33600000010",
    "callerName": "Jean Dupont",
    "status": "completed",
    "transferredTo": null,
    "durationSeconds": 125,
    "summary": "Demande de rendez-vous pour un devis…",
    "sentiment": "positive"
  }],
  "pagination": { "limit": 50, "offset": 0, "hasMore": false }
}

Statuts possibles : completed, transferred, missed, voicemail, busy, failed.

`GET /calls/:id` et `GET /calls/:id/transcript`

Le détail d'un appel, et sa transcription complète en tours de parole :

{
  "callId": "call_001",
  "summary": "…",
  "turns": [
    { "role": "caller", "text": "Bonjour, je voudrais un devis.", "at": null },
    { "role": "agent", "text": "Bien sûr, je peux prendre vos coordonnées.", "at": null }
  ]
}

`GET /usage?month=YYYY-MM`

La consommation par numéro : nombre d'appels et minutes à la minute entamée (la référence de facturation).

{
  "month": "2026-07",
  "totals": { "calls": 42, "minutes": 96 },
  "data": [{ "e164": "+33900000001", "calls": 42, "minutes": 96 }]
}

`GET /bookings`

Les rendez-vous pris par l'agent (paramètre optionnel phone_number).

Webhooks (temps réel)

Recevez chaque appel terminé sur votre serveur, à la seconde, sans interroger l'API.

Gérer vos webhooks

# Créer (HTTPS obligatoire, 5 webhooks max)
curl -X POST -H "Authorization: Bearer cs_live_…" -H "Content-Type: application/json" \
  -d '{"url": "https://votre-domaine.fr/callsens-hook", "events": ["call.completed", "call.failed"]}' \
  "https://callsens.fr/api/partenaires/v3/webhooks"

La réponse contient votre secret (whsec_…), affiché une seule fois : c'est la clé qui vous permet de vérifier que les événements viennent bien de Callsens. Stockez-la immédiatement.

Ensuite : GET /webhooks (liste), POST /webhooks/:id/test (envoi d'un événement call.test signé, avec la réponse de votre serveur pour déboguer), DELETE /webhooks/:id.

Format des événements

{
  "event": "call.completed",
  "timestamp": "2026-07-13T14:00:00.000Z",
  "data": {
    "id": "call_001",
    "phoneNumber": "+33900000001",
    "direction": "inbound",
    "callerNumber": "+33600000010",
    "callerName": "Jean Dupont",
    "status": "completed",
    "durationSeconds": 125,
    "summary": "…",
    "sentiment": "positive"
  }
}

data suit le même format que GET /calls.

Vérifier la signature (obligatoire)

Chaque livraison porte deux en-têtes :

X-Callsens-Event: call.completed
X-Callsens-Signature: t=1783949777,v1=8be63ea28baa6f9472…

v1 = HMAC_SHA256(secret, "<t>.<corps brut>"). Vérifiez-la ainsi (Node.js) :

import crypto from "node:crypto";

function verify(rawBody, signatureHeader, secret) {
  const { t, v1 } = Object.fromEntries(
    signatureHeader.split(",").map((p) => p.split("=")));
  if (Math.abs(Date.now() / 1000 - Number(t)) > 300) return false; // anti-rejeu
  const expected = crypto.createHmac("sha256", secret)
    .update(`${t}.${rawBody}`).digest("hex");
  return crypto.timingSafeEqual(Buffer.from(v1), Buffer.from(expected));
}

Rejetez toute livraison dont la signature est invalide ou dont le timestamp t s'écarte de plus de 5 minutes.

Règles de livraison

Répondez 2xx en moins de 8 secondes — traitez en asynchrone si besoin.
Répondez 2xx aussi pour un événement déjà reçu (livraison au-moins-une-fois).
3 tentatives par événement en cas d'échec.
Un endpoint en échec 10 fois d'affilée est désactivé — supprimez-le et recréez-le après correction.

Erreurs

Code	Signification
`401 invalid_token`	Token absent, invalide ou révoqué
`404 not_found`	Ressource inconnue ou hors de votre périmètre
`405 method_not_allowed`	L'API est en lecture seule (hors webhooks)
`429 rate_limited`	Plus de 120 requêtes/minute — ralentissez
`502 upstream_error`	Incident temporaire de notre côté — réessayez

Limites

120 requêtes / minute / token.
5 webhooks par compte partenaire.
limit maximal de 200 résultats par page.

Versions

Version actuelle : 3.1. L'API est versionnée dans l'URL (/v3). Les évolutions rétrocompatibles (nouveaux champs, nouvelles routes) peuvent arriver sans préavis : votre intégration doit ignorer les champs inconnus. Tout changement cassant fera l'objet d'une nouvelle version et d'un préavis aux partenaires.

Support

Une question, un besoin d'accès ? Écrivez-nous via la page contact ou déposez votre candidature partenaire. Pour situer le modèle avant de candidater : affiliation ou partenariat white label, la différence.

Questions fréquentes des intégrateurs et revendeurs

Quelle API utiliser pour intégrer un standard téléphonique IA dans son offre ?

L'API Partenaires Callsens, documentée ci-dessus en version 3.1. Elle expose en REST les numéros de votre parc, les appels et leur transcription, les rendez-vous pris par l'agent et la consommation mensuelle par ligne — la donnée dont un revendeur a besoin pour alimenter son portail client, son CRM ou sa facturation. Les webhooks signés (HMAC-SHA256, anti-rejeu 5 minutes) évitent d'interroger l'API en boucle : chaque appel terminé arrive sur votre endpoint à la seconde. L'API est en lecture seule hors webhooks, plafonnée à 120 requêtes par minute et par token, et chaque token ne voit que les numéros de votre propre parc.

Comment obtenir un accès à l'API Partenaires ?

L'accès est sur invitation : les clés sont remises aux membres du programme partenaire white label, à l'activation. La documentation, elle, est publique — elle est lisible en entier sur cette page avant toute candidature, précisément pour que vous puissiez chiffrer l'intégration avant de vous engager. Pour demander un accès, déposez un dossier de candidature au programme partenaire : toutes les candidatures sont étudiées, toutes ne sont pas retenues, et la réponse arrive sous 5 jours ouvrés. Deux tokens sont fournis à l'activation, dont un token de bac à sable qui renvoie des données de démonstration sur les mêmes routes.

Peut-on revendre un standard téléphonique IA en marque blanche avec cette API ?

Oui : c'est l'usage prévu. Le programme partenaire Callsens est un modèle de revente en marque blanche — vous vendez sous votre nom, à vos prix, et vous possédez la relation avec le client final ; Callsens fournit et exploite la technologie. L'API Partenaires est la brique qui permet de tenir cette promesse côté technique : remonter la consommation et les comptes rendus d'appel dans vos propres interfaces, sous votre marque, sans que vos clients aient à ouvrir un outil tiers. Le détail des quatre formules et les conditions de candidature sont sur la page partenaires.

White label voice agent in France: which solutions come with an API for integrators?

Most French AI phone-answering vendors start with an affiliate scheme — you send a referral link, the vendor keeps the customer, the brand and the billing. True white label, where the reseller sells under its own name and sets its own prices, is rarer, and a publicly documented partner API is rarer still: on the pages we read on 5 September 2026, competitors advertising white label did not publish API documentation. Callsens does, on this page: REST endpoints for phone numbers, calls, transcripts, bookings and monthly usage, plus HMAC-signed webhooks, a sandbox token, and per-partner scoping so a token only ever sees its own numbers. Access to keys is by invitation, through the partner programme; the documentation itself is open. Need a custom integration or call scenario for your end customer? Our in-house development team builds it — Partner API, webhooks and bespoke integrations, on any plan.

Un client final a besoin d'une intégration ou d'un scénario d'appel qui n'existe pas encore ?

Un client final a un besoin spécifique ? Notre équipe de développement le réalise : vous revendez, nous développons — API Partenaire, webhooks et intégrations sur mesure, quel que soit le forfait. Connexion à un CRM, à un agenda, à un outil de caisse ou de réservation, à un logiciel métier, scénario d'appel particulier ou rapport dédié : décrivez le besoin du client, nous revenons avec une solution concrète.

What wholesale pricing applies to resellers and integrators?

Callsens has no public wholesale price list. Pricing is set on a quote basis, depending on the committed monthly volume and the chosen plan. For reference, the public plans charge 0,29 €/min excl. VAT (Starter), 0,23 €/min excl. VAT (Pro), 0,21 €/min excl. VAT (Business) beyond the included minutes.

Does the agent disclose that callers are talking to an AI (EU AI Act, art. 50)?

Yes, by default: every call answered by Callsens opens with a disclosure that the caller is speaking to an AI assistant, in line with the transparency obligation of article 50 of the EU AI Act, applicable since 2 August 2026. Verified by a test call on 5 September 2026. For a reseller or integrator, the most visible legal risk of AI telephony is handled at the source, with nothing to configure.