API Appels

L'API Appels vous permet de gérer les appels téléphoniques, d'accéder à l'historique des appels et d'obtenir des statistiques détaillées.

Prérequis

Pour utiliser ces endpoints, votre application doit disposer des étendues (scopes) calls:read et/ou calls:write.

Récupérer les appels récents

GET/v2/calls/recent

Récupère la liste des appels récents pour l'utilisateur ou l'organisation, triés par date (du plus récent au plus ancien).

Paramètres de requête

Paramètre	Type	Requis	Description
limit	Integer	Non	Nombre maximum d'appels à retourner (défaut: 20, max: 100)
offset	Integer	Non	Nombre d'appels à sauter (pour la pagination)
direction	String	Non	Filtrer par direction: "inbound", "outbound" ou "all" (défaut: "all")
status	String	Non	Filtrer par statut: "answered", "missed", "voicemail" ou "all" (défaut: "all")
from	ISO Date	Non	Date de début (format ISO 8601)
to	ISO Date	Non	Date de fin (format ISO 8601)
user_id	String	Non	ID de l'utilisateur (pour les administrateurs uniquement)

Exemple de requête

curl -X GET "https://api.diamy.fr/v2/calls/recent?limit=10&direction=inbound" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json"

Réponse

{
  "status": "success",
  "data": {
    "calls": [
      {
        "id": "call_123456",
        "direction": "inbound",
        "from": {
          "number": "+33123456789",
          "name": "Jean Dupont"
        },
        "to": {
          "number": "+33987654321",
          "name": "Service Client"
        },
        "duration": 142,
        "status": "answered",
        "recording_url": "https://api.diamy.fr/v2/calls/call_123456/recording",
        "notes": "Client demande information sur le produit X",
        "tags": ["important", "suivi-requis"],
        "timestamp": "2023-06-15T14:32:21Z"
      },
      {
        "id": "call_123457",
        "direction": "inbound",
        "from": {
          "number": "+33678901234",
          "name": "Marie Martin"
        },
        "to": {
          "number": "+33987654321",
          "name": "Service Client"
        },
        "duration": 0,
        "status": "missed",
        "recording_url": null,
        "notes": "",
        "tags": [],
        "timestamp": "2023-06-15T13:45:12Z"
      }
      // ... autres appels
    ],
    "pagination": {
      "total": 42,
      "limit": 10,
      "offset": 0,
      "has_more": true
    }
  }
}

Codes de statut

Code	Description
200	Succès
400	Paramètres invalides
401	Non autorisé
403	Accès refusé
429	Trop de requêtes

Récupérer les détails d'un appel

GET/v2/calls/{call_id}

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

Paramètres de chemin

Paramètre	Type	Requis	Description
call_id	String	Oui	Identifiant unique de l'appel

Exemple de requête

curl -X GET "https://api.diamy.fr/v2/calls/call_123456" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json"

Réponse

{
  "status": "success",
  "data": {
    "call": {
      "id": "call_123456",
      "direction": "inbound",
      "from": {
        "number": "+33123456789",
        "name": "Jean Dupont",
        "contact_id": "contact_789012"
      },
      "to": {
        "number": "+33987654321",
        "name": "Service Client",
        "user_id": "user_345678"
      },
      "duration": 142,
      "status": "answered",
      "recording_url": "https://api.diamy.fr/v2/calls/call_123456/recording",
      "notes": "Client demande information sur le produit X",
      "tags": ["important", "suivi-requis"],
      "timestamp": "2023-06-15T14:32:21Z",
      "ended_at": "2023-06-15T14:34:43Z",
      "queue": {
        "id": "queue_123",
        "name": "Support Technique",
        "wait_time": 45
      },
      "transferred": false,
      "transfer_history": [],
      "custom_data": {
        "crm_ticket_id": "TKT-12345",
        "priority": "high"
      }
    }
  }
}

Initier un appel

POST/v2/calls

Initie un nouvel appel téléphonique.

Corps de la requête

Paramètre	Type	Requis	Description
to	String	Oui	Numéro de téléphone à appeler (format E.164)
from	String	Non	Numéro de téléphone à utiliser comme appelant (doit être un numéro valide de votre compte)
user_id	String	Non	ID de l'utilisateur qui passe l'appel (pour les administrateurs uniquement)
record	Boolean	Non	Indique si l'appel doit être enregistré (défaut: false)
callback_url	String	Non	URL à appeler lorsque le statut de l'appel change
custom_data	Object	Non	Données personnalisées à associer à l'appel

Exemple de requête

curl -X POST "https://api.diamy.fr/v2/calls" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "to": "+33123456789",
    "from": "+33987654321",
    "record": true,
    "custom_data": {
      "crm_contact_id": "CRM-12345",
      "campaign": "summer_promo"
    }
  }'

Réponse

{
  "status": "success",
  "data": {
    "call": {
      "id": "call_789012",
      "status": "initiating",
      "direction": "outbound",
      "from": {
        "number": "+33987654321",
        "name": "Service Client"
      },
      "to": {
        "number": "+33123456789",
        "name": "Jean Dupont"
      },
      "timestamp": "2023-06-15T15:30:00Z",
      "custom_data": {
        "crm_contact_id": "CRM-12345",
        "campaign": "summer_promo"
      }
    }
  }
}

Important

L'initiation d'un appel est asynchrone. L'API retourne immédiatement avec un statut "initiating", mais l'appel peut prendre quelques secondes pour être établi. Utilisez le webhook ou le callback_url pour être notifié des changements de statut.

Terminer un appel

DELETE/v2/calls/{call_id}

Termine un appel en cours.

Paramètres de chemin

Paramètre	Type	Requis	Description
call_id	String	Oui	Identifiant unique de l'appel

Exemple de requête

curl -X DELETE "https://api.diamy.fr/v2/calls/call_789012" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

Réponse

{
  "status": "success",
  "data": {
    "call": {
      "id": "call_789012",
      "status": "ended",
      "ended_at": "2023-06-15T15:32:45Z"
    }
  }
}

Transférer un appel

POST/v2/calls/{call_id}/transfer

Transfère un appel en cours vers un autre numéro ou utilisateur.

Paramètres de chemin

Paramètre	Type	Requis	Description
call_id	String	Oui	Identifiant unique de l'appel

Corps de la requête

Paramètre	Type	Requis	Description
to	String	Oui	Numéro de téléphone ou ID d'utilisateur vers lequel transférer l'appel
type	String	Non	Type de transfert: "blind" (immédiat) ou "attended" (assisté) (défaut: "blind")
callback_url	String	Non	URL à appeler lorsque le transfert est terminé

Exemple de requête

curl -X POST "https://api.diamy.fr/v2/calls/call_789012/transfer" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "to": "+33456789012",
    "type": "blind"
  }'

Réponse

{
  "status": "success",
  "data": {
    "call": {
      "id": "call_789012",
      "status": "transferring",
      "transfer_to": "+33456789012",
      "transfer_type": "blind"
    }
  }
}

Statistiques d'appels

GET/v2/calls/stats

Récupère des statistiques agrégées sur les appels pour une période donnée.

Paramètres de requête

Paramètre	Type	Requis	Description
from	ISO Date	Oui	Date de début (format ISO 8601)
to	ISO Date	Oui	Date de fin (format ISO 8601)
group_by	String	Non	Regrouper par: "day", "week", "month" ou "none" (défaut: "none")
user_id	String	Non	ID de l'utilisateur (pour les administrateurs uniquement)

Exemple de requête

curl -X GET "https://api.diamy.fr/v2/calls/stats?from=2023-06-01T00:00:00Z&to=2023-06-30T23:59:59Z&group_by=day" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json"

Réponse

{
  "status": "success",
  "data": {
    "stats": {
      "total_calls": 245,
      "total_duration": 28350,
      "average_duration": 115.7,
      "inbound_calls": 142,
      "outbound_calls": 103,
      "answered_calls": 198,
      "missed_calls": 32,
      "voicemail_calls": 15,
      "by_day": [
        {
          "date": "2023-06-01",
          "total_calls": 12,
          "inbound_calls": 7,
          "outbound_calls": 5,
          "total_duration": 1450
        },
        {
          "date": "2023-06-02",
          "total_calls": 15,
          "inbound_calls": 9,
          "outbound_calls": 6,
          "total_duration": 1820
        }
        // ... autres jours
      ]
    }
  }
}

Conseil

Pour une intégration plus efficace, utilisez les webhooks pour recevoir des notifications en temps réel sur les événements d'appels plutôt que de sonder régulièrement l'API.

← Documentation API API Contacts →