電話拡張SDK
アプリで電話拡張SDK(英語)を使用すると、CRMレコード内で直接、HubSpotユーザーに対して通話のカスタムオプションを提供できます。
電話拡張は、次の3つのコンポーネントで構成されています。
- 電話拡張SDK(英語)。貴社のアプリとHubSpot間の通信を可能にするJavaScript SDK。
- コール設定エンドポイント。貴社のアプリのコール設定のために使用するエンドポイント。この設定は、アプリに接続する各HubSpotアカウントで使用されます。
- コール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の使用例をご覧ください。
注:これらのデモアプリは完全に機能する通話アプリではなく、より現実的なエクスペリエンスを提供するために、モックデータを使用します。
インストールの有無にかかわらず、デモアプリを実行できます。ローカル環境にデモをインストールするには:
- お使いの環境にNode.jsをインストールします。
- このリポジトリのZIPをダウンロード、複製、またはフォークします。
- ターミナルを開き、プロジェクトのルートディレクトリーに移動します。
- 次のコマンドのいずれかを実行します。
demo-minimal-js
の場合:
demo-react-ts
の場合:
npm start
コマンドを実行すると、https://localhost:9025/に接続された新しいブラウザータブが自動的に開きます。アプリケーションにアクセスするには、「接続がセキュリティーで保護されていない」ことを通知するメッセージをバイパスする必要があります。
- レコードに移動します。
- コンタクト:HubSpotアカウントで、[コンタクト]>[コンタクト]に移動します。
- 会社:HubSpotアカウントで、[コンタクト]>[キャンペーン]に移動します。
- ブラウザーの開発者コンソールを開き、次のコマンドを実行します。
demo-minimal-js
またはdemo-react-ts
のインストール手順が完了している場合:
- インストール手順をスキップした場合:
demo-minimal-js
の場合:
demo-react-ts
の場合:
- ページを更新し、左側のサイドバーのコールアイコンをクリックします。[発信元]ドロップダウンメニューをクリックして、その中からデモアプリの名前を選択します(例:Demo App Local、Demo App JS、Demo App React)。
- [コール]をクリックして、デモアプリが電話拡張SDKを介してHubSpotとどのように連携しているかを確認します。また、ブラウザーの開発者コンソールに記録されたイベントも表示できます。
電話拡張SDKをNode.jsの依存関係として通話アプリに追加するには:
- npmの場合は次を実行します。
- yarnの場合は次を実行します。
電話拡張SDKはメッセージを交換のために、HubSpot用のシンプルなAPIと通話アプリを公開します。メッセージは、SDKによって公開された方法で送信され、eventHandlers
を介して受信されます。
イベントの説明は次のとおりです。
- 番号をダイヤルする:HubSpotは番号ダイヤルイベント送信します。
- 発信通話が開始された:通話が開始されると、アプリがHubSpotに通知します。
- エンゲージメントを作成する:HubSpotは、アプリから要求された場合、最小限の情報でコールエンゲージメントを作成します。
- エンゲージメントが作成された:HubSpotがエンゲージメントを作成しました。
- EngagementIdがアプリに送信された:HubSpotが
engagementId
をアプリに送信します。 - 通話が終了した:通話が終了するとアプリが通知します。
- 通話が完了しました:ユーザーがアプリのユーザー体験を完了するとアプリが通知します。
- エンゲージメントを更新する:アプリは
engagementId
によってエンゲージメントを取得し、その他の通話の詳細とエンゲージメントをマージして更新します。コールエンゲージメントの更新の詳細については、こちらをご覧ください。
まず、CallingExtensions
オブジェクトのインスタンスを作成します。拡張機能インスタンスを作成するときにオプションのオブジェクトを指定することで、拡張機能の動作を定義できます。このオプションのオブジェクトは、拡張機能の動作を指定できるeventHandlers
フィールドを提供します。次のコードブロックは、使用可能なオプションと定義可能なイベントハンドラーを示しています。
extensions
オブジェクトは、HubSpotにメッセージを送信したり、他の関連する動作を指定したりするために呼び出すことができる、次のイベントハンドラーを提供します。後述の例を参照してください。
initialized
:ソフトフォンのインタラクションの準備ができていることを示すメッセージを送信します。
userLoggedIn
:ユーザーがログインしたことを示すメッセージを送信します。
userLoggedOut
:ユーザーがログアウトしたことを示すメッセージを送信します。
outgoingCall
:発信通話が開始されたことをHubSpotに通知するメッセージを送信します。
callAnswered
:発信通話が応答されていることをHubSpotに通知するメッセージを送信します。
callEnded
:通話が終了したことをHubSpotに通知するメッセージを送信します。
callCompleted
:通話が完了したことをHubSpotに通知するメッセージを送信します。
sendError
:通話アプリでエラーが発生したことをHubSpotに通知するメッセージを送信します。
resizeWidget
:通話アプリのサイズを変更する必要があることをHubSpotに通知するメッセージを送信します。
extensions
オブジェクトは、HubSpotでメッセージを受信するとき、または他の関連する動作を指定するときに呼び出すことができる、次のイベントハンドラーを提供します。後述の例を参照してください。
onReady
:HubSpotがメッセージを受信する準備ができていることを示すメッセージ。
onDial
:ユーザーが発信通話をトリガーしたことを示すメッセージ。
onEngagementCreated
:HubSpotがonEngagementCreated
データを作成したことを示すメッセージ。
onVisibilityChanged
:ユーザーが通話アプリを最小化または非表示にしたかどうかを示すメッセージ。
defaultEventHandler
:イベントの既定のハンドラー。
アプリケーションの開発中に、localStorage
値を設定することにより、ブラウザーのiframe URLを手動で設定できます。これにより、ローカルテスト用のlocalhost URLを設定できます。
この値を設定するには、ブラウザーの開発者ツールを開き、開発者コンソールで次のJavaScriptコマンドを実行します。
nameの値は通話アプリのヘッダーに表示されるタイトルとなり、urlはiframeに使用されるURLになります。この項目を設定すると、設定したnameがコールアイコンのクリック時に電話事業者のオプションとして表示され、設定したiframeのurlが通話アプリに使用されます。
APIツール(Postmanなど)を使用して、このペイロードを設定APIに送信します。通話アプリケーションのAPP_IDとアプリのDEVELOPER_ACCOUNT_API_KEYを取得してください。
isReady
フラグは、アプリの本番環境用の準備ができているかどうかを示します。テスト中、このフラグはfalseに設定される必要があります。
localStorage
を使用して上書きできます。
アプリのセットアップが完了したら、最後のステップとしてHubSpotマーケットプレイスに通話アプリを掲載します。詳細については、こちらをご覧ください。また、このアプリケーションが社内専用である場合は、マーケットプレイスに掲載しないという選択もできます。
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を使用していることを確認します。
createEngagement
がtrueの場合、こちらからアプリ情報を更新する方法をご覧ください。
outgoingCall
イベント全体の例を次に示します。
さらにサポートが必要な場合は、HubSpot開発者サポートフォーラムをご覧ください。
貴重なご意見をありがとうございました。