• Créez vos propres intégrations avec Voys
• Les quatre composants
• 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 : composez en un seul clic
• Les API en un coup d'œil
• Que pouvez-vous créer avec cela ?
• Le créer vous-même ou utiliser une solution toute faite ?
• Responsabilité et assistance
• FAQ

Créez vos propres intégrations avec Voys

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

Cette page va au-delà des 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 qu'il est possible de faire avec nos API, mais ce n'est pas une spécification technique. Les endpoints, les champs et les exemples peuvent évoluer. Vous trouverez toujours la documentation à jour sur le portail OpenAPI, référez-vous-y lorsque vous développerez (ou transmettez-la à votre développeur).
2. Gardez à l'esprit que ce que vous construisez avec ces API, et la manière 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) auriez développées. Vous en saurez plus à ce sujet en bas de page.

Les quatre composants

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

Une API, c'est un guichet où votre logiciel peut récupérer ou déposer des données : historique d'appels, contacts, statut de disponibilité. Votre système pose la 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 (Contactbook, User status, Call transcription storage).
• Les autres fonctionnent sur api.voys.nl/api/v2 (Call, Call recording, Users, VoIP accounts, Caller ID numbers, Webphone user, et les API partenaires pour l'onboarding).

L'authentification fonctionne partout de la même manière : 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 survient sur un appel, nous l'envoyons automatiquement à l'URL de votre choix. Votre logiciel n'a pas besoin de demander. Nous signalons l'information nous-mêmes, sous forme de requête POST avec un corps JSON.

Il y a six moments par appel : created (entrant uniquement), ringing, in progress, warm transfer, cold transfer et ended (avec un motif : completed, busy, no answer, failed, cancelled ou abandoned). Voys Intelligence est-il activé ? 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, et des informations sur l'appelant et la destination. Vous pouvez aussi utiliser ce call_id pour récupérer l'enregistrement ou la transcription du même appel via les API correspondantes, de sorte que notifications et API travaillent ici de concert.

Vous pouvez configurer cela vous-même dans Freedom : Intégration -> Notifications d'appel -> Ajouter. Choisissez Custom 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 survient suffisamment tôt pour agir encore sur l'appel : pendant qu'on vous appelle, nous envoyons une requête GET à votre serveur pour lui demander 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.

Il est facile de les confondre, voici donc la différence : le webhook route l'appel (GET, entrant uniquement, demande une décision), tandis que les notifications rapportent seulement ce qui s'est passé (POST, toutes 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 : composez en un seul clic

Cela permet à votre logiciel de lancer un appel depuis l'appareil, l'application ou le Webphone de quelqu'un. Imaginez 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 voulez vérifier comment se passe l'appel ? Interrogez alors GET /api/clicktodial/{callid}/. Vous obtiendrez un statut : en 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.

Les API en un coup d'œil

Dix des treize API sont destinées à vos propres logiciels. Les trois autres (partner client, phone number et onboarding dial plan) sont réservées aux partenaires qui intègrent de nouveaux clients, nous les avons donc exclues ici.

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

Que pouvez-vous créer avec cela ?

Reconnaître automatiquement les correspondants. Dès qu'un appel arrive, votre système recherche le numéro dans le carnet d'adresses partagé (API Contactbook) et affiche le nom et les informations client avant même que l'appel ne soit décroché. Vous souhaitez également router l'appel en fonction de l'identité du correspondant ? Combinez cela avec le webhook du plan de routage.

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

Appelez depuis votre CRM, avec statut en direct. Un collègue clique sur un numéro, et votre intégration envoie un POST à l'Appel en un clic. Au lieu d'interroger GET /clicktodial/{callid}/ en continu, vous pouvez laisser les notifications d'appel (ringing, in-progress, ended) mettre à jour la fiche CRM.

Enregistrement, transcription et résumé arrivent automatiquement dans la fiche client. Vous avez activé Voys Intelligence ? Une notification call recording created arrive après l'appel avec une recording_url prête à l'emploi, suivie de call_transcription et summary une fois ceux-ci disponibles. Vous récupérez ensuite les versions finales via l'API Call Transcription Storage et les ajoutez à la fiche.

Le créer vous-même ou utiliser une solution toute faite ?

Vous avez un développeur ? Il peut démarrer tout de suite sur le portail OpenAPI, où vous trouverez la documentation technique actuelle pour les 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, donc traitez-le comme un mot de passe : gardez-le pour vous et assurez-vous qu'il ne se retrouve jamais dans du code visible par d'autres.

Pas de développeur sous la main ? Pas d'inquiétude, vous n'avez pas besoin de repartir de zéro. Des intégrations prêtes à l'emploi existent déjà pour des outils populaires, comme Zapier, Slack, HubSpot, Bubble, ROBIN et Microsoft Teams. Avant de demander à quelqu'un de créer 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 assistance

Voys fournit les API, les notifications d'appel, le webhook et la documentation pour l'ensemble. Vous décidez de ce que vous créez avec, avec qui vous le créez et comment. Cela signifie également que la responsabilité vous incombe.

Concrètement, cela signifie :

• Nous sommes là pour vous aider avec : l'accessibilité de l'API, le bon fonctionnement de votre jeton, l'activation de Voys Intelligence, ou une divergence entre un endpoint ou un code de statut et la documentation.
• Nous ne pouvons pas vous aider avec : 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 créée pour vous par un tiers et qui n'est plus maintenue.

Vous êtes bloqué et ne savez pas d'où vient le problème ? N'hésitez pas à nous contacter. Nous serons ravis de réfléchir avec vous, même si la création et la maintenance de votre propre intégration restent de votre ressort (ou de celui de votre développeur).

FAQ

Dois-je savoir coder ? Non. Cette page vous aide à comprendre ce qui est possible et comment c'est construit dans les grandes lignes. La création proprement dite est réalisée par un développeur, ou vous utilisez une intégration toute faite.

Mon jeton API est-il sécurisé ? Oui, tant que vous le gardez 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 pu fuiter ? Vous pouvez en demander un nouveau dans Freedom.

Pourquoi je ne reçois pas de résumés de mes appels ? Dans la quasi-totalité des cas, c'est parce que Voys Intelligence n'est pas encore activé. Cela vaut la peine de le vérifier en premier, avant de chercher plus loin.

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

Que faire si mon intégration ne fonctionne plus ? Vérifiez d'abord si le problème vient de notre côté : 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 ? Vous ou votre développeur devrez alors le résoudre. Vous pouvez en lire davantage sous « Responsabilité et assistance » ci-dessus.

Y a-t-il des limites de débit, 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 si un en-tête Retry-After est inclus. Par précaution, prévoyez une nouvelle tentative avec temporisation.

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 pas de champ de statut ni de 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 continu.