Number Insight API avancé

À compter du 4 février 2027, Vonage mettra fin à Vonage Number Insights. Afin d'assurer un soutien ininterrompu et de fournir une solution plus évolutive et à l'épreuve du temps, nous vous encourageons à migrer vers notre offre améliorée : Vonage Identity Insights API. L'API Identity Insights de Vonage consolide plusieurs ensembles de données liées aux numéros de téléphone en une seule API flexible, vous permettant de demander des informations en temps réel sur un numéro de téléphone et de récupérer toute combinaison d'informations - telles que le formatage du numéro, les détails de l'opérateur, le SIM Swap et le Subscriber Match - en un seul appel.

Veuillez consulter le Guide de transition de Numbers Insightsqui fournit des conseils détaillés sur les différences entre les API, les changements nécessaires et les meilleures pratiques pour une transition en douceur.

L'API Number Insight vous donne des informations en temps réel sur les numéros de téléphone dans le monde entier. Trois niveaux sont disponibles : Basic, Standard et Advanced.

Le niveau avancé vous fournit les données les plus complètes pour vous aider à protéger votre organisation contre la fraude et le spam. Contrairement aux niveaux de base et standard, vous accédez généralement à l'API avancée de manière asynchrone, par le biais d'un fichier webhook.

Dans ce tutoriel

Dans ce tutoriel, vous créez un service web RESTful dans Numbers et Express qui accepte un numéro de téléphone et renvoie des informations perspicaces sur le numéro lorsqu'elles sont disponibles.

Pour ce faire, vous devez suivre les étapes suivantes :

  1. Créer le projet - créer une application Node.js/Express.
  2. Installer le vonage paquet - ajouter des fonctionnalités Vonage à votre projet.
  3. Exposez votre application à l'Internet - utiliser ngrok pour permettre à Vonage d'accéder à votre application via un webhook.
  4. Créer l'application de base - construire la fonctionnalité de base.
  5. Créer la requête asynchrone - appeler l'API avancée de Number Insight.
  6. Créer le webhook - écrire le code qui traite les données d'observation entrantes.
  7. Tester l'application - le voir en action !

Conditions préalables

Pour compléter le tutoriel, vous avez besoin de :

  • A Account Vonage - pour votre clé d'API et votre secret
  • ngrok - pour rendre votre serveur web de développement accessible aux serveurs de Vonage sur l'Internet

Créer le projet

Créez un répertoire pour votre application, cd dans le répertoire, puis utiliser le gestionnaire de paquets Node.js npm pour créer un package.json pour les dépendances de votre application :

mkdir myapp cd myapp npm init

Appuyez sur [Enter] pour accepter chacune des valeurs par défaut.

Ensuite, installez le express le cadre d'application web et analyseur de corps paquets :

npm install express body-parser --save

Installer le vonage paquet

Exécuter ce qui suit npm dans la fenêtre du terminal pour installer le SDK Vonage Node Server :

npm install @vonage/server-sdk

Exposez votre application à l'Internet

Lorsque l'API Number Insight a terminé le traitement de votre demande, elle avertit votre application par le biais d'un message webhook. Le webhook fournit un mécanisme permettant aux serveurs de Vonage de communiquer avec les vôtres.

Pour que votre application soit accessible aux serveurs de Vonage, elle doit être publiquement disponible sur Internet. Une façon d'y parvenir pendant le développement et les essais est d'utiliser la fonction ngrokUn service qui expose les serveurs locaux à l'Internet public par le biais de tunnels sécurisés. Voir aussi cet article de blog pour plus de détails.

Télécharger et installer ngrokpuis démarrez-le avec la commande suivante :

./ngrok http 5000

Cela crée des URL publiques (HTTP et HTTPS) pour tout site web fonctionnant sur le port 5000 de votre machine locale.

Utiliser le ngrok à l'interface web à l'adresse http://localhost:4040 et notez les URL que ngrok fournit : vous en avez besoin pour compléter ce tutoriel.

Créer l'application de base

Créer le index.js dans le répertoire de votre application avec le code suivant, en remplaçant l'élément VONAGE_API_KEY, VONAGE_API_SECRET et WEBHOOK_URL avec vos propres valeurs :

Testez-le en exécutant la commande suivante dans le terminal et en obtenant le résultat indiqué :

node index.js Listening on port 5000

Dans un navigateur, entrez l'URL suivante, en remplaçant https://bcac78a0.ngrok.io avec le nom d'hôte ngrok des fournitures :

https://bcac78a0.ngrok.io/insight/123456

Si tout fonctionne correctement, Getting information for 123456 s'affiche dans le terminal.

Créer la requête asynchrone

Maintenant que votre application peut recevoir un numéro de téléphone, vous devez créer la requête asynchrone vers l'API Number Insight Async.

Tout d'abord, écrivez le code qui crée une instance de Vonage avec les détails de votre Account :

Ensuite, étendre le /insight/:number pour appeler l'API Number Insight, en indiquant le numéro qui vous intéresse et l'URL du webhook qui traite la réponse. Vous créerez le webhook dans une étape ultérieure.

L'appel à l'API avancée de Number Insight renvoie une réponse immédiate qui accuse réception de la demande avant que les données d'aperçu réelles ne soient disponibles. C'est cette réponse que nous enregistrons dans la console :

{ request_id: '3e6e31a4-3efb-49ab-8751-5a43e4de6406', number: '447700900000', remaining_balance: '17.775', request_price: '0.03000000', status: 0 }

Les status dans le corps de la requête indique si l'opération a réussi. Une valeur de zéro indique un succès et une valeur différente de zéro indique un échec, comme décrit dans la section Documentation de référence de Number Insight API.

Créer le webhook

L'API Insight renvoie les résultats à votre application par l'intermédiaire d'un fichier POST vous devez donc définir l'option /webhooks/insight en tant que app.post()comme indiqué :

Le gestionnaire enregistre les données JSON entrantes dans la console et envoie un message de type 204 Réponse HTTP aux serveurs de Vonage.

Le code d'état HTTP 204 indique que le serveur a répondu avec succès à la demande et qu'il n'y a pas de contenu supplémentaire à envoyer dans le corps de la réponse.

Tester l'application

Exécuter index.js:

node index.js

Saisissez une URL au format suivant dans la barre d'adresse du navigateur, en remplaçant https://bcac78a0.ngrok.io avec votre ngrok URL et INSIGHT_NUMBER avec un numéro de téléphone de votre choix :

http://YOUR_NGROK_HOSTNAME/insight/NUMBER

Après la réponse initiale d'accusé de réception, la console doit afficher des informations similaires à celles présentées ci-dessous :

{ "status": 0, "status_message": "Success", "lookup_outcome": 0, "lookup_outcome_message": "Success", "request_id": "55a7ed8e-ba3f-4730-8b5e-c2e787cbb2b2", "international_format_number": "447700900000", "national_format_number": "07700 900000", "country_code": "GB", "country_code_iso3": "GBR", "country_name": "United Kingdom", "country_prefix": "44", "request_price": "0.03000000", "remaining_balance": "1.97", "current_carrier": { "network_code": "23410", "name": "Telefonica UK Limited", "country": "GB", "network_type": "mobile" }, "original_carrier": { "network_code": "23410", "name": "Telefonica UK Limited", "country": "GB", "network_type": "mobile" }, "valid_number": "valid", "reachable": "reachable", "ported": null, "roaming": "unknown" }

Tenez compte des éléments suivants lorsque vous testez votre application :

  • L'API avancée Insight ne fournit aucune information sur les lignes terrestres qui ne soit pas disponible dans l'API standard.
  • Les requêtes à l'API Insight sont payantes. Envisagez d'utiliser le ngrok le tableau de bord pour réécouter les demandes précédentes pendant le développement afin d'éviter les frais inutiles.

Conclusion

Dans ce didacticiel, vous avez créé une application qui utilise l'API Number Insight Advanced Async pour renvoyer des données à un webhook.

Le didacticiel n'a pas abordé certaines des fonctionnalités propres à l'API avancée, telles que la correspondance des adresses IP, la joignabilité et l'état d'itinérance. Examinez le didacticiel de l la documentation pour savoir comment utiliser ces fonctions.

Quelle est la prochaine étape ?

Les ressources suivantes vous aideront à utiliser Number Insight dans vos Applications :