• Créez vos propres intégrations avec Voys
• Les quatre outils
• API : votre logiciel récupère quelque chose chez nous
• Notifications d'appel : nous vous envoyons quelque chose
• Webhook du plan de routage : nous vous posons une question pendant que le téléphone sonne encore
• Appel en un clic : appelez en un seul clic
• Vue d'ensemble des API
• Que pourriez-vous créer avec cela ?
• Développer vous-même ou opter pour une solution clé en main ?
• Responsabilité et accompagnement
• FAQ

Créez vos propres intégrations avec Voys

Vous aimeriez que votre CRM affiche qui vous appelle avant de décrocher ? Ou qu'un appel manqué arrive automatiquement dans Slack ? C'est possible. Voys vous propose quatre outils qui permettent à vos logiciels et notre système téléphonique de communiquer entre eux : les API, les notifications d'appel, le webhook du plan de routage, et l'Appel en un clic.

Cette page va plus loin que les bases : vous y trouverez également les URL de base, les endpoints et des exemples de requêtes.

Bon à savoir avant de commencer :

1. Cette page explique ce qui est possible avec nos API, mais elle ne constitue pas une spécification technique. Les endpoints, champs et exemples peuvent évoluer. Vous trouverez toujours la documentation actuelle sur le portail OpenAPI, que nous vous conseillons d'utiliser comme référence lorsque vous commencerez à développer (ou de partager avec votre développeur).
2. Veuillez garder à l'esprit que ce que vous construisez avec ces API, et la façon dont vous le faites, relève de votre propre responsabilité. Voys fournit la plateforme et la documentation, mais nous ne pouvons pas assurer le support d'intégrations personnalisées que vous (ou quelqu'un que vous engagez) développez. Vous trouverez plus d'informations à ce sujet vers le bas de cette page.

Les quatre outils

API : votre logiciel récupère quelque chose chez nous

Une API, c'est un peu comme un guichet où votre logiciel peut récupérer ou déposer des données : l'historique des appels, les contacts, qui est disponible. Votre système pose une question, nous répondons.

Voys dispose de treize API, réparties en deux générations avec chacune sa propre adresse :

• Les API les plus récentes fonctionnent sur api.eu-production.holodeck.voys.nl (Carnet de contacts, Statut utilisateur, Stockage des transcriptions d'appels).
• Les autres fonctionnent sur api.voys.nl/api/v2 (Appels, Enregistrement des appels, Utilisateurs, Comptes VoIP, Numéros d'identifiant du correspondant, Utilisateur Webphone, ainsi que les API partenaires pour l'intégration).

L'authentification fonctionne de la même manière partout : un en-tête Authorization: Bearer <votre-token> ou Authorization: Token <votre-token>. Par exemple, voici comment récupérer votre propre historique d'appels des cinq dernières semaines :

GET https://api.voys.nl/api/v2/call/personalized/
Authorization: Bearer <your-token>

Cela renvoie, entre autres, direction, answered, start_time, duration_in_seconds, et qui a appelé qui. Vous trouverez la liste complète des endpoints et des champs sur le portail OpenAPI.

Notifications d'appel : nous vous envoyons quelque chose

Cela fonctionne dans l'autre sens : dès qu'un événement se produit sur un appel, nous l'envoyons automatiquement à l'URL de votre choix. Votre logiciel n'a pas besoin de poser la question. Nous le signalons nous-mêmes, sous forme de requête POST avec un corps JSON.

Il y a six moments par appel : créé (entrant uniquement), sonne, en cours, transfert accompagné, transfert direct, et terminé (avec un motif : terminé, occupé, sans réponse, échoué, annulé ou abandonné). Voys Intelligence est-il activé ? Dans ce cas, deux notifications supplémentaires suivent après la fin de l'appel : call_transcription une fois la transcription prête, et summary une fois le résumé IA prêt.

Chaque notification contient au minimum un call_id, un timestamp, un status, une direction, ainsi que des détails sur l'appelant et la destination. Vous pouvez également utiliser ce call_id pour récupérer l'enregistrement ou la transcription du même appel via les API correspondantes, de sorte que les notifications et les API fonctionnent ensemble ici.

Vous pouvez configurer cela vous-même dans Freedom : Intégration -> Notifications d'appel -> Ajouter. Choisissez Personnalisé pour votre propre URL, ou Robin pour une intégration directe.

Webhook du plan de routage : nous vous posons une question pendant que le téléphone sonne encore

Cela ressemble beaucoup aux notifications d'appel, mais fonctionne dans l'autre sens. Et cela se produit suffisamment tôt pour pouvoir encore agir sur l'appel : pendant qu'on vous appelle, nous envoyons une requête GET à votre serveur pour savoir où l'appel doit être dirigé. Cela ne fonctionne que pour les appels entrants, et à un seul endroit précis du plan de routage. C'est le seul moment où votre système peut réellement influencer l'appel.

Les deux sont faciles à confondre, voici donc la différence : le webhook route l'appel (GET, entrant uniquement, demande une décision), tandis que les notifications rapportent simplement ce qui s'est passé (POST, toutes les directions, aucune influence sur l'appel). Vous pouvez les utiliser côte à côte sur le même appel sans aucun problème.

Appel en un clic : appelez en un seul clic

Cela permet à votre logiciel de lancer un appel depuis l'appareil, l'application ou le Webphone d'une personne. Pensez à un bouton d'appel à côté de chaque numéro de téléphone dans votre CRM.

• Adresse : https://api.voipgrid.nl/api/clicktodial/. Bon à savoir : il s'agit d'un domaine différent des autres.
• Authentification : Authorization: Token <adresse-e-mail>:<votre-token>. Cela fonctionne un peu différemment des autres API : l'adresse e-mail de l'utilisateur en fait partie, séparée par deux points.

POST https://api.voipgrid.nl/api/clicktodial/
Authorization: Token name@company.com:<your-token>
Content-Type: application/json

{ "b_number": "+31612345678" }

Cela renvoie un callid. Vous souhaitez vérifier comment se passe l'appel ? Dans ce cas, interrogez GET /api/clicktodial/{callid}/. Vous obtiendrez un statut en retour : en cours de connexion (dialing_a, dialing_b), connecté (connected), ou terminé/échoué (disconnected, failing_a, failing_b). Encore plus simple : laissez les notifications d'appel vous indiquer quand l'appel sonne, est décroché ou se termine.

Vue d'ensemble des API

Dix des treize API sont destinées à vos propres logiciels. Les trois autres (client partenaire, numéro de téléphone et plan de routage d'intégration) sont réservées aux partenaires qui intègrent de nouveaux clients, nous ne les avons donc pas incluses ici.

Vous trouverez tous les détails, champs et paramètres de chaque API sur le portail OpenAPI.

Que pourriez-vous créer avec cela ?

Reconnaître automatiquement vos correspondants. Dès qu'une personne appelle, votre système recherche le numéro dans le répertoire partagé (API Contactbook) et affiche le nom ainsi que les informations client avant même que l'appel ne soit décroché. Vous souhaitez également router l'appel en fonction de l'appelant ? Dans ce cas, combinez cette fonctionnalité avec le webhook du plan de routage.

Appel manqué, alerte instantanée. Une notification ended avec le motif no-answer arrive sur votre URL. Vous recherchez le numéro via l'API Contactbook et publiez le nom ainsi que le numéro dans le canal de votre équipe.

Appeler depuis votre CRM, avec suivi en temps réel. Un collègue clique sur un numéro, et votre intégration envoie un POST à l'Appel en un clic. Plutôt que d'interroger GET /clicktodial/{callid}/ en boucle, vous pouvez laisser les notifications d'appel (ringing, in-progress, ended) mettre à jour la fiche CRM.

Enregistrement, transcription et résumé dans la fiche client, automatiquement. Voys Intelligence est activé ? Une notification call recording created arrive après l'appel, avec une recording_url prête à l'emploi, suivie de call_transcription et summary dès qu'ils sont disponibles. Il ne vous reste plus qu'à récupérer les versions finales via l'API Call Transcription Storage et à les ajouter à la fiche.

Développer vous-même ou opter pour une solution clé en main ?

Vous avez un développeur ? Il peut se lancer immédiatement sur le portail OpenAPI, où se trouve la documentation technique actuelle des treize API. Chacun peut trouver son propre jeton API dans Freedom, sous les paramètres personnels (jeton API). Ce jeton est la clé que votre logiciel utilise pour s'identifier auprès de nous, alors traitez-le comme un mot de passe : gardez-le pour vous et assurez-vous qu'il ne se retrouve jamais dans du code accessible à d'autres personnes.

Pas de développeur sous la main ? Aucun problème, vous ne devez pas repartir de zéro. Des intégrations prêtes à l'emploi existent déjà pour des outils populaires, tels que Zapier, Slack, HubSpot, Bubble, ROBIN et Microsoft Teams. Avant de demander à quelqu'un de développer quelque chose, jetez un œil à cette page d'aide sur les intégrations. Il existe peut-être déjà une solution pour votre système.

Responsabilité et accompagnement

Voys fournit les API, les notifications d'appel, le webhook et la documentation de tout cela. C'est vous qui décidez ce que vous construisez avec, avec qui et comment. Cela signifie également que la responsabilité vous incombe.

Concrètement, cela veut dire :

• Nous sommes là pour vous aider concernant : l'accessibilité de l'API, le bon fonctionnement de votre jeton, l'activation de Voys Intelligence, ou encore une divergence entre un endpoint ou un code de statut et la documentation.
• Nous ne pouvons pas vous aider pour : les bugs dans votre propre code, un flux Zapier que vous avez configuré vous-même et qui ne fonctionne plus, ou une intégration développée par un tiers pour vous et qui n'est plus maintenue.

Vous êtes bloqué et vous ne savez pas d'où vient le problème ? N'hésitez surtout pas à nous contacter. Nous réfléchirons volontiers avec vous, même si le développement et la maintenance de votre propre intégration restent de votre côté (ou de celui de votre développeur).

FAQ

Dois-je savoir coder ? Non. Cette page vous aide à comprendre ce qui est possible et, dans les grandes lignes, comment c'est construit. Le développement en lui-même est assuré par un développeur, ou vous utilisez une intégration prête à l'emploi.

Mon jeton API est-il sécurisé ? Oui, pour autant que vous le gardiez secret. Toute personne disposant de ce jeton peut récupérer des données ou modifier des paramètres en votre nom. Vous pensez que votre jeton a peut-être été compromis ? Vous pouvez en demander un nouveau dans Freedom.

Pourquoi je ne reçois pas de résumés de mes appels ? Dans presque tous les cas, c'est parce que Voys Intelligence n'est pas encore activé. Il serait judicieux de vérifier cela en premier, avant d'aller plus loin.

Puis-je faire supprimer automatiquement un enregistrement ou une transcription ? Ce ne serait pas possible, mais ce n'est pas nécessaire : ils expirent d'eux-mêmes après la période de rétention.

Que se passe-t-il si mon intégration cesse de fonctionner ? Vérifiez d'abord si le problème vient de chez nous : le statut de l'API, la validité de votre jeton, ou des paramètres comme Voys Intelligence. Le problème se situe dans votre propre code ou dans une intégration tierce ? Dans ce cas, c'est à vous ou à votre développeur de le résoudre. Vous pouvez en lire davantage sous « Responsabilité et accompagnement » ci-dessus.

Y a-t-il des limites de taux, et que se passe-t-il en cas de 429 ? Certains endpoints (comme Call Recording) renvoient un 429 throttled si vous les appelez trop souvent. Nous n'avons pas publié les limites exactes, ni précisé si un en-tête Retry-After est inclus. Par précaution, prévoyez une nouvelle tentative avec temporisation progressive.

Puis-je vérifier si un enregistrement, une transcription ou un résumé est déjà prêt ? Pas pour le moment : il n'y a ni champ de statut, ni filtre « depuis X ». La bonne nouvelle, c'est que la notification d'appel vous prévient automatiquement dès que quelque chose est prêt, vous n'avez donc pas besoin d'interroger le système en boucle.