Salesforce Open CTI での実装

ども、@kimihom です。

ここ最近、Salesforce Open CTI を利用して Salesforce 内で電話をするっていう実装を調査してきたのログとしてまとめる。

Salesforce Open CTI の概要

2つドキュメントが用意されているので、これらが参考のベースとなる。

help.salesforce.com

developer.salesforce.com

Salesforce 内ではメールの返信などは通常の機能でできるけど、電話は Salesforce 公式としては用意されていない。ただ、Salesforce は Open CTI として、外部で作った電話の機能を Salesforce に埋め込むことのできる機能を提供してくれている。

この OpenCTI は、簡単に言っちゃえば iframe の埋め込みだ。そしておそらく HTML5 の postMessage を使っているんだろうけど、Salesforce 側とその iframe の間でやり取りができる Open CTI の JavaScript ライブラリが用意されている。

なお、今回は Lightning Experience オンリーの想定としている。 Lightning Experience でのソフトフォンはフッターに表示されており、Salesforce 側でページ遷移が発生しても Ajax を通じてリロードが走らないため、通話が途切れることがなくなっている。Salesforce Classic では、ソフトフォンはすべての Salesforce ページの左サイドバーに表示される仕様になっていて、ページ遷移するたびにリロードが走るため電話を別ウィンドウに切り出す必要が出てくるだろう。

コールセンター定義ファイルの用意

Salesforce 側に関わる設定はほぼこのコールセンター定義ファイルだけと言って大丈夫だろう。以下のような定義ファイルを XML として用意する。

<callCenter>
  <section sortOrder="0" name="reqGeneralInfo" label="General Info">
    <item sortOrder="0" name="reqInternalName" label="Internal Name">MyAwesomeCallcenter</item>
    <item sortOrder="1" name="reqDisplayName" label="Display Name">MyAwesomeCallcenter Adapter</item>
    <item sortOrder="2" name="reqProgId" label="CTI Connector ProgId">MyAwesomeCallcenterAdapter.1</item>
    <item sortOrder="3" name="reqDescription" label="Description">This will change the world.</item>
    <item sortOrder="4" name="reqAdapterUrl" label="CTI Adapter URL">https://my-awesome-callcenter.com/salesforce</item>
    <item sortOrder="5" name="reqUseApi" label="Use CTI API">true</item>
    <item sortOrder="6" name="reqSoftphoneHeight" label="Height">550</item>
    <item sortOrder="7" name="reqSoftphoneWidth" label="Width">400</item>
    <item sortOrder="8" name="reqSalesforceCompatibilityMode" label="Salesforce Compatibility Mode">Lightning</item>
  </section>
</callCenter>

上記が必須項目となっている。お分かりの通り reqAdapterUrl で Salesforce 側に表示させる iframe URL を指定するのが一番大事な設定項目だ。 reqSalesforceCompatibilityMode にも注意しよう。ここで Lightning を指定しないと、Salesforce 側で適用しても電話アイコンが出てこないという見つけづらい問題を生んでしまう。私がどハマりしたのは、ドキュメントにある定義ファイルのサンプルをコピペすると、なんとreqSalesforceCompatabilityMode っていうまさかのスペルミスで、いつまでたっても Salesforce 側に電話の項目が出てこないという問題があるので気をつけてほしい。どこに報告すればいいかわからなかったので記事として残しておく。

なお、この reqSalesforceCompatibilityMode は、Classic_and_Lightning っていう設定項目も可能だ。ただ、読み込みする JavaScript URL が違っていたり、メソッド呼び出しや提供してる/してないメソッドがあるなどの違いがあり、このオプションを使うまでしてダブルプラットフォームに対応させるべきか否かは検討したほうがいいだろう。

さて、これら検討を終えて XML ファイルの用意ができたら、いよいよ Salesforce へその XML をアップロードしよう。設定のクイック検索から「コールセンター」で検索するとその設定ページが表示される。インポートより、その XML ファイルをアップロードしよう。そしてその後、そのコールセンターの UI を表示させる"コールセンターユーザ"を指定する。これにより、そのユーザーが定義した XML ファイルのコールセンター機能を利用できるようになる。

これだけだと単に「表示できる」ってだけなので、実際に表示する設定をする必要がある。再び検索で「アプリケーションマネージャ」から「新規 Lightning アプリケーション」を作成しよう。

コンソールナビゲーション
ユーティリティ項目に Open CTI ソフトフォンを追加
ナビゲーション項目に好きなアイテムを追加 (そのアプリケーションを開いたときに表示されるタブ)
アプリにアクセスを許可するユーザープロファイルを選択
Salesforce 左上メニュー (9つの●のとこ)をクリックして、作成した Lightning アプリケーションを選択
Lightning Experience app が起動し、フッタに "Phone" が表示されるようになる。

iframe 呼び出し側の実装

うまく iframe による呼び出しができたら、iframe 側に sfdcIframeOrigin っていう URL パラメータ付きでリクエストが飛んでくる。これで、Salesforce の Iframe からの呼び出しなのか、通常の URL リクエストなのかの判別ができる。

PC による電話の実装まで話すときりがないので省略するけど、その iframe 内で呼び出し可能な Open CTI の JavaScript ライブラリについて軽く説明する。

まずは、その iframe 側で、以下の JavaScript を読み込もう。

"#{your salesforce domain}/support/api/46.0/lightning/opencti_min.js"

この script を読み込んで初期化に成功すれば、見事 Open CTI を操作する JavaScript メソッドをゲットできる。例えば Salesforce 側で電話番号がクリックされた時のイベントを定義したり、着信が来た時にそのウィンドウを表示させ、相手情報を Salesforce で表示させることが可能だ。