Documentation API Telefon-iA

L'API Telefon-iA vous permet d'intégrer la téléphonie IA dans vos applications. Tous les endpoints retournent du JSON. L'authentification utilise des Bearer tokens JWT.

URL de base : https://api.telefon-ia.io

Authentification requise — Toutes les routes protégées nécessitent un header Authorization: Bearer <accessToken>. Le token expire après 15 minutes. Utilisez POST /api/auth/refresh pour obtenir un nouveau token via le refreshToken.

Authentification

POST /api/auth/register Créer un nouveau compte

Corps de la requête

Champ	Type	Requis	Description
email	string	Requis	Adresse e-mail unique
password	string	Requis	Minimum 8 caractères
firstName	string	Requis	Prénom
lastName	string	Requis	Nom de famille
organizationName	string	Requis	Nom de l'organisation

Réponse 201 — Compte créé

{
  "accessToken":  "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "refreshToken": "dGhpcyBpcyBhIHJlZnJlc2ggdG9rZW4...",
  "user": {
    "id":             "usr_01J...",
    "email":          "contact@entreprise.fr",
    "firstName":     "Sophie",
    "lastName":      "Martin",
    "organizationId": "org_01J...",
    "role":           "owner",
    "createdAt":      "2025-01-15T10:00:00.000Z"
  }
}

POST /api/auth/login Se connecter

Corps de la requête

Champ	Type	Requis	Description
email	string	Requis	Adresse e-mail
password	string	Requis	Mot de passe

Réponse 200

{
  "accessToken":  "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "refreshToken": "dGhpcyBpcyBhIHJlZnJlc2ggdG9rZW4...",
  "user": {
    "id":    "usr_01J...",
    "email": "contact@entreprise.fr",
    "role":  "owner"
  }
}

POST /api/auth/refresh Renouveler le token d'accès

Corps de la requête

Champ	Type	Requis	Description
refreshToken	string	Requis	Token de renouvellement obtenu lors de la connexion

Réponse 200

{
  "accessToken":  "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "refreshToken": "dGhpcyBpcyBhIHJlZnJlc2ggdG9rZW4..."
}

GET /api/auth/me Profil de l'utilisateur connecté

Headers requis

Header	Valeur		Description
Authorization	string	Requis	Bearer <accessToken>

Réponse 200

{
  "id":             "usr_01J...",
  "email":          "contact@entreprise.fr",
  "firstName":     "Sophie",
  "lastName":      "Martin",
  "role":           "owner",
  "organizationId": "org_01J...",
  "plan":           "pro",
  "createdAt":      "2025-01-15T10:00:00.000Z"
}

Appels

GET /api/calls Lister les appels

Paramètres de requête

Paramètre	Type	Requis	Description
page	integer	Optionnel	Numéro de page (défaut : 1)
limit	integer	Optionnel	Résultats par page, max 100 (défaut : 20)
direction	string	Optionnel	`inbound` \| `outbound`
status	string	Optionnel	`completed` \| `missed` \| `in_progress`
date_from	string	Optionnel	ISO 8601, ex. `2025-01-01T00:00:00Z`
date_to	string	Optionnel	ISO 8601

Réponse 200

{
  "data": [
    {
      "id":           "call_01J...",
      "direction":   "inbound",
      "status":      "completed",
      "from":        "+33612345678",
      "to":          "+33756789012",
      "duration":    187,
      "startedAt":   "2025-03-10T14:32:00.000Z",
      "endedAt":     "2025-03-10T14:35:07.000Z",
      "hasRecording": true,
      "sentiment":   "positive"
    }
  ],
  "total": 142,
  "page":  1,
  "limit": 20
}

GET /api/calls/:id Détail d'un appel

Réponse 200

{
  "id":           "call_01J...",
  "direction":   "inbound",
  "status":      "completed",
  "from":        "+33612345678",
  "to":          "+33756789012",
  "duration":    187,
  "transcript":  "Bonjour, je voudrais...",
  "summary":     "Client demande remboursement livraison J+3",
  "sentiment":   "positive",
  "recordingUrl": "https://cdn.telefon-ia.io/recordings/call_01J....mp3",
  "agentId":     "agt_01J...",
  "contactId":   "cnt_01J...",
  "tags":        ["livraison", "remboursement"],
  "startedAt":   "2025-03-10T14:32:00.000Z",
  "endedAt":     "2025-03-10T14:35:07.000Z"
}

Contacts

GET /api/contacts Lister les contacts

Paramètres de requête

Paramètre	Type	Requis	Description
page	integer	Optionnel	Numéro de page (défaut : 1)
limit	integer	Optionnel	Résultats par page (défaut : 20)
search	string	Optionnel	Recherche par nom, téléphone ou email
tag	string	Optionnel	Filtrer par tag

Réponse 200

{
  "data": [
    {
      "id":        "cnt_01J...",
      "firstName": "Marie",
      "lastName":  "Dupont",
      "phone":     "+33612345678",
      "email":     "marie.dupont@exemple.fr",
      "tags":      ["prospect", "lyon"],
      "callCount": 3,
      "createdAt": "2025-02-01T09:00:00.000Z"
    }
  ],
  "total": 84,
  "page":  1,
  "limit": 20
}

POST /api/contacts Créer un contact

Corps de la requête

Champ	Type	Requis	Description
phone	string	Requis	Format E.164 ex. +33612345678
firstName	string	Optionnel	Prénom
lastName	string	Optionnel	Nom
email	string	Optionnel	Adresse e-mail
tags	string[]	Optionnel	Liste de tags
customFields	object	Optionnel	Champs personnalisés clé/valeur

Réponse 201 — Contact créé

{
  "id":        "cnt_01J...",
  "phone":     "+33612345678",
  "firstName": "Marie",
  "lastName":  "Dupont",
  "email":     "marie.dupont@exemple.fr",
  "tags":      ["prospect"],
  "createdAt": "2025-03-15T11:00:00.000Z"
}

DELETE /api/contacts/:id Supprimer un contact

Réponse 200

{ "success": true }

POST /api/contacts/import Importer depuis un fichier CSV

Corps — multipart/form-data

Champ	Type	Requis	Description
file	File	Requis	Fichier CSV (max 10 Mo). Colonnes : phone, firstName, lastName, email, tags

Réponse 200

{
  "imported": 243,
  "skipped":  7,
  "errors": [
    { "row": 4, "reason": "Numéro de téléphone invalide" }
  ]
}

Campagnes

POST /api/campaigns Créer une campagne d'appels sortants

Corps de la requête

Champ	Type	Requis	Description
name	string	Requis	Nom de la campagne
agentId	string	Requis	ID de l'agent IA à utiliser
contactIds	string[]	Requis	Liste d'IDs de contacts à appeler
callWindow	object	Optionnel	Fenêtre horaire : `{from: "09:00", to: "18:00", timezone: "Europe/Paris"}`
maxConcurrent	integer	Optionnel	Appels simultanés max (défaut : 3)
retryCount	integer	Optionnel	Nombre de rappels si pas de réponse (défaut : 2)

Réponse 201

{
  "id":          "cmp_01J...",
  "name":        "Relance prospects mars",
  "status":      "draft",
  "totalCalls":  150,
  "createdAt":   "2025-03-01T08:00:00.000Z"
}

POST /api/campaigns/:id/start Démarrer une campagne

Réponse 200

{ "id": "cmp_01J...", "status": "running", "startedAt": "2025-03-01T09:00:00.000Z" }

POST /api/campaigns/:id/pause Mettre en pause une campagne

Réponse 200

{ "id": "cmp_01J...", "status": "paused" }

Facturation

GET /api/billing/credits Solde de crédits de l'organisation

Réponse 200

{
  "balance":       1240,
  "unit":          "minutes",
  "plan":          "pro",
  "monthlyIncluded": 500,
  "renewsAt":      "2025-04-01T00:00:00.000Z"
}

POST /api/billing/checkout Créer une session de paiement

Corps de la requête

Champ	Type	Requis	Description
pack	string	Requis	`starter` \| `pro` \| `enterprise` \| `credits_500` \| `credits_1000`
successUrl	string	Optionnel	URL de redirection après paiement réussi
cancelUrl	string	Optionnel	URL de redirection en cas d'annulation

Réponse 200

{
  "checkoutUrl": "https://checkout.revolut.com/payment-link/...",
  "sessionId":   "pay_01J...",
  "expiresAt":   "2025-03-15T12:30:00.000Z"
}

Webhooks sortants

Telefon-iA envoie ces événements en POST vers l'URL webhook configurée dans votre tableau de bord. Chaque requête inclut le header X-Cloud Call-Signature (HMAC-SHA256 du corps avec votre clé secrète) pour vérifier l'authenticité.

call.started WEBHOOK Déclenché dès qu'un appel est établi

{
  "event":     "call.started",
  "id":        "evt_01J...",
  "createdAt": "2025-03-10T14:32:00.000Z",
  "data": {
    "callId":    "call_01J...",
    "direction": "inbound",
    "from":      "+33612345678",
    "to":        "+33756789012",
    "agentId":   "agt_01J...",
    "contactId": "cnt_01J...",
    "startedAt": "2025-03-10T14:32:00.000Z"
  }
}

call.ended WEBHOOK Déclenché à la fin d'un appel (avec transcription)

{
  "event":     "call.ended",
  "id":        "evt_01J...",
  "createdAt": "2025-03-10T14:35:07.000Z",
  "data": {
    "callId":       "call_01J...",
    "duration":     187,
    "status":       "completed",
    "transcript":   "Bonjour, je voudrais...",
    "summary":      "Client demande remboursement livraison J+3",
    "sentiment":    "positive",
    "recordingUrl": "https://cdn.telefon-ia.io/recordings/call_01J....mp3",
    "tags":         ["livraison", "remboursement"],
    "endedAt":      "2025-03-10T14:35:07.000Z"
  }
}

call.transferred WEBHOOK Déclenché quand l'IA transfère vers un agent humain

{
  "event":     "call.transferred",
  "id":        "evt_01J...",
  "createdAt": "2025-03-10T14:34:00.000Z",
  "data": {
    "callId":         "call_01J...",
    "transferredTo":  "+33756789099",
    "reason":         "Demande client — dossier complexe",
    "agentNote":      "Client Premium, 18 mois, frustré livraison J+5",
    "transferredAt":  "2025-03-10T14:34:00.000Z"
  }
}