電話拡張SDK

概要エンドポイント

アプリで電話拡張SDK（英語）を使用すると、CRMレコード内で直接、HubSpotユーザーに対して通話のカスタムオプションを提供できます。 

電話拡張は、次の3つのコンポーネントで構成されています。

  1. 電話拡張SDK（英語）。貴社のアプリとHubSpot間の通信を可能にするJavaScript SDK。
  2. コール設定エンドポイント。貴社のアプリのコール設定のために使用するエンドポイント。この設定は、アプリに接続する各HubSpotアカウントで使用されます。
  3. コールiframe。貴社のアプリをHubSpotユーザーに対して表示する場所。コール設定エンドポイントを使用して設定されます。

詳しくはアプリ内でのコール操作についてをご参照ください。電話拡張を有効にしたアプリがHubSpotに接続されると、ユーザーがHubSpotから電話をかける際に、コール切り替え機能のオプションとして表示されます。

アプリをまだ用意していない場合は、HubSpot開発者アカウントを使用してアプリを作成（英語）できます。HubSpot開発者アカウントをまだお持ちでない場合は、こちらから登録してください。

注：現在サポートされているのは発信コールのみです。

デモ通話アプリを実行する

2つの異なるデモアプリで電話拡張SDKをテストするオプションがあります。

  •  demo-minimal-jsの特徴はSDKの必要最小限の実装です。JavaScript、HTML、CSSを使用して行われます。index.jsでのSDKの使用例をご覧ください。
  • demo-react-tsの特徴はSDKを実用的に実装できることです。React、TypeScript、Styled Componentsを使用してアプリのブループリントとして動作します。useCti.tsでのSDKの使用例をご覧ください。

注：これらのデモアプリは完全に機能する通話アプリではなく、より現実的なエクスペリエンスを提供するために、モックデータを使用します。

デモ通話アプリをインストールする

インストールの有無にかかわらず、デモアプリを実行できます。ローカル環境にデモをインストールするには：

  1. お使いの環境にNode.jsをインストールします。
  2. このリポジトリのZIPをダウンロード、複製、またはフォークします。
  3. ターミナルを開き、プロジェクトのルートディレクトリーに移動します。
  4. 次のコマンドのいずれかを実行します。
      • demo-minimal-jsの場合:
cd demos/demo-minimal-js && npm i && npm start
  • demo-react-tsの場合:
cd demos/demo-react-ts && npm i && npm start

これによって、目的のデモディレクトリーに切り替え、npm CLIを使用してプロジェクトに必要なNode.jsの依存関係をインストールし、アプリを起動できます。 

注：npm startコマンドを実行すると、https://localhost:9025/に接続された新しいブラウザータブが自動的に開きます。アプリケーションにアクセスするには、「接続がセキュリティーで保護されていない」ことを通知するメッセージをバイパスする必要があります。

HubSpotからデモ通話アプリを起動する

  1. レコードに移動します。
    • コンタクト：HubSpotアカウントで、［コンタクト］>［コンタクト］に移動します。
    • 会社：HubSpotアカウントで、［コンタクト］>［キャンペーン］に移動します。
  2. ブラウザーの開発者コンソールを開き、次のコマンドを実行します。
    • demo-minimal-jsまたはdemo-react-tsのインストール手順が完了している場合：
localStorage.setItem("LocalSettings:Calling:installDemoWidget", "local");
    • インストール手順をスキップした場合：
      • demo-minimal-jsの場合:
localStorage.setItem("LocalSettings:Calling:installDemoWidget", "app:js");
  • demo-react-tsの場合:
localStorage.setItem("LocalSettings:Calling:installDemoWidget", "app");
  1. ページを更新し、左側のサイドバーのコールアイコンをクリックします。［発信元］ドロップダウンメニューをクリックして、その中からデモアプリの名前を選択します（例：Demo App Local、Demo App JS、Demo App React）。 
    call-app-in-record
  2. ［コール］をクリックして、デモアプリが電話拡張SDKを介してHubSpotとどのように連携しているかを確認します。また、ブラウザーの開発者コンソールに記録されたイベントも表示できます。

calling-sdk-in-app

 

電話拡張SDKを通話アプリにインストールする

電話拡張SDKをNode.jsの依存関係として通話アプリに追加するには：

  • npmの場合は次を実行します。
npm i --save @hubspot/calling-extensions-sdk
  • yarnの場合は次を実行します。
yarn add @hubspot/calling-extensions-sdk

通話アプリとHubSpot間の通常のメッセージフロー

電話拡張SDKはメッセージを交換のために、HubSpot用のシンプルなAPIと通話アプリを公開します。メッセージは、SDKによって公開された方法で送信され、eventHandlersを介して受信されます。

イベントの説明は次のとおりです。

  1. 番号をダイヤルする：HubSpotは番号ダイヤルイベント送信します。
  2. 発信通話が開始された：通話が開始されると、アプリがHubSpotに通知します。
  3. エンゲージメントを作成する：HubSpotは、アプリから要求された場合、最小限の情報でコールエンゲージメントを作成します。
  4. エンゲージメントが作成された:HubSpotがエンゲージメントを作成しました。
  5. EngagementIdがアプリに送信された：HubSpotがengagementIdをアプリに送信します。
  6. 通話が終了した：通話が終了するとアプリが通知します。
  7. 通話が完了しました：ユーザーがアプリのユーザー体験を完了するとアプリが通知します。
  8. エンゲージメントを更新する：アプリはengagementIdによってエンゲージメントを取得し、その他の通話の詳細とエンゲージメントをマージして更新します。コールエンゲージメントの更新の詳細については、こちらをご覧ください。

電話拡張SDKの使用

インスタンスを作成する

まず、CallingExtensionsオブジェクトのインスタンスを作成します。拡張機能インスタンスを作成するときにオプションのオブジェクトを指定することで、拡張機能の動作を定義できます。このオプションのオブジェクトは、拡張機能の動作を指定できるeventHandlersフィールドを提供します。次のコードブロックは、使用可能なオプションと定義可能なイベントハンドラーを示しています。

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: event => { /* HubSpot has created an engagement for this call. */ }, onVisibilityChanged: event => { /* Call widget's visibility is changed. */ } } }; const extensions = new CallingExtensions(options);

HubSpotへのメッセージの送信

extensionsオブジェクトは、HubSpotにメッセージを送信したり、他の関連する動作を指定したりするために呼び出すことができる、次のイベントハンドラーを提供します。後述の例を参照してください。

  • initialized：ソフトフォンのインタラクションの準備ができていることを示すメッセージを送信します。 
// 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：ユーザーがログインしたことを示すメッセージを送信します。
// 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：ユーザーがログアウトしたことを示すメッセージを送信します。
// Sends a message indicating that user has logged out extensions.userLoggedOut();
  • outgoingCall：発信通話が開始されたことをHubSpotに通知するメッセージを送信します。 
// 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：発信通話が応答されていることをHubSpotに通知するメッセージを送信します。
extensions.callAnswered();
  • callEnded：通話が終了したことをHubSpotに通知するメッセージを送信します。
// 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：通話が完了したことをHubSpotに通知するメッセージを送信します。
// 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 the widget unless `hideWidget` is set to false. const data = { engagementId: number, hideWidget: boolean // (optional) defaults to true }; extensions.callCompleted(data);
  • sendError：通話アプリでエラーが発生したことをHubSpotに通知するメッセージを送信します。
// 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：通話アプリのサイズを変更する必要があることをHubSpotに通知するメッセージを送信します。
// 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);

HubSpotからのメッセージを受信する

extensionsオブジェクトは、HubSpotでメッセージを受信するとき、または他の関連する動作を指定するときに呼び出すことができる、次のイベントハンドラーを提供します。後述の例を参照してください。

  • onReady：HubSpotがメッセージを受信する準備ができていることを示すメッセージ。
// 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 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：HubSpotがonEngagementCreatedデータを作成したことを示すメッセージ。
// Message indicating that HubSpot has created onEngagementCreated(data) { const { /* A HubSpot created engagement id. */ engagementId: number, } = data; ... }
  • onVisibilityChanged：ユーザーが通話アプリを最小化または非表示にしたかどうかを示すメッセージ。
// Message indicating if user has minimized/hide the call widget onVisibilityChanged(data) { const { isMinimized, isHidden } = data; ... }
  • defaultEventHandler：イベントの既定のハンドラー。
// Default handler for events. defaultEventHandler(event) { console.info("Event received. Do you need to handle it?", event); }

ローカル環境からアプリをテストする

アプリケーションの開発中に、localStorage値を設定することにより、ブラウザーのiframe URLを手動で設定できます。これにより、ローカルテスト用のlocalhost URLを設定できます。

この値を設定するには、ブラウザーの開発者ツールを開き、開発者コンソールで次のJavaScriptコマンドを実行します。

localStorage.setItem( "LocalSettings:Calling:CallingExtensions", '{"name": "<your intended widget name>", "url": "<your dev url or prod url>"}' );

nameの値は通話アプリのヘッダーに表示されるタイトルとなり、urlはiframeに使用されるURLになります。この項目を設定すると、設定したnameがコールアイコンのクリック時に電話事業者のオプションとして表示され、設定したiframeのurlが通話アプリに使用されます。

アプリを本番環境用に準備する

エンドユーザー向けの電話拡張iFrameを起動するには、HubSpotに次のiFrameパラメーターが必要です。

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

APIツール（Postmanなど）を使用して、このペイロードを設定APIに送信します。通話アプリケーションのAPP_IDとアプリの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 support GET and DELETE

isReadyフラグは、アプリの本番環境用の準備ができているかどうかを示します。テスト中、このフラグはfalseに設定される必要があります。

注：このフラグも、その他全てのフラグも、localStorageを使用して上書きできます。
/** * Override the isReady flag for the call widget */ localStorage.setItem( "LocalSettings:Calling:CallingExtensions", '{"name": "<your intended widget name>", "isReady": true}' );

通話アプリをHubSpotマーケットプレイスに公開する

アプリのセットアップが完了したら、最後のステップとしてHubSpotマーケットプレイスに通話アプリを掲載します。詳細については、こちらをご覧ください。また、このアプリケーションが社内専用である場合は、マーケットプレイスに掲載しないという選択もできます。

電話拡張SDK |よくある質問

How is user authentication handled?

通話アプリには認証機能が付いています。

Is Calling Extensions hosted on a CDN?

いいえ。通話拡張機能は非常に小さく、通話アプリにバンドルされます。ファイルをバンドルできない場合、npmパッケージには、HTMLに含めることができるコンパイル済みのUMDバンドルが含まれます（../node_modules/@hubspot/calling-extensions-sdk/dist/main.js）。

When should an engagement be created versus updated?

ユーザーは、HubSpot UI内からもHubSpot UI外からも通話を開始できます（モバイルアプリ、リダイレクトされた番号など）。通話がHubSpot UI内から開始された場合、HubSpotはコールエンゲージメントを作成し、通話アプリにエンゲージメントを送信します。通話が終了すると、通話アプリはその他の通話の詳細を追加し、このエンゲージメントを更新できます。通話がHubSpot UIの外部で開始された場合、アプリは通話エンゲージメントを作成します。

What scopes are required as a part of the integration?

連絡先とタイムラインのスコープを追加する必要があります。これらのスコープにより、アプリケーションは連絡先にアクセスでき、CRMでコールエンゲージメントを作成および更新することができます。

Can this functionality be added to an already existing application in the marketplace or do I create a new app?

コール ユース ケースに対応する既存のアプリを既に持っている場合は、この機能を既存のアプリに直接追加できます。既にアプリをインストールしている全てのお客様は、アプリを再度インストールしなくても、この新しい機能を利用できます。

Can I integrate my existing soft phone application in the SDK?

はい。既存のソフト フォン アプリケーションとの連携は非常に簡単です。上記のドキュメントの手順に従って、アプリケーションを起動して実行してください。

Can users use multiple integrations at the same time?

はい。ユーザーは複数のサードパーティーのコール連携を同時に使用できます。コールボタンをクリックした後に表示される電話事業者を切り替える機能を使用して、電話事業者をシームレスに切り替えることができます。

Can free users install app integrations?

はい。全てのユーザーがアプリをインストールできます。

If a user already has my app installed, does the integration automatically show up?

はい。ユーザーが既にアプリをインストールしており、電話拡張機能で同じアプリを更新している場合、連携が自動的に表示されます。現在、開発者が通話アプリを一部の顧客のみに有効にする方法はありません。

Can any user install or uninstall an app?

いいえ。必要な権限を持つユーザーのみ、アプリのインストールおよびアンインストールができます。ユーザーの権限を確認する方法の詳細については、こちらをご覧ください。

Can I place a call from a custom object?

はい。コール連携がSDKのみを使用してコールを作成していれば、カスタムオブジェクトから通話を行うことができます。各連携は、通話拡張SDKのみを使用してコールを作成することを確認する必要があり、またoutgoingCallイベントでHubSpotに通知する必要があります。

まず、outgoingCallイベントでエンゲージメントを作成するのに、連携が電話拡張SDKを使用していることを確認します。

outgoingCall({ createEngagement: true })

createEngagementがtrueの場合、こちらからアプリ情報を更新する方法をご覧ください。

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);

さらにサポートが必要な場合は、HubSpot開発者サポートフォーラムをご覧ください。

参考になりましたか？
こちらのフォームではドキュメントに関するご意見をご提供ください。HubSpotがご提供しているヘルプはこちらでご確認ください。