đź“ž API Click-to-Call

Documentation complète de l'API REST pour les appels WebRTC

Environnement: preprod Version: 41a9f066 Port: 3025

đź“‹ Vue d'ensemble

Cette API permet de gérer les appels téléphoniques via WebRTC en utilisant Infobip. Elle offre des fonctionnalités complètes pour l'initialisation, le suivi et la gestion des appels.

Base URL: http://localhost:3025

🔑 Authentification

L'API utilise une clé API Infobip stockée dans les variables d'environnement (INFOBIP_API_KEY). Cette clé est requise pour générer les tokens WebRTC et initier les appels.

đź“Š Statuts d'appel

Les appels peuvent avoir les statuts suivants :

INITIATED RINGING ESTABLISHED COMPLETED FAILED HANGUP

🛣️ Endpoints

POST /click-to-call/token

Génère un token WebRTC pour un utilisateur. Ce token est nécessaire pour établir une connexion WebRTC via Infobip.

Body (JSON) :

Paramètre Type Requis Description
user_id string Oui Identité unique de l'utilisateur WebRTC
displayName string Non Nom d'affichage de l'utilisateur
applicationId string Non ID de l'application Infobip

Exemple de requĂŞte :

POST /click-to-call/token
Content-Type: application/json

{
  "user_id": "user123",
  "displayName": "John Doe",
  "applicationId": "app-id-123"
}

Exemple de réponse (200) :

{
  "success": true,
  "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "expiresIn": 3600
}
POST /click-to-call/initiate

Initialise un nouvel appel et crée un enregistrement dans l'historique avec le statut INITIATED.

Body (JSON) :

Paramètre Type Requis Description
user_id string Oui Identité de l'utilisateur qui initie l'appel
phoneNumber string Oui Numéro de téléphone à appeler (format E164, ex: +33123456789)
fromNumber string Non Numéro d'origine de l'appel
metadata object Non Métadonnées supplémentaires (stockées en JSON)

Exemple de requĂŞte :

POST /click-to-call/initiate
Content-Type: application/json

{
  "user_id": "user123",
  "phoneNumber": "+33123456789",
  "fromNumber": "+33987654321",
  "metadata": {
    "campaign": "support",
    "source": "website"
  }
}
PUT /click-to-call/update-status/:id

Met à jour le statut d'un appel existant. Utilisé pour suivre l'évolution de l'appel (RINGING, ESTABLISHED, etc.).

Paramètres URL :

Paramètre Type Description
id integer ID de l'enregistrement d'appel dans la base de données

Body (JSON) :

Paramètre Type Requis Description
status string Oui Nouveau statut (voir statuts disponibles ci-dessus)
callId string Non ID de l'appel Infobip
errorCode string Non Code d'erreur si l'appel a échoué
errorMessage string Non Message d'erreur détaillé
PUT /click-to-call/end/:id

Termine un appel et calcule automatiquement la durée en secondes. Met à jour les timestamps de fin (UTC et local).

Paramètres URL :

Paramètre Type Description
id integer ID de l'enregistrement d'appel

Body (JSON) - Optionnel :

Paramètre Type Description
status string Statut final (par défaut: COMPLETED)
errorCode string Code d'erreur si l'appel a échoué
errorMessage string Message d'erreur détaillé
GET /click-to-call/history

Récupère l'historique des appels avec filtres et pagination. Retourne les appels triés par date de début (plus récents en premier).

Query Parameters :

Paramètre Type Requis Description
user_id string Non Filtrer par identité utilisateur
phoneNumber string Non Filtrer par numéro appelé
status string Non Filtrer par statut
startDate string (ISO 8601) Non Date de début (ex: 2024-01-01T00:00:00Z)
endDate string (ISO 8601) Non Date de fin
page integer Non Numéro de page (défaut: 1, min: 1, max: 10000)
limit integer Non Nombre d'éléments par page (défaut: 50, min: 1, max: 500)

Exemple de requĂŞte :

GET /click-to-call/history?user_id=user123&status=COMPLETED&page=1&limit=20
GET /click-to-call/call/:id

Récupère les détails complets d'un appel spécifique par son ID.

Paramètres URL :

Paramètre Type Description
id integer ID de l'enregistrement d'appel
GET /click-to-call/stats

Récupère les statistiques agrégées des appels (nombre total, durée moyenne, appels réussis/échoués, etc.).

Query Parameters :

Paramètre Type Requis Description
user_id string Non Filtrer par identité utilisateur
startDate string (ISO 8601) Non Date de début pour la période d'analyse
endDate string (ISO 8601) Non Date de fin pour la période d'analyse
POST /click-to-call/records-webhook

Webhook pour recevoir les notifications d'enregistrements audio des appels depuis Infobip.

Cette route est destinée à être appelée par Infobip, pas directement par les clients.

GET /click-to-call-demo

Page de démonstration interactive pour tester les fonctionnalités Click-to-Call.

⚠️ Codes d'erreur

Code HTTP Description
200 Succès - Requête traitée avec succès
400 Requête invalide - Paramètres manquants ou invalides
404 Ressource non trouvée - Appel ou enregistrement inexistant
500 Erreur serveur - Erreur interne du serveur

📝 Format des réponses

Toutes les réponses suivent un format JSON standardisé :

Réponse de succès :

{
  "success": true,
  "data": { ... }
}

RĂ©ponse d'erreur :

{
  "success": false,
  "error": "Message d'erreur descriptif"
}