電話拡張SDK

概要エンドポイント

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

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

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

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

Please note: only outgoing calls are currently supported.

電話拡張SDK

電話拡張SDK（英語）は、HubSpotと貴社のコールアプリの間の通信に使用されるJavaScriptライブラリーであり、iframe内に表示されます。この通信には、次の要素が含まれます。

  • HubSpotから貴社のアプリへの、発信先番号の伝達。
  • 貴社のアプリからHubSpotへの、通話の接続と、通話の終了の伝達。
  • HubSpotから貴社のアプリへの、コールの詳細によって更新するためのプレースホルダーとなるエンゲージメントのIDの伝達。

このSDKは、こちらのGitHubリポジトリー（英語）にて、SDKの技術的な要件とウェブアプリ内での使用方法の詳細と共に提供されています。

セットアップ

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

アプリに関するコール設定は、一度行うと（1回限りの作業）、貴社のアプリをそのHubSpotアカウントに接続する全てのユーザーに適用されます。コール設定の作成方法については、「エンドポイント」タブを参照してください。

コール設定の完了後、ユーザーは接続プロセスに従って、HubSpotアカウント上で貴社の通話サービスを利用可能にする必要があります。 

コールプロセス

電話拡張を使用したコールは次のような手順で行います。

  1. ユーザーがCRMレコードのコールアイコンをクリックします。
  2. コールプロバイダーとなるアプリをユーザーが選択し、［ブラウザーからコール］ボタンをクリックします。
  3. iframeが表示され、アプリ内のコール設定に指定されたURLが開きます。
  4. アプリを通じたコールが確立されます（iframeに表示）。
  5. HubSpotによりプレースホルダーエンゲージメントが作成され、電話拡張SDK（英語）を通じてこのエンゲージメントのIDがアプリに送信されます。
  6. アプリによって、プレースホルダーエンゲージメントが更新されて、コールの詳細が提供されます。

ユーザーが貴社のアプリをHubSpotに接続すると、レコードからのコールの際に追加されるようになります。ユーザーがコールアイコンをクリックすると、既定のHubSpotコールシステムではなく貴社のアプリを使用してコールを行うオプションが表示されます。 

HubSpotから電話を発信する方法をご確認ください。 

コール_プロバイダー

ユーザーがブラウザー経由でコールする場合には、iframeが表示され、アプリのコール設定に指定したURLが開きます。このURLは、貴社の通話サービスを通じてコールを行うカスタム ウェブ アプリへの参照にしてください。電話拡張SDK（英語）を使用することにより、貴社のアプリがHubSpotアプリと通信できます。HubSpotアプリからのメッセージでは発信先の番号が貴社のアプリに伝達され、貴社のアプリからは、コールの終了や、ユーザーによるサービスからのログアウトなど、さまざまなイベントに関するメッセージを送信することができます。

コール_iframe

アプリを開発する際には、次の点に注意してください。

  • iframe内の表示用ウェブアプリはご自身で用意していただく必要があります。HubSpot側ではiframeのコンテンツに関する処理は行われず、iframe URLをバックエンドSIPサービスに設定することはできないためです。
  • iframeのサイズは、設定APIを通じて設定する高さと幅のパラメーターに基づいて決まります。小さい画面も含めた広範なウィンドウサイズにおいて、高さ600px、幅400pxのウィンドウが最適です。
  • iframe内にエラー条件を表示できるようにしてください。貴社のアプリから、音声やネットワークの問題、その他のエラーについてユーザーに通知するために必要です。

テスト

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

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

localStorage.setItem('LocalSettings:Calling:CallingExtensions', '{"name": "Example Calling app Title", "url": "https://myWidgetUrl/path/"}')

nameの値がコールウィジェットのヘッダーに表示され、urlはiframeに使用されるURLになります。この項目を設定すると、設定したnameがコールアイコンのクリック時にコールプロバイダーのオプションとして表示され、設定したiframeのurlがコールウィジェットに使用されます。

HubSpotにおけるコールのログ記録

HubSpot上で、コールはエンゲージメントオブジェクトとして記録されます。このエンゲージメントは、関連付けられているCRMオブジェクトのタイムラインにコールの詳細を表示するために使用されます。HubSpotに組み込まれているセールスレポートにも使用されます。

貴社のアプリを通じてコールが行われる際には、HubSpotによって自動的に基本のエンゲージメントオブジェクトが作成され、電話拡張SDK（英語）経由で貴社のアプリにエンゲージメントのIDが送信されます。貴社のアプリへのこのIDの受け渡しには、onEngagementCreated関数が使用されます。所有者、タイプ、関連付けなど、エンゲージメントの基本的な詳細は、HubSpotによって設定されます。コールの長さを設定したり、bodyフィールドの中にコールのメモを設定したりする場合には、エンゲージメントレコードのメタデータの詳細を更新する必要があります。コールの録音がある場合は、recordingUrlを設定することにより、HubSpot上でコンタクトレコードを閲覧する際に、HubSpotユーザーが再生できるようにすることも可能です。

エンゲージメントの更新については、CRMエンゲージメントのドキュメント（英語）を参照してください。

例：

// { "engagement": { "timestamp": 1561953600000 // A millisecond timestamp of the time of the call. This will default to the time that the call was initiated, but can be updated if needed. }, "metadata": { // Details for the call "toNumber": "+1 (888) 482-7768", // The number that was called. Displayed as a string, with no further formatting. "durationMilliseconds": 38000, // The length of the call in milliseconds. "recordingUrl": "https://app.example.com/Recordings/callrecordpath", // A path to a recording of the call "body": "Call notes" // Details about the call, displayed as the description } }

上記の詳細の場合、下記の画像のようにHubSpot上にエンゲージメントとして表示されます。

コール-sdk-エンゲージメント

エンゲージメントの使い方については、CRMのエンゲージメント（英語）を参照してください。

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