<p>こんにちは、プロダクト開発部の永元です。</p>
<p>クラッソーネではCTIシステムとしてGenesysを利用しており、管理する顧客情報を連携するためにいくらかハマることがありました。将来の自分のためにも記事として残しておきます。</p>
<h2 id="cti%E3%81%A8%E3%81%AF"><a class="header-anchor-link" href="#cti%E3%81%A8%E3%81%AF" aria-hidden="true"></a> CTIとは</h2>
<p>CTIは、Computer Telephony Integrationの略称です。ざっくり説明すると、所謂コールセンターの業務をサポートするシステムです。詳細に知りたい方は<a href="https://it-trend.jp/cti/article/23-0002" target="_blank" rel="nofollow noopener noreferrer">こちら</a>をどうぞ。</p>
<h2 id="genesys%E3%81%A8%E3%81%AF"><a class="header-anchor-link" href="#genesys%E3%81%A8%E3%81%AF" aria-hidden="true"></a> Genesysとは</h2>
<blockquote>
<p>従来のコールセンターを劇的に進化させる先進のCTIシステム。それが、ジェネシスのコンタクトセンター・ソリューションです。</p>
</blockquote>
<p><a href="https://www.genesys.com/ja-jp" target="_blank" rel="nofollow noopener noreferrer">コンタクトセンター・コールセンターソリューション | オムニチャネル・カスタマーエクスペリエンス | ジェネシス</a> より</p>
<p>GenesysはCTIシステム業界では大手で機能も充実しています。CTIシステムがB向けという性質を持ち、本社がアメリカのサービスなため、大手とは言え日本での認知度は高くなく、公式サイト以外の日本語情報も少ないです。</p>
<h2 id="%E9%80%A3%E7%B5%A1%E5%85%88%E3%81%AE%E6%89%B1%E3%81%84"><a class="header-anchor-link" href="#%E9%80%A3%E7%B5%A1%E5%85%88%E3%81%AE%E6%89%B1%E3%81%84" aria-hidden="true"></a> 連絡先の扱い</h2>
<p>Genesysでは「外部の連絡先」<sup class="footnote-ref"><a href="#fn-7bc2-1" id="fnref-7bc2-1">[1]</a></sup>という名前で顧客情報を扱います。また、「外部の連絡先」には個人と組織が存在します。エンジニアとしてAPIを扱う都合上、日本語訳より英語で覚えることをおすすめします。<br />
外部の連絡先 → external contacts<br />
外部の連絡先(個人) → external contacts(contacts)<br />
外部の連絡先(組織) → external contacts(organizations)</p>
<h2 id="%E3%83%8F%E3%83%9E%E3%82%8A%E3%83%9D%E3%82%A4%E3%83%B3%E3%83%88"><a class="header-anchor-link" href="#%E3%83%8F%E3%83%9E%E3%82%8A%E3%83%9D%E3%82%A4%E3%83%B3%E3%83%88" aria-hidden="true"></a> ハマりポイント</h2>
<p>新しいサービスを利用開始するときは多少ハマるのは当たり前だと思います。ここでは私が特にハマったことを紹介します。</p>
<h3 id="%E5%85%AC%E5%BC%8F%E3%83%89%E3%82%AD%E3%83%A5%E3%83%A1%E3%83%B3%E3%83%88%E3%83%9A%E3%83%BC%E3%82%B8%E3%81%AE%E9%96%B2%E8%A6%A7%E3%81%AB%E5%B0%91%E3%81%97%E6%85%A3%E3%82%8C%E3%81%8C%E5%BF%85%E8%A6%81"><a class="header-anchor-link" href="#%E5%85%AC%E5%BC%8F%E3%83%89%E3%82%AD%E3%83%A5%E3%83%A1%E3%83%B3%E3%83%88%E3%83%9A%E3%83%BC%E3%82%B8%E3%81%AE%E9%96%B2%E8%A6%A7%E3%81%AB%E5%B0%91%E3%81%97%E6%85%A3%E3%82%8C%E3%81%8C%E5%BF%85%E8%A6%81" aria-hidden="true"></a> 公式ドキュメントページの閲覧に少し慣れが必要</h3>
<p>公式ドキュメントは充実しており、うまく検索できれば目的の情報は見つかります。ただ少し慣れが必要です。</p>
<p>公式ドキュメントページは<a href="https://help.mypurecloud.com/" target="_blank" rel="nofollow noopener noreferrer">Resource Center</a>と<a href="https://developer.genesys.cloud/" target="_blank" rel="nofollow noopener noreferrer">Developer Center</a>と大きく2つに分かれていますが、統一感のあるデザインのため、混同しないように注意しましょう。開発者向けの情報はDeveloper Centerを当たりましょう。Resource Centerの検索ボックスからはサンプルコードなどの開発者が求める情報には辿り着けません。(自戒)</p>
<p>日本語のページもそれなりに存在しますが、英語ページしか存在しないことがよくあるため、最初から英語のページを見るのがおすすめです。</p>
<h4 id="%E7%89%B9%E3%81%AB%E3%82%88%E3%81%8F%E9%96%B2%E8%A6%A7%E3%81%99%E3%82%8B%E3%83%9A%E3%83%BC%E3%82%B8"><a class="header-anchor-link" href="#%E7%89%B9%E3%81%AB%E3%82%88%E3%81%8F%E9%96%B2%E8%A6%A7%E3%81%99%E3%82%8B%E3%83%9A%E3%83%BC%E3%82%B8" aria-hidden="true"></a> 特によく閲覧するページ</h4>
<ul>
<li><a href="https://developer.dev-genesys.cloud/api/rest/v2/externalcontacts/" target="_blank" rel="nofollow noopener noreferrer">External Contacts</a>: 外部連絡先関連のAPI一覧できます。顧客情報に関するAPIはだいたいここを見ればなんとかなります。</li>
<li><a href="https://developer.genesys.cloud/api/rest/client-libraries/#-i-class--devicon-javascript-guest-plain-colored----i--guest-chat-client---javascript" target="_blank" rel="nofollow noopener noreferrer">Software Development Kit (SDK)</a>: 各SDKとそのサンプルコードが一覧できます。</li>
<li><a href="https://developer.genesys.cloud/api/tutorials/" target="_blank" rel="nofollow noopener noreferrer">Tutorials</a>: 各環境・言語における様々な利用シーンのチュートリアル(サンプルコード)を一覧できます。自分の目的に近いサンプルが掲載されているととても嬉しいです。</li>
<li><a href="https://developer.genesys.cloud/developer-tools/" target="_blank" rel="nofollow noopener noreferrer">Developer Tools</a>: ブラウザで動作する開発者向けツールです。色んなAPIを試しに呼び出したり、サンプルコードを動かしたりできて便利です。</li>
</ul>
<h3 id="api%E5%88%A9%E7%94%A8%E3%82%92%E5%A7%8B%E3%82%81%E3%82%8B%E3%81%9F%E3%82%81%E3%81%ABweb%E3%82%A2%E3%83%97%E3%83%AA%E4%B8%8A%E3%81%8B%E3%82%89%E4%BA%8B%E5%89%8D%E6%BA%96%E5%82%99%E3%81%8C%E5%BF%85%E8%A6%81"><a class="header-anchor-link" href="#api%E5%88%A9%E7%94%A8%E3%82%92%E5%A7%8B%E3%82%81%E3%82%8B%E3%81%9F%E3%82%81%E3%81%ABweb%E3%82%A2%E3%83%97%E3%83%AA%E4%B8%8A%E3%81%8B%E3%82%89%E4%BA%8B%E5%89%8D%E6%BA%96%E5%82%99%E3%81%8C%E5%BF%85%E8%A6%81" aria-hidden="true"></a> API利用を始めるためにWEBアプリ上から事前準備が必要</h3>
<p>よくある話ではありますが、GenesysでもAPI利用を可能にする事前設定が必要です。利用する認証方法に応じた設定をしましょう。日本語・英語両方のヘルプページを貼っておきますが、APIやその認証方法に詳しい人は英語版だけを読んだほう理解が早いと思います。<br />
<a href="https://help.mypurecloud.com/articles/create-an-oauth-client/" target="_blank" rel="nofollow noopener noreferrer">Create an OAuth client - Genesys Cloud Resource Center</a><br />
<a href="https://jp-help.mypurecloud.com/articles/create-an-oauth-client/" target="_blank" rel="nofollow noopener noreferrer">OAuthクライアントを作成する-Genesysクラウドリソースセンター</a></p>
<p>GenesysAPIは複数の認証方法に対応しています。次のリンクを参照し、利用シーンに適した認証方法を選びましょう。<br style="display:none" />
<span class="embed-block zenn-embedded zenn-embedded-link-card"><iframe id="zenn-embedded__6d675165a744c" src="https://embed.zenn.studio/link-card#zenn-embedded__6d675165a744c" data-content="https%3A%2F%2Fdeveloper.genesys.cloud%2Fapi%2Frest%2Fauthorization%2F" frameborder="0" scrolling="no" loading="lazy"></iframe></span><a href="https://developer.genesys.cloud/api/rest/authorization/" style="display:none" target="_blank" rel="nofollow noopener noreferrer">https://developer.genesys.cloud/api/rest/authorization/</a></p>
<h3 id="ruby%E3%81%AEsdk%E3%81%8C%E3%81%AA%E3%81%84"><a class="header-anchor-link" href="#ruby%E3%81%AEsdk%E3%81%8C%E3%81%AA%E3%81%84" aria-hidden="true"></a> RubyのSDKがない</h3>
<p>厳密には「サポート中のRuby SDKがない」です。<br />
<a href="https://help.mypurecloud.com/articles/deprecation-genesys-cloud-ruby-sdk/" target="_blank" rel="nofollow noopener noreferrer">Deprecation: Genesys Cloud Ruby SDK - Genesys Cloud Resource Center</a><br />
Deprecationですが<a href="https://github.com/MyPureCloud/platform-client-sdk-ruby" target="_blank" rel="nofollow noopener noreferrer">Ruby SDKはGitHubに公開されている</a>ので参考にすることは可能です。実際に弊社では参考にして認証部分の実装を行いました。</p>
<p>Rubyにはありませんが、JavaScriptを始め、主要言語で複数種類のSDKが提供されています。公式SDKが豊富なのは非常にありがたいです。</p>
<h3 id="%E9%80%A3%E7%B5%A1%E5%85%88%E3%81%AE%E3%83%90%E3%83%AA%E3%83%87%E3%83%BC%E3%82%B7%E3%83%A7%E3%83%B3"><a class="header-anchor-link" href="#%E9%80%A3%E7%B5%A1%E5%85%88%E3%81%AE%E3%83%90%E3%83%AA%E3%83%87%E3%83%BC%E3%82%B7%E3%83%A7%E3%83%B3" aria-hidden="true"></a> 連絡先のバリデーション</h3>
<p>外部の連絡先(個人)の場合は姓・名が必須です。姓と名を分けずに管理しているところは対応が必要そうです。<br />
姓: 鈴木一郎<br />
名: .<br />
のように姓と名どちらかにフルネームで設定し、使わない方に意味はなくとも何某かの文字を設定する…といった回避方法はありますが、あまりおすすめしません。Genesysの担当者と自社の状況を踏まえて相談しましょう。</p>
<p>外部の連絡先(組織)の場合は組織名のみ必須です。こちらは特に躓くことはなさそうです。</p>
<h3 id="%E9%9B%BB%E8%A9%B1%E7%95%AA%E5%8F%B7%E3%81%AE%E5%BD%A2%E5%BC%8F"><a class="header-anchor-link" href="#%E9%9B%BB%E8%A9%B1%E7%95%AA%E5%8F%B7%E3%81%AE%E5%BD%A2%E5%BC%8F" aria-hidden="true"></a> 電話番号の形式</h3>
<p>"090xxxxxxxx"<br />
は電話番号として認識されません。電話番号冒頭の0は国内を意味するプレフィックスであり、GenesysのAPI利用時には日本の電話番号であることを明示する必要があるためです。冒頭の"0"を"+81"に置換した"+8190xxxxxxxx"であれば日本の携帯電話番号として認識され、APIから登録が可能です。</p>
<p>ちなみにGenesysのWEBアプリから入力するときは自動的にデフォルトで設定されている国コードに変換して保存してくれます。そのおかげでAPI利用時のエラー原因に気づきにくいです。</p>
<p>※電話番号のプレフィックスなど詳細については<a href="https://www.soumu.go.jp/main_sosiki/joho_tsusin/top/tel_number/q_and_a.html" target="_blank" rel="nofollow noopener noreferrer">総務省｜電気通信番号制度｜電話番号に関するQ&amp;A</a>の参照をおすすめします</p>
<h3 id="%E9%9B%BB%E8%A9%B1%E7%95%AA%E5%8F%B7%E6%A4%9C%E7%B4%A2%E3%81%AB%E7%99%96%E3%81%8C%E3%81%82%E3%82%8B"><a class="header-anchor-link" href="#%E9%9B%BB%E8%A9%B1%E7%95%AA%E5%8F%B7%E6%A4%9C%E7%B4%A2%E3%81%AB%E7%99%96%E3%81%8C%E3%81%82%E3%82%8B" aria-hidden="true"></a> 電話番号検索に癖がある</h3>
<p>"090xxxxxxxx"<br />
という携帯電話番号について検索したいときは<br />
"90-xxxx-xxxx"<br />
で検索しましょう。</p>
<p>冒頭の国を表すプレフィックスは削除し、ハイフン(全角半角どちらでも可らしい)ありの形式であればHITします。これを知らないと、<br />
「APIで外部の連絡先を作成して200レスポンスだったけど、作成したはずの連絡先が見つからない」<br />
と焦ることになります。(自戒)</p>
<p>また、この仕様はAPIを利用した検索・WEBアプリ上の検索どちらも同じ仕様です。Genesysで電話対応を行うスタッフにこそ、知らせたいです。</p>
<h2 id="%E6%9C%80%E5%BE%8C%E3%81%AB"><a class="header-anchor-link" href="#%E6%9C%80%E5%BE%8C%E3%81%AB" aria-hidden="true"></a> 最後に</h2>
<p>ハマった後に「早く担当者に聞いておけばよかったな。聞いたらすぐ解決してたな。」という反省が私にはありました。Genesysに限らず、新しいツール・サービスの利用を始めるときに多少ハマるのは仕方のないことです。早めに積極的に問い合わせていきたいですね。</p>
<h2 id="we-are-hiring!"><a class="header-anchor-link" href="#we-are-hiring!" aria-hidden="true"></a> We Are Hiring!</h2>
<p>クラッソーネに少しでも興味を持っていただけたらぜひお気軽にご連絡ください。</p>
<p><span class="embed-block zenn-embedded zenn-embedded-link-card"><iframe id="zenn-embedded__653755dbd4a18" src="https://embed.zenn.studio/link-card#zenn-embedded__653755dbd4a18" data-content="https%3A%2F%2Fwww.crassone.co.jp%2Frecruit%2Fengineer%2F" frameborder="0" scrolling="no" loading="lazy"></iframe></span><a href="https://www.crassone.co.jp/recruit/engineer/" style="display:none" target="_blank" rel="nofollow noopener noreferrer">https://www.crassone.co.jp/recruit/engineer/</a></p>
<section class="footnotes">
<span class="footnotes-title">脚注</span>
<ol class="footnotes-list">
<li id="fn-7bc2-1" class="footnote-item"><p>コールセンターのメンバーが内部。電話をかける・かけてくる相手が外部という扱いらしいです。 <a href="#fnref-7bc2-1" class="footnote-backref">↩︎</a></p>
</li>
</ol>
</section>



こんにちは、プロダクト開発部の永元です。

クラッソーネではCTIシステムとしてGenesysを利用しており、管理する顧客情報を連携するためにいくらかハマることがありました。将来の自分のためにも記事として残しておきます。

CTIとは
CTIは、Computer Telephony Integrationの略称です。ざっくり説明すると、所謂コールセンターの業務をサポートするシステムです。詳細に知りたい方はこちらをどうぞ。

Genesysとは
>従来のコールセンターを劇的に進化させる先進のCTIシステム。それが、ジェネシスのコンタクトセンター・ソリューションです。

コンタクトセンター・コールセンターソリューション | オムニチャネル・カスタマーエクスペリエンス | ジェネシス より

GenesysはCTIシステム業界では大手で機能も充実しています。CTIシステムがB向けという性質を持ち、本社がアメリカのサービスなため、大手とは言え日本での認知度は高くなく、公式サイト以外の日本語情報も少ないです。

連絡先の扱い
Genesysでは「外部の連絡先」という名前で顧客情報を扱います。また、「外部の連絡先」には個人と組織が存在します。エンジニアとしてAPIを扱う都合上、日本語訳より英語で覚えることをおすすめします。
外部の連絡先 → external contacts
外部の連絡先(個人) → external contacts(contacts)
外部の連絡先(組織) → external contacts(organizations)

: コールセンターのメンバーが内部。電話をかける・かけてくる相手が外部という扱いらしいです。

ハマりポイント
新しいサービスを利用開始するときは多少ハマるのは当たり前だと思います。ここでは私が特にハマったことを紹介します。

公式ドキュメントページの閲覧に少し慣れが必要
公式ドキュメントは充実しており、うまく検索できれば目的の情報は見つかります。ただ少し慣れが必要です。

公式ドキュメントページはResource CenterとDeveloper Centerと大きく2つに分かれていますが、統一感のあるデザインのため、混同しないように注意しましょう。開発者向けの情報はDeveloper Centerを当たりましょう。Resource Centerの検索ボックスからはサンプルコードなどの開発者が求める情報には辿り着けません。(自戒)

日本語のページもそれなりに存在しますが、英語ページしか存在しないことがよくあるため、最初から英語のページを見るのがおすすめです。

特によく閲覧するページ
External Contacts: 外部連絡先関連のAPI一覧できます。顧客情報に関するAPIはだいたいここを見ればなんとかなります。
Software Development Kit (SDK): 各SDKとそのサンプルコードが一覧できます。
Tutorials: 各環境・言語における様々な利用シーンのチュートリアル(サンプルコード)を一覧できます。自分の目的に近いサンプルが掲載されているととても嬉しいです。
Developer Tools: ブラウザで動作する開発者向けツールです。色んなAPIを試しに呼び出したり、サンプルコードを動かしたりできて便利です。

API利用を始めるためにWEBアプリ上から事前準備が必要
よくある話ではありますが、GenesysでもAPI利用を可能にする事前設定が必要です。利用する認証方法に応じた設定をしましょう。日本語・英語両方のヘルプページを貼っておきますが、APIやその認証方法に詳しい人は英語版だけを読んだほう理解が早いと思います。
Create an OAuth client - Genesys Cloud Resource Center
OAuthクライアントを作成する-Genesysクラウドリソースセンター

GenesysAPIは複数の認証方法に対応しています。次のリンクを参照し、利用シーンに適した認証方法を選びましょう。
https://developer.genesys.cloud/api/rest/authorization/

RubyのSDKがない
厳密には「サポート中のRuby SDKがない」です。
Deprecation: Genesys Cloud Ruby SDK - Genesys Cloud Resource Center
DeprecationですがRuby SDKはGitHubに公開されているので参考にすることは可能です。実際に弊社では参考にして認証部分の実装を行いました。

Rubyにはありませんが、JavaScriptを始め、主要言語で複数種類のSDKが提供されています。公式SDKが豊富なのは非常にありがたいです。

連絡先のバリデーション
外部の連絡先(個人)の場合は姓・名が必須です。姓と名を分けずに管理しているところは対応が必要そうです。
姓: 鈴木一郎
名: .
のように姓と名どちらかにフルネームで設定し、使わない方に意味はなくとも何某かの文字を設定する…といった回避方法はありますが、あまりおすすめしません。Genesysの担当者と自社の状況を踏まえて相談しましょう。

外部の連絡先(組織)の場合は組織名のみ必須です。こちらは特に躓くことはなさそうです。

電話番号の形式
"090xxxxxxxx"
は電話番号として認識されません。電話番号冒頭の0は国内を意味するプレフィックスであり、GenesysのAPI利用時には日本の電話番号であることを明示する必要があるためです。冒頭の"0"を"+81"に置換した"+8190xxxxxxxx"であれば日本の携帯電話番号として認識され、APIから登録が可能です。

ちなみにGenesysのWEBアプリから入力するときは自動的にデフォルトで設定されている国コードに変換して保存してくれます。そのおかげでAPI利用時のエラー原因に気づきにくいです。

※電話番号のプレフィックスなど詳細については総務省｜電気通信番号制度｜電話番号に関するQ&Aの参照をおすすめします

電話番号検索に癖がある
"090xxxxxxxx"
という携帯電話番号について検索したいときは
"90-xxxx-xxxx"
で検索しましょう。

冒頭の国を表すプレフィックスは削除し、ハイフン(全角半角どちらでも可らしい)ありの形式であればHITします。これを知らないと、
「APIで外部の連絡先を作成して200レスポンスだったけど、作成したはずの連絡先が見つからない」
と焦ることになります。(自戒)

また、この仕様はAPIを利用した検索・WEBアプリ上の検索どちらも同じ仕様です。Genesysで電話対応を行うスタッフにこそ、知らせたいです。

最後に
ハマった後に「早く担当者に聞いておけばよかったな。聞いたらすぐ解決してたな。」という反省が私にはありました。Genesysに限らず、新しいツール・サービスの利用を始めるときに多少ハマるのは仕方のないことです。早めに積極的に問い合わせていきたいですね。

We Are Hiring!
クラッソーネに少しでも興味を持っていただけたらぜひお気軽にご連絡ください。

https://www.crassone.co.jp/recruit/engineer/


クラッソーネ開発者ブログ

永元雄宙が執筆した記事

Genesys入門時にハマったポイント

永元 雄宙が執筆した記事

Genesys入門時にハマったポイント

永元雄宙が執筆した記事