電話拡張SDK

概要エンドポイント

注：HubSpotのコールアプリのパートナー様は、コールエンゲージメントを手動で作成し、更新する必要がなくなりました。HubSpotが代わりにコールエンゲージメントの作成と更新に対処します。詳しくはこちらをご覧ください。

アプリで電話拡張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 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);

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に通知するメッセージを送信します。エンゲージメントのプロパティーはHubSpotが所有するため、手動で作成または更新する必要がなくなりました（強調表示されている箇所を参照）。
注：ユーザーがCallタスクタイプのタスクキューにある場合、hideWidgetプロパティーは無視されます。
// 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：通話アプリでエラーが発生したことを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データを作成したことを示すメッセージ。
注：2024年にHubSpotはonEngagementCreatedイベントを廃止し、onCreateEngagementSucceededを使用する予定です。
/** @deprecated */ // Message indicating that HubSpot has created onEngagementCreated(data) { const { /* A HubSpot created engagement id. */ engagementId: number, } = data; ... }
  • onCreateEngagementSucceededまたはonCreateEngagementFailed（新規）：HubSpotが、エンゲージメントの更新が正常に完了したか、または失敗したかを通知するメッセージをコールアプリのパートナー様に送信します。
onCreateEngagementSucceeded: event => { /* HubSpot has created an engagement for this call. */ }, onCreateEngagementFailed: event => { /* HubSpot has failed to create an engagement for this call. */ }
  • onUpdateEngagementSucceededまたはonUpdateEngagementFailed（新規）：HubSpotが、エンゲージメントの作成が正常に完了したか、または失敗したかを通知するメッセージをコールアプリのパートナー様に送信します。
onUpdateEngagementSucceeded: event => { /* HubSpot has updated an engagement for this call. */ }, onUpdateEngagementFailed: event => { /* HubSpot has failed to update an engagement for this call. */ }
  • 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); }

アプリをテストする

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

{ 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 */ }

通話設定エンドポイントの使用

APIツール（Postmanなど）を使用して、次のペイロードをHubSpotの設定APIに送信します。通話のAPP_IDとアプリのDEVELOPER_ACCOUNT_API_KEYを取得してください。

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

localStorageを使用して拡張機能の設定を上書きする

テスト目的で、拡張機能の設定を上書きできます。HubSpotタブからブラウザーの開発者コンソールを開き、以下の設定を編集して、コマンドを実行します。

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

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

アプリのテスト時に既にPOSTエンドポイントを使用している場合は、PATCHエンドポイントを使用してisReadyをtrueに変更できます。それ以外の場合は、APIツール（Postmanなど）を使用して、このペイロードをHubSpotの設定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 supports PATCH, GET and DELETE

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

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

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

How is user authentication handled?

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

Is Calling Extensions hosted on a CDN?

はい。電話拡張SDKはjsDeliver経由でインストールできます。例えば、calling-extensions-sdk@0.2.2をインストールするには、https://cdn.jsdelivr.net/npm/@hubspot/calling-extensions-sdk@0.2.2/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がご提供しているヘルプはこちらでご確認ください。