Documentation

Documentation API

L'API Diamy vous permet d'intégrer nos fonctionnalités de téléphonie WebRTC dans vos applications et services. Cette documentation vous guidera à travers les différentes ressources et méthodes disponibles.

API REST

Notre API REST vous permet d'accéder à toutes les fonctionnalités de Diamy de manière programmatique.

Gestion des appels et des conférences
Accès à l'annuaire et aux contacts
Messagerie vocale et instantanée
Statistiques et rapports

En savoir plus →

Webhooks

Les webhooks vous permettent de recevoir des notifications en temps réel lorsque des événements se produisent dans votre système Diamy.

Notifications d'appels entrants et sortants
Événements de messagerie vocale
Mises à jour de statut de présence
Alertes système

En savoir plus →

Version actuelle

La version actuelle de l'API est v2.0. La v1.0 reste disponible mais sera dépréciée le 31 décembre 2023.

Authentification

L'API Diamy utilise OAuth 2.0 pour l'authentification. Vous devez obtenir un jeton d'accès avant de pouvoir effectuer des requêtes.

Obtenir des identifiants

Connectez-vous à votre console d'administration Diamy et accédez à Paramètres > API > Applications
Cliquez sur Créer une application
Remplissez les informations requises (nom, description, URL de redirection)
Sélectionnez les étendues (scopes) nécessaires pour votre application
Cliquez sur Créer
Notez le Client ID et le Client Secret qui seront générés

Obtenir un jeton d'accès

curl -X POST "https://api.diamy.fr/v2/oauth/token" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "grant_type=client_credentials&client_id=YOUR_CLIENT_ID&client_secret=YOUR_CLIENT_SECRET"

Réponse

{
  "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "token_type": "Bearer",
  "expires_in": 3600,
  "scope": "calls:read calls:write contacts:read"
}

Utiliser le jeton d'accès

Incluez le jeton d'accès dans l'en-tête Authorization de vos requêtes API :

curl -X GET "https://api.diamy.fr/v2/calls/recent" \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."

Sécurité

Ne partagez jamais votre Client Secret et ne l'incluez pas dans le code côté client. Utilisez toujours HTTPS pour toutes les communications avec l'API Diamy.

Ressources disponibles

Appels

Gérez les appels entrants et sortants, consultez l'historique et les statistiques.

Récupérer l'historique des appels
Initier un appel
Transférer un appel
Mettre fin à un appel
Obtenir des statistiques d'appels

Documentation des appels →

Contacts

Accédez et gérez votre annuaire de contacts et groupes.

Lister les contacts
Créer un contact
Mettre à jour un contact
Supprimer un contact
Gérer les groupes de contacts

Documentation des contacts →

Messagerie vocale

Gérez les messages vocaux, les annonces et les paramètres.

Récupérer les messages vocaux
Marquer un message comme lu
Télécharger un message vocal
Supprimer un message vocal
Configurer les paramètres de messagerie

Documentation de la messagerie vocale →

Utilisateurs

Gérez les utilisateurs, les permissions et les préférences.

Lister les utilisateurs
Créer un utilisateur
Mettre à jour un utilisateur
Désactiver un utilisateur
Gérer les permissions

Documentation des utilisateurs →

Exemple d'utilisation

Voici un exemple complet d'utilisation de l'API pour récupérer la liste des appels récents :

// Fonction pour obtenir un jeton d'accès
const getAccessToken = async () => {
  const params = new URLSearchParams();
  params.append('grant_type', 'client_credentials');
  params.append('client_id', 'YOUR_CLIENT_ID');
  params.append('client_secret', 'YOUR_CLIENT_SECRET');

  const response = await fetch('https://api.diamy.fr/v2/oauth/token', {
    method: 'POST',
    headers: {
      'Content-Type': 'application/x-www-form-urlencoded'
    },
    body: params
  });

  const data = await response.json();
  return data.access_token;
};

// Fonction pour récupérer les appels récents
const getRecentCalls = async () => {
  try {
    // Obtenir le jeton d'accès
    const accessToken = await getAccessToken();

    // Faire la requête pour récupérer les appels récents
    const response = await fetch('https://api.diamy.fr/v2/calls/recent?limit=10', {
      method: 'GET',
      headers: {
        'Authorization': `Bearer ${accessToken}`,
        'Content-Type': 'application/json'
      }
    });

    const data = await response.json();
    
    if (data.status === 'success') {
      // Traiter les données des appels
      console.log('Appels récents:', data.data.calls);
      
      // Exemple : Afficher la durée totale des appels
      const totalDuration = data.data.calls.reduce((total, call) => total + call.duration, 0);
      console.log(`Durée totale des appels: ${totalDuration} secondes`);
      
      return data.data.calls;
    } else {
      console.error('Erreur:', data.message);
    }
  } catch (error) {
    console.error('Erreur lors de la récupération des appels:', error);
  }
};

// Exécuter la fonction
getRecentCalls();

Gestion des erreurs

L'API Diamy utilise les codes de statut HTTP standard pour indiquer le succès ou l'échec d'une requête. En cas d'erreur, la réponse inclut un message descriptif et un code d'erreur.

Code HTTP	Description	Exemple
200 OK	La requête a réussi	`{ "status": "success", "data": { ... } }`
400 Bad Request	La requête est mal formée ou contient des paramètres invalides	`{ "status": "error", "code": "invalid_parameter", "message": "Le paramètre 'limit' doit être un nombre" }`
401 Unauthorized	Authentification requise ou invalide	`{ "status": "error", "code": "unauthorized", "message": "Jeton d'accès invalide ou expiré" }`
403 Forbidden	Accès refusé à la ressource demandée	`{ "status": "error", "code": "forbidden", "message": "Vous n'avez pas les permissions nécessaires" }`
404 Not Found	La ressource demandée n'existe pas	`{ "status": "error", "code": "not_found", "message": "Contact introuvable" }`
429 Too Many Requests	Limite de taux dépassée	`{ "status": "error", "code": "rate_limit_exceeded", "message": "Limite de taux dépassée. Réessayez dans 60 secondes" }`
500 Internal Server Error	Erreur interne du serveur	`{ "status": "error", "code": "server_error", "message": "Une erreur interne s'est produite" }`

Conseil

Implémentez toujours une gestion d'erreurs robuste dans vos applications qui utilisent l'API Diamy. Vérifiez le code de statut HTTP et le message d'erreur pour diagnostiquer les problèmes.

Limites et quotas

Pour garantir la stabilité et la disponibilité de notre API, nous appliquons des limites de taux. Ces limites varient en fonction de votre plan d'abonnement.

Plan	Limite de requêtes	Période
Starter	100 requêtes	Par minute
Pro	500 requêtes	Par minute
Enterprise	2000 requêtes	Par minute

Si vous dépassez ces limites, vous recevrez une réponse avec le code d'état HTTP 429 (Too Many Requests). L'en-tête Retry-After indiquera le nombre de secondes à attendre avant de réessayer.

Important

Implémentez une logique de backoff exponentiel dans votre code pour gérer les limites de taux de manière élégante. Cela permettra à votre application de continuer à fonctionner même en cas de dépassement temporaire des limites.

Bonnes pratiques

Optimisation des performances

Utilisez la pagination pour les requêtes qui retournent de grandes quantités de données
Spécifiez les champs exacts dont vous avez besoin avec le paramètre fields
Mettez en cache les réponses qui ne changent pas fréquemment
Utilisez des connexions persistantes pour réduire la latence
Compressez les données avec gzip pour réduire la bande passante

Sécurité

Stockez les jetons d'accès de manière sécurisée
Renouvelez régulièrement vos jetons d'accès
Utilisez uniquement les étendues (scopes) nécessaires pour votre application
Validez toutes les entrées utilisateur avant de les envoyer à l'API
Implémentez une journalisation des appels API pour la détection des anomalies

Ressources supplémentaires

SDK et bibliothèques

Nous proposons des SDK officiels pour faciliter l'intégration de l'API Diamy dans vos applications.

Outils de développement

Accélérez votre développement avec nos outils et ressources.

Support

Besoin d'aide avec l'API ? Nous sommes là pour vous.

Restez informé

Abonnez-vous à notre newsletter pour développeurs pour recevoir les dernières mises à jour, fonctionnalités et bonnes pratiques concernant l'API Diamy.

← Documentation Introduction à l'API →