Kit de développement logiciel pour les extensions d'appel

PrésentationPoints de terminaison

Remarque : Nos partenaires d'application d'appel n'ont plus besoin de créer et de mettre à jour manuellement les engagements d'appel ; HubSpot s'en chargera pour eux. Découvrez-en davantage ici.

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 :

  1. 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 ;
  2. 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.
  3. 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.

Exécuter l'application d'appel de démonstration

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.

Installer l'application d'appel de démonstration

Vous pouvez exécuter les applications de démonstration avec ou sans installation. Pour installer la démo sur votre environnement local :

  1. Installez Node.js sur votre environnement.
  2. Clonez, bifurquez ou téléchargez le ZIP de ce référentiel.
  3. Ouvrez votre terminal et accédez au répertoire racine du projet.
  4. Exécutez l'une des commandes suivantes :
      • Pour demo-minimal-js :
cd demos/demo-minimal-js && npm i && npm start
  • Pour demo-react-ts :
cd demos/demo-react-ts && npm i && npm start

Celles-ci basculeront vers le répertoire de démonstration souhaité, installeront les dépendances Node.js requises pour le projet à l'aide de l'ILC npm et démarreront l'application. 

Remarque : La commande 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.

Lancer l'application d'appel de démonstration depuis HubSpot

  1. Accédez à vos fiches d'informations :
    • Contacts : dans votre compte HubSpot, accédez à Contacts > Contacts.
    • Entreprise : dans votre compte HubSpot, accédez à Contacts > Entreprises.
  2. 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 ou demo-react-ts :
localStorage.setItem("LocalSettings:Calling:installDemoWidget", "local");
    • Si vous avez ignoré les étapes d'installation :
      • Pour demo-minimal-js :
localStorage.setItem("LocalSettings:Calling:installDemoWidget", "app:js");
  • Pour demo-react-ts :
localStorage.setItem("LocalSettings:Calling:installDemoWidget", "app");
  1. 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). 
    call-app-in-record
  2. 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.

calling-sdk-in-app

 

Installer le kit de développement logiciel pour les extensions d'appel sur votre application d'appel

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 :
npm i --save @hubspot/calling-extensions-sdk
  • Pour yarn, exécutez :
yarn add @hubspot/calling-extensions-sdk

Flux de messages typiques entre l'application appelante et HubSpot

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 :

  1. Numérotation : HubSpot envoie l'événement de numérotation.
  2. Appel sortant démarré : l'application informe HubSpot lorsque l'appel a démarré.
  3. Créer un engagement : HubSpot crée un engagement d'appel avec un minimum d'informations si l'application le demande.
  4. Engagement créé : HubSpot a créé un engagement.
  5. EngagementId envoyé à l'application : HubSpot envoie engagementId à l'application.
  6. Fin de l'appel : l'application informe lorsque l'appel est terminé.
  7. Appel terminé : l'application informe lorsque l'utilisateur a terminé l'expérience utilisateur de l'application.
  8. 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.

Utilisation du kit de développement logiciel pour les extensions d'appel

Créer une instance

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 :

import CallingExtensions from "@hubspot/calling-extensions-sdk"; const options = { /** @property {boolean} debugMode - Whether to log various inbound/outbound debug messages to the console. If false, console.debug will be used instead of console.log */ debugMode: true | false, // eventHandlers handle inbound messages eventHandlers: { onReady: () => { /* HubSpot is ready to receive messages. */ }, onDialNumber: event => { /* HubSpot sends a dial number from the contact */ }, /** onEngagementCreated will be @deprecated in 2024 */ onEngagementCreated: event => { /* HubSpot has created an engagement for this call. */ }, onCreateEngagementSucceeded: event => { /* HubSpot has created an engagement for this call. */ } onEngagementCreatedFailed: event => { /* HubSpot has failed to create an engagement for this call. */ } onUpdateEngagementSucceeded: event => { /* HubSpot has updated an engagement for this call. */ }, onUpdateEngagementFailed: event => { /* HubSpot has failed to update an engagement for this call. */ } onVisibilityChanged: event => { /* Call widget's visibility is changed. */ } } }; const extensions = new CallingExtensions(options);

Envoi de messages à HubSpot

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. 
// The initialized call allows you to send a message indicating that the soft phone is ready for interaction. const payload = { // Whether a user is logged-in isLoggedIn: true|false, // Optionally send the desired widget size sizeInfo: { height: number, width: number } } extensions.initialized(payload);
  • userLoggedIn : envoie un message indiquant que l'utilisateur s'est connecté.
// Sends a message indicating that user has logged in // This message is only needed when user isn't loged in when initialized extensions.userLoggedIn();
  • userLoggedOut : envoie un message indiquant que l'utilisateur s'est déconnecté.
// Sends a message indicating that user has logged out extensions.userLoggedOut();
  • outgoingCall : envoie un message pour informer HubSpot qu'un appel sortant a commencé. 
// Sends a message to notify HubSpot that an outgoing call has started. const callInfo = { phoneNumber: string, // optional unless call is initiated by the widget createEngagement: true, // whether HubSpot should create an engagement for this call callStartTime: number // optional unless call is initiated by the widget }; extensions.outgoingCall(callInfo);
  • callAnswered : envoie un message pour informer HubSpot qu'un appel sortant est en cours de prise en charge.
extensions.callAnswered();
  • callEnded : envoie un message pour informer HubSpot que l'appel a pris fin.
// Sends a message to notify HubSpot that the call has ended. // After receiving the call ended event, the user can navigate away, can close the call widget. extensions.callEnded();
  • callCompleted : envoie un message pour informer HubSpot que l'appel est terminé. Les propriétés d'engagement appartiennent à HubSpot et n'ont plus besoin d'être créées ou mises à jour manuellement (voir les éléments en surbrillance).
Remarque : La propriété hideWidget sera ignorée lorsque l'utilisateur se trouvera dans une file d'attente de tâches avec le type de tâche Call.
// Sends a message to notify HubSpot that the call has completed. // After receiving the call completed event, HubSpot will // 1) insert the engagement into the timeline // 2) set the default associations on the engagement // 3) closes the widget unless `hideWidget` is set to false. // 4) update the engagement with any engagement properties const data = { engagementId: number, hideWidget: boolean, // (optional) defaults to true engagementProperties?: { [key: string]: string } // opt in to hs owned engagements by adding properties in https://developers.hubspot.com/docs/api/crm/calls#properties extensions.callCompleted(data);
  • sendError : envoie un message pour informer HubSpot que l'application d'appel a rencontré une erreur.
// Sends a message to notify HubSpot that the call widget has encountered an error. // After receiving the sendError event, HubSpot will display an alert popup to the user with the error message provided. const data = { message: string // error message to be displayed in the alert popup }; extensions.sendError(data);
  • resizeWidget : envoie un message pour informer HubSpot que l'application d'appel doit être redimensionnée.
// Sends a message to notify HubSpot that the call widget needs to be resized. // After receiving the resizeWidget event, HubSpot will use the provided height and width to resize the call widget. const data = { height: boolean // desired height of the call widget width: number, // desired width of the call widget }; extensions.resizeWidget(data);

Recevoir des messages de HubSpot

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.
// Message indicating that HubSpot is ready to receive messages onReady() { // Send initialized message to HubSpot to indicate that the call widget is also ready extensions.initialized(payload); ... }
  • onDial : message indiquant que l'utilisateur a déclenché un appel sortant.
// Message indicating that user has triggered an outbound call onDialNumber(data) { const { /* The phone nubmer to dial */ phoneNumber: string, /* The id of the logged in user. */ ownerId: number, /* The id of the hubspot account */ portalId: number, /* HubSpot object Id of the phoneNumber */ objectId: number, /* HubSpot object type of the phoneNumber */ objectType: CONTACT | COMPANY } = data; ... }
  • onEngagementCreated : message indiquant que HubSpot a créé des données onEngagementCreated.
Remarque : HubSpot va supprimer l'événement onEngagementCreated en faveur de onCreateEngagementSucceeded en 2024.
/** @deprecated */ // Message indicating that HubSpot has created onEngagementCreated(data) { const { /* A HubSpot created engagement id. */ engagementId: number, } = data; ... }
  • onCreateEngagementSucceeded ou onCreateEngagementFailed (NOUVEAU) : HubSpot envoie un message pour informer le partenaire d'application d'appel que la mise à jour de l'engagement a réussi ou échoué.
onCreateEngagementSucceeded: event => { /* HubSpot has created an engagement for this call. */ }, onCreateEngagementFailed: event => { /* HubSpot has failed to create an engagement for this call. */ }
  • onUpdateEngagementSucceeded ou onUpdateEngagementFailed (NOUVEAU) : HubSpot envoie un message pour informer le partenaire d'application d'appel que la création de l'engagement a réussi ou échoué.
onUpdateEngagementSucceeded: event => { /* HubSpot has updated an engagement for this call. */ }, onUpdateEngagementFailed: event => { /* HubSpot has failed to update an engagement for this call. */ }
  • onVisibilityChanged : message indiquant si l'utilisateur a minimisé ou masqué l'application d'appel.
// Message indicating if user has minimized/hide the call widget onVisibilityChanged(data) { const { isMinimized, isHidden } = data; ... }
  • defaultEventHandler : gestionnaire par défaut pour les événements.
// Default handler for events. defaultEventHandler(event) { console.info("Event received. Do you need to handle it?", event); }

Tester votre application

Afin de lancer les extensions d'appel iFrame pour les utilisateurs finaux, HubSpot nécessite les paramètres iFrame suivants.

{ name: string /* The name of your calling app to display to users. */, url: string /* The URL of your calling app, built with the Calling Extensions SDK */, width: number /* The iFrame's width */, height: number /* The iFrame's height */, isReady: boolean /* Whether the widget is ready for production (defaults to true) */, supportsCustomObjects : true /* Whether calls can be placed from a custom object */ }

Via le point de terminaison des paramètres d'appel

Via votre outil d'API (par exemple, Postman), envoyez la charge utile suivante à l'API de paramètres de HubSpot. Assurez-vous d'obtenir l'élément APP_ID de votre application d'appel et de votre application DEVELOPER_ACCOUNT_API_KEY.

Remarque : L'indicateur isReady indique si l'application est prête pour la production. Il doit être défini sur false lors des tests.
# Example payload to add the call widget app settings curl --request POST \ --url 'https://api.hubapi.com/crm/v3/extensions/calling/APP_ID/settings?hapikey=DEVELOPER_ACCOUNT_API_KEY' \ --header 'accept: application/json' \ --header 'content-type: application/json' \ --data '{"name":"demo widget","url":"https://mywidget.com/widget","height":600,"width":400,"isReady":false}' # Note that this endpoint also supports PATCH, GET and DELETE

Remplacer vos paramètres d'extension à l'aide de localStorage

Vous pouvez remplacer n'importe lequel de vos paramètres d'extension à des fins de test. Ouvrez la console du développeur de votre navigateur à partir d'un onglet HubSpot, modifiez les paramètres ci-dessous et exécutez la commande :

const myExtensionSettings = { isReady: true, name: "My app name", url: "My local/qa/prod URL", }; localStorage.setItem( "LocalSettings:Calling:CallingExtensions", myExtensionSettings, );

Préparer votre application pour la production

Si vous avez déjà utilisé le point de terminaison POST lors du test de votre application, vous pouvez utiliser le point de terminaison PATCH pour définir isReady sur true. Autrement, via 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 de votre application DEVELOPER_ACCOUNT_API_KEY.

# Example payload to add the call widget app settings curl --request POST \ --url 'https://api.hubapi.com/crm/v3/extensions/calling/APP_ID/settings?hapikey=DEVELOPER_ACCOUNT_API_KEY' \ --header 'accept: application/json' \ --header 'content-type: application/json' \ --data '{"name":"demo widget","url":"https://mywidget.com/widget","height":600,"width":400,"isReady":true}' # Note that this endpoint also supports PATCH, GET and DELETE

Publier votre application d'appel dans le marketplace de HubSpot

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.

Kit de développement logiciel pour les appels | Foire aux questions

How is user authentication handled?

L'application d'appel doit gérer l'authentification.

Is Calling Extensions hosted on a CDN?

Oui. Vous pouvez installer le kit de développement logiciel pour les extensions d'appel via jsDeliver. Par exemple, pour installer call-extensions-sdk@0.2.2, vous pouvez utiliser https://cdn.jsdelivr.net/npm/@hubspot/calling-extensions-sdk@0.2.2/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 :

outgoingCall({ createEngagement: true })

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 :

const callInfo = { phoneNumber: string, // optional unless call is initiated by the widget createEngagement: true // whether HubSpot should create an engagement for this call callStartTime: number // optional unless call is initiated by the widget }; extensions.outgoingCall(callInfo);

Si vous avez besoin d'une aide supplémentaire, consultez le forum de discussion de HubSpot pour les développeurs.

Cet article vous a-t-il été utile ?
Ce formulaire est destiné à recueillir les avis sur la documentation pour les développeurs. Si vous souhaitez faire part de votre avis sur les produits HubSpot, veuillez le partager sur le forum des idéesde la communauté.