Documentation API Cloud Call

L'API Cloud Call 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.cloud-call.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.cloud-call.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

Cloud Call 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.cloud-call.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"
  }
}