Clés API et portées

L'API REST Ringhum permet à vos propres systèmes d'interagir avec votre espace de travail : lister les appels et les transcriptions, créer des assistants, prendre des rendez-vous, gérer les contacts, passer des appels sortants et plus encore. Chaque requête est authentifiée avec une clé API qui appartient à un espace de travail. Cet article couvre la création des clés et les conventions communes à chaque point de terminaison. La référence complète des points de terminaison se trouve sur /docs.

Qui peut gérer les clés

L'API est disponible sur tous les forfaits. Ce qu'une clé peut faire reste limité par votre forfait : par exemple, créer un assistant au-delà de la limite de votre forfait renvoie une erreur.

Créer une clé API

1. Ouvrez Développeurs dans la barre latérale.
2. Dans la carte Clés API, cliquez sur Créer une clé.
3. Saisissez un Nom de la clé qui indique où la clé est utilisée, par exemple « Serveur de production ».
4. Sous Portées, cochez read, write ou les deux.
5. Cliquez sur Créer une clé.
6. Copiez la clé depuis l'encadré vert et conservez-la en lieu sûr, comme le coffre de secrets de votre serveur. Cliquez sur Terminé.

Important : la clé n'est affichée qu'une seule fois. Ringhum n'en conserve qu'une empreinte, elle ne peut donc plus être affichée par la suite. Si vous la perdez, créez une nouvelle clé et révoquez l'ancienne.

Les clés commencent par ck_live_. Le tableau Clés API affiche le nom de chaque clé, ses premiers caractères, ses portées, sa dernière utilisation et son statut : Active ou Révoquée.

Portées

Toute clé peut appeler les points de terminaison qui ne font que lire. Les points de terminaison qui créent, modifient ou suppriment quelque chose nécessitent la portée write. Par exemple, passer un appel, envoyer un message, prendre un rendez-vous ou mettre à jour un assistant. La référence sur /docs signale ces points de terminaison. Une clé sans write reçoit une erreur 403 sur ceux-ci.

Donnez à chaque système l'accès le plus restreint dont il a besoin. Un tableau de bord de reporting n'a besoin que de read.

Révoquer une clé

1. Sur Développeurs, trouvez la clé dans le tableau Clés API.
2. Cliquez sur Révoquer et confirmez.

Les requêtes utilisant la clé échouent immédiatement avec 401. Les clés révoquées restent dans la liste, marquées Révoquée, afin que vous puissiez consulter leur historique. Une clé ne peut pas être modifiée : pour changer ses portées, créez une nouvelle clé et révoquez l'ancienne.

Faire des requêtes

• URL de base : https://ringhum.com/api/v1
• Authentification : envoyez la clé comme jeton Bearer : Authorization: Bearer ck_live_…
• Format : JSON en entrée et en sortie. Envoyez Content-Type: application/json avec un corps de requête.
• Les horaires sont au format ISO 8601 en UTC. Les numéros de téléphone sont au format E.164, par exemple +14155550132. Les identifiants sont des entiers.
• Les mises à jour utilisent PATCH avec uniquement les champs que vous souhaitez modifier.
• Chaque réponse porte un en-tête X-Request-Id. Indiquez-le lorsque vous contactez le support.

curl "https://ringhum.com/api/v1/calls?per_page=10" \
  -H "Authorization: Bearer ck_live_…"

Pour vérifier à quel espace de travail appartient une clé, appelez GET /me.

Réponses et pagination

Un objet unique est renvoyé sous la forme {"data": {…}}. Les listes paginées sont renvoyées avec un objet meta :

{
  "data": [ … ],
  "meta": {
    "current_page": 1,
    "last_page": 4,
    "per_page": 25,
    "total": 87,
    "next_page_url": "https://ringhum.com/api/v1/calls?page=2",
    "prev_page_url": null
  }
}

Utilisez page et per_page pour parcourir les résultats. per_page vaut 25 par défaut et peut aller jusqu'à 100 au maximum.

Erreurs

Chaque échec a la même forme, avec un type stable que vous pouvez vérifier dans votre code :

{
  "error": {
    "type": "validation_error",
    "message": "The to field format is invalid.",
    "errors": { "to": ["Use E.164 format, e.g. +15551234567."] }
  }
}

Limites de débit

Vous pouvez effectuer 120 requêtes par minute. Les réponses incluent les en-têtes X-RateLimit-Limit et X-RateLimit-Remaining. Au-delà de la limite, vous recevez un 429 avec un en-tête Retry-After indiquant le nombre de secondes à attendre.

Astuce : n'interrogez pas l'API en boucle pour connaître le résultat d'un appel. Ajoutez un webhook pour call.ended et Ringhum vous envoie le résumé et la transcription dès que l'appel est terminé. Voir Webhooks.

Questions courantes

Existe-t-il une spécification lisible par machine ? Oui. La description OpenAPI 3.1 se trouve sur /api/v1/openapi.json et ne nécessite aucune clé. Vous pouvez en générer un client.

Une clé cesse-t-elle de fonctionner si la personne qui l'a créée quitte l'entreprise ? Non. Les clés appartiennent à l'espace de travail et continuent de fonctionner jusqu'à ce qu'elles soient révoquées. Révoquez les clés auxquelles vous ne faites plus confiance, surtout lorsqu'une personne qui y avait accès s'en va.

Puis-je utiliser l'API depuis une page web ? Non. Toute personne ouvrant la page pourrait lire la clé. Appelez l'API depuis votre serveur.