Kit de développement logiciel pour les extensions d'appel
Le kit de développement logiciel pour les extensions d'appel permet aux applications de proposer une option d'appel personnalisée pour les utilisateurs HubSpot directement à partir d'une fiche d'informations dans le CRM.
Une extension d'appel comprend trois éléments principaux :
- le kit de développement logiciel pour les extensions d'appel, un kit de développement logiciel pour JavaScript qui permet la communication entre votre application et HubSpot ;
- les points de terminaison des paramètres d'appel, qui sont utilisés pour définir les paramètres d'appel pour votre application. Chaque compte HubSpot qui connectera votre application utilisera ces paramètres.
- l'iFrame d'appel, qui est l'endroit où votre application apparaît pour les utilisateurs HubSpot et est configuré à l'aide des points de terminaison des paramètres d'appel.
Pour plus d'informations sur l'expérience d'appel dans l'application, consultez cet article de base de connaissances. Une fois que votre application compatible avec les extensions d'appel est connectée à HubSpot, elle apparaîtra comme option dans le sélecteur d'appel lorsque un utilisateur effectue un appel depuis HubSpot.
Si vous n'avez pas d'application, vous pouvez en créer une depuis votre compte de développeur HubSpot. Si vous n'avez pas encore de compte de développeur HubSpot, vous pouvez vous inscrire ici.
Remarque : Seuls les appels sortants sont actuellement pris en charge.
Vous pouvez tester le kit de développement logiciel pour les extensions d'appel sur deux applications de démonstration différentes :
- demo-minimal-js propose une implémentation minimale du kit de développement logiciel en utilisant JavaScript, HTML et CSS. Affichez la façon dont le kit de développement logiciel est instancié dans index.js.
- demo-react-ts propose une implémentation réelle du kit de développement logiciel à l'aide de React, TypeScript et Styled Components pour servir de modèle à votre application. Affichez l'instanciation du kit de développement logiciel dans useCti.ts.
Remarque : Ces applications de démonstration ne sont pas entièrement fonctionnelles et utilisent des données factices pour offrir une expérience plus réaliste.
Vous pouvez exécuter les applications de démonstration avec ou sans installation. Pour installer la démo sur votre environnement local :
- Installez Node.js sur votre environnement.
- Clonez, bifurquez ou téléchargez le ZIP de ce référentiel.
- Ouvrez votre terminal et accédez au répertoire racine du projet.
- Exécutez l'une des commandes suivantes :
- Pour
demo-minimal-js
:
- Pour
- Pour
demo-react-ts
:
npm start
ouvrira automatiquement un nouvel onglet dans votre navigateur à l'adresse https://localhost:9025/ et vous devrez peut-être contourner un avertissement « Votre connexion n'est pas sécurisée » pour accéder à l'application.
- Accédez à vos fiches d'informations :
- Contacts : dans votre compte HubSpot, accédez à Contacts > Contacts.
- Entreprise : dans votre compte HubSpot, accédez à Contacts > Entreprises.
- Ouvrez la console de développeur de votre navigateur et exécutez la commande suivante :
- Si vous avez terminé les étapes d'installation, pour
demo-minimal-js
oudemo-react-ts
:
- Si vous avez terminé les étapes d'installation, pour
- Si vous avez ignoré les étapes d'installation :
- Pour
demo-minimal-js
:
- Pour
- Pour
demo-react-ts
:
- Actualisez la page et cliquez sur l'icône Appel dans la barre latérale de gauche. Cliquez sur le menu déroulant Appel de et sélectionnez le nom de l'application de démonstration à l'étape 2 (par exemple, Demo App Local, Demo App JS, Demo App React).
- Cliquez sur Appel pour voir comment l'application de démonstration s'intègre à HubSpot via le kit de développement logiciel pour les extensions d'appel. Vous pouvez également voir les événements enregistrés sur la console de développeur de votre navigateur.
Pour ajouter le kit de développement logiciel pour les extensions d'appel en tant que dépendance Node.js à votre application d'appel :
- Pour npm, exécutez :
- Pour yarn, exécutez :
Le kit de développement logiciel pour les extensions d'appel expose une API simple pour HubSpot et une application d'appel pour échanger des messages. Les messages sont envoyés via des méthodes exposées par le kit de développement logiciel et reçus via eventHandlers
.
Voici une description des événements :
- Numérotation : HubSpot envoie l'événement de numérotation.
- Appel sortant démarré : l'application informe HubSpot lorsque l'appel a démarré.
- Créer un engagement : HubSpot crée un engagement d'appel avec un minimum d'informations si l'application le demande.
- Engagement créé : HubSpot a créé un engagement.
- EngagementId envoyé à l'application : HubSpot envoie
engagementId
à l'application. - Fin de l'appel : l'application informe lorsque l'appel est terminé.
- Appel terminé : l'application informe lorsque l'utilisateur a terminé l'expérience utilisateur de l'application.
- Mettre à jour l'engagement : l'application récupère l'engagement avec
engagementId
, puis fusionne et met à jour l'engagement avec des détails d'appel supplémentaires. Découvrez-en davantage sur la mise à jour d'un engagement d'appel.
Pour commencer, créez une instance de l'objet CallingExtensions
. Vous pouvez définir le comportement de votre extension en fournissant l'objet d'une option lorsque vous créez votre instance d'extensions. L'objet de cette option fournit un champ eventHandlers
dans lequel vous pouvez spécifier le comportement de votre extension. Le bloc de code suivant illustre les options disponibles et les gestionnaires d'événements que vous pouvez définir :
L'objet extensions
fournit les gestionnaires d'événements suivants que vous pouvez appeler pour envoyer des messages à HubSpot ou pour spécifier un autre comportement associé. Consultez l'exemple ci-dessous.
initialized
: envoie un message indiquant que le téléphone logiciel est prêt pour l'interaction.
userLoggedIn
: envoie un message indiquant que l'utilisateur s'est connecté.
userLoggedOut
: envoie un message indiquant que l'utilisateur s'est déconnecté.
outgoingCall
: envoie un message pour informer HubSpot qu'un appel sortant a commencé.
callAnswered
: envoie un message pour informer HubSpot qu'un appel sortant est en cours de prise en charge.
callEnded
: envoie un message pour informer HubSpot que l'appel a pris fin.
callCompleted
: envoie un message pour informer HubSpot que l'appel est terminé.
sendError
: envoie un message pour informer HubSpot que l'application d'appel a rencontré une erreur.
resizeWidget
: envoie un message pour informer HubSpot que l'application d'appel doit être redimensionnée.
L'objet extensions
fournit les gestionnaires d'événements suivants que vous pouvez appeler pour recevoir des messages dans HubSpot ou pour spécifier un autre comportement associé. Consultez l'exemple ci-dessous.
onReady
: message indiquant que HubSpot est prêt à recevoir des messages.
onDial
: message indiquant que l'utilisateur a déclenché un appel sortant.
onEngagementCreated
: message indiquant que HubSpot a créé des donnéesonEngagementCreated
.
onVisibilityChanged
: message indiquant si l'utilisateur a minimisé ou masqué l'application d'appel.
defaultEventHandler
: gestionnaire par défaut pour les événements.
Si votre application est en cours de création, vous pouvez définir manuellement l'URL d'iFrame pour votre navigateur en configurant une valeur localStorage
. Vous pourrez ainsi définir une URL localhost pour un test en local.
Pour définir la valeur, ouvrez les outils de développeur pour votre navigateur et exécutez la commande JavaScript suivante dans la console de développeur :
La valeur name apparaîtra dans le titre qui s'affiche dans l'en-tête de l'application d'appel et url sera l'URL utilisée pour l'iFrame. Lorsque cet élément est défini, la valeur name que vous avez définie apparaîtra comme une option pour le fournisseur d'appels lorsque vous cliquerez sur l'icône Appel. L'application d'appel utilisera l'élément url de l'iFrame que vous avez défini.
En utilisant votre outil d'API (par exemple, Postman), envoyez cette charge utile à notre API de paramètres. Assurez-vous d'obtenir l'élément APP_ID de votre application d'appel et votre application DEVELOPER_ACCOUNT_API_KEY.
L'indicateur isReady
indique si l'application est prête pour la production. Ce drapeau doit être défini sur false lors des tests.
localStorage
.
Une fois votre application configurée, la dernière étape consiste à lister votre application d'appel dans le marketplace HubSpot. Vous trouverez plus de détails ici. Vous pouvez également choisir de ne pas la lister sur le marketplace si cette application est à usage interne uniquement.
How is user authentication handled?
L'application d'appel doit gérer l'authentification.
Is Calling Extensions hosted on a CDN?
Non. Les extensions d'appel sont très petites et doivent être fournies avec l'application d'appel. Si le regroupement du fichier n'est pas possible, le pack npm inclut un groupe UMD compilé qui peut être inclus dans le HTML (../node_modules/@hubspot/calling-extensions-sdk/dist/main.js).
When should an engagement be created versus updated?
Un utilisateur peut lancer un appel à partir de l'interface utilisateur HubSpot, mais également en dehors (par exemple, application mobile, numéro redirigé, etc.). Si un appel est lancé à partir de l'interface utilisateur de HubSpot, HubSpot créera une interaction d'appel et enverra l'interaction à l'application d'appel. Une fois l'appel terminé, l'application d'appel peut mettre à jour cette interaction avec des détails d'appel supplémentaires. Si un appel est lancé en dehors de l'interface utilisateur HubSpot, l'application doit créer l'interaction d'appel.
What scopes are required as a part of the integration?
L'ajout des périmètres d'accès Contacts et Chronologie est requis. Ces périmètres d'accès garantissent que votre application a accès aux contacts, et peut créer et mettre à jour des interactions d'appel dans le CRM.
Can this functionality be added to an already existing application in the marketplace or do I create a new app?
Si vous disposez déjà d'une application existante qui répond au cas d'utilisation d'appel, vous pouvez ajouter directement cette fonctionnalité à votre application existante. Tous les clients qui ont déjà votre application auront accès à cette nouvelle fonctionnalité sans avoir à installer l'application à nouveau.
Can I integrate my existing soft phone application in the SDK?
Oui, l'intégration de votre application de téléphone logiciel existante devrait être très facile. Il suffit de suivre les étapes décrites dans la documentation ci-dessus pour que votre application soit opérationnelle.
Can users use multiple integrations at the same time?
Oui, les utilisateurs peuvent utiliser plusieurs intégrations d'appel tierces en même temps. Ils peuvent utiliser le sélecteur de fournisseur qui s'affiche après avoir cliqué sur le bouton d'appel pour basculer facilement entre les fournisseurs.
Can free users install app integrations?
Oui, tous les utilisateurs peuvent installer l'application.
If a user already has my app installed, does the integration automatically show up?
Oui, si un utilisateur a déjà installé votre application et que vous mettez à jour la même application avec les extensions d'appel, l'intégration s'affichera automatiquement. Actuellement, il n'est pas possible pour le développeur d'activer l'application d'appel uniquement pour un sous-ensemble de clients.
Can any user install or uninstall an app?
Non, seuls les utilisateurs disposant des autorisations nécessaires peuvent installer et désinstaller une application. Découvrez comment consulter les autorisations d'un utilisateur.
Can I place a call from a custom object?
Oui, les intégrations d'appel peuvent passer des appels à partir d'objets personnalisés tant qu'elles n'utilisent que le kit de développement logiciel pour créer l'appel. Chaque intégration devra vérifier qu'elle utilise uniquement le kit de développement logiciel d'appel pour créer des appels et notifier HubSpot lors de l'événement outgoingCall
.
Tout d'abord, vérifiez que l'intégration utilise le kit de développement logiciel pour les appels pour créer des engagements dans l'événement outgoingCall :
Si createEngagement
est défini sur true, découvrez comment mettre à jour les informations de votre application ici.
Voici l'exemple pour l'ensemble de l'événement outgoingCall
:
Si vous avez besoin d'une aide supplémentaire, consultez le forum de discussion de HubSpot pour les développeurs.
Merci d'avoir partagé votre avis.