Zoho SalesIQのVisitor APIで詰まった話: ドキュメントにあるAPI Permissionsが画面に出ないとき
かなり細かい話ですが、Zoho SalesIQでWebサイトの訪問者データを公式APIから取得しようとして、少し詰まりました。
やりたかったことは単純です。
SalesIQの管理画面で見えている訪問者情報を、週次のブログ改善やCRM/AIのフィードバックループに使えるように、公式REST APIから取得したい。
公式ドキュメントを見ると、訪問者一覧APIは用意されています。
ただ、実際に進めると、ドキュメント上の説明と管理画面の見え方が一致しないところがありました。
ドキュメント上の前提
Zoho SalesIQの訪問者一覧APIは、次のようなURLで呼び出します。
https://{SalesIQ server URI}/api/v3/{screenname}/visitors
JPデータセンターの場合、SalesIQ server URIは salesiq.zoho.jp です。
OAuth scopeは、ドキュメント上では visitors.READ とされています。API Console側ではSalesIQ用のscope名として扱う必要があります。
そして重要なのが、ドキュメント内の注意書きです。
このAPIを使うには、SalesIQの Settings > Portal Settings > API Permissions で Basic visitor information を有効化する必要があります。
ここまでは自然です。API Consoleでscopeを付け、SalesIQ側でも訪問者情報の取得許可をオンにする。一般的な二段階の権限設定に見えます。
実際に困ったところ
問題は、管理画面に API Permissions のメニューが見当たらなかったことです。
公式ドキュメントには「ここを有効化する」と書いてある。しかし、現在の画面ではそのメニューが見えない。
この状態でAPIを叩くと、OAuth token自体は通っているように見えるのに、訪問者一覧APIは失敗します。
今回のケースでは、最初は次のような意味のエラーで止まりました。
Visitor Feature not enabled in this plan
ここでややこしいのは、「プランに存在しない」と決めつけると早計なことです。
SalesIQの画面上では訪問者データが見えている。ドキュメント上もvisitor list APIは存在している。けれど、API Permissionsメニューが画面に出ていない。
つまり、単純なOAuth scope不足ではなく、SalesIQポータル側の機能有効化状態が噛んでいる可能性があります。
サポートに確認したこと
最終的には、Zohoサポートに次の点を確認しました。
- JPデータセンターのSalesIQでも、API Permissionsメニューは利用できるのか
- メニューの場所がドキュメントと違うのか
- Zoho One契約のSalesIQポータルでも、Basic visitor informationを有効化できるのか
- 管理者権限、プラン、追加設定など、表示条件があるのか
ここでは、個別のポータルID、アカウントID、担当者名、サポートチケット番号などは書きません。
結論だけを書くと、今回の環境では、利用者自身の画面操作だけではなく、バックエンド側での有効化が必要でした。
サポート経由で有効化してもらったあと、管理画面上にもAPI Permissions相当の設定が表示され、公式v3 APIから訪問者一覧を取得できるようになりました。
取得できるようになった後の挙動
有効化後は、以前出ていた Visitor Feature not enabled in this plan のエラーは消えました。
実際に公式APIで訪問者データを取得できました。
ただし、ページングの指定には注意が必要でした。
訪問者一覧APIには prev_key と next_key があります。今回、直近から過去に向かって取得する用途では、prev_key に現在時刻のミリ秒を指定する形がうまく動きました。
GET https://salesiq.zoho.jp/api/v3/{screenname}/visitors?limit=50&prev_key={current_time_ms}
一方で、過去時刻を next_key に入れる形では、条件に一致する訪問者がないという応答になることがありました。
このあたりは、ドキュメントを読んだだけでは少し分かりにくいところです。
取得できた情報と、取れなかった情報
公式v3の訪問者一覧APIで取れたのは、主に次のような基本情報です。
- 国
- 地域、都市
- Lead Score
- 訪問回数
- 初回アクセス時刻
- 最終アクセス時刻
これは、訪問者の大まかな傾向を見るには十分役立ちます。
たとえば、どの地域からアクセスがあるのか、再訪している人がいるのか、SalesIQ上でスコアが付いている訪問者がいるのか、といった確認ができます。
一方で、今回の取得範囲では、ブログ改善に使いたい次の情報までは十分に取れませんでした。
- どの記事を見たか
- どのURLから来たか
- LinkedIn経由か
- UTM campaignは何か
- どのCTAに反応したか
ここは、SalesIQの別API、PageSense、サイト側のイベント計測、またはSalesIQの画面上の訪問詳細を組み合わせて見る必要があります。
つまり、公式v3 visitor list APIは「訪問者の一覧と基本属性」を取るAPIであって、「マーケティング導線を全部分析するAPI」として期待しすぎないほうがよさそうです。
実務上の教訓
今回の教訓は、かなり地味ですが重要です。
公式ドキュメントに書いてある機能でも、画面にメニューが出ないことがある。
このときに、すぐ非公開の方法で無理に進めるのではなく、まずは次の順番で確認するのが安全です。
- データセンターに合ったserver URIを使っているか
- OAuth scopeが正しいか
- screen nameが正しいか
- ドキュメント上のPortal Settings / API Permissionsが画面にあるか
- なければ、サポートに「このドキュメントのこの機能を有効化したい」と問い合わせる
特にZohoのように製品数が多く、データセンターや契約形態も複数あるサービスでは、ドキュメント、画面、契約、バックエンド設定が完全に同じタイミングで揃っているとは限りません。
公式APIを使う場合でも、実務ではこのズレを丁寧に潰す必要があります。
CRM/AIの文脈で見ると
なぜここまでしてSalesIQの訪問者データを取りたいのか。
それは、ブログやWebサイトの反応を、次の記事やCRMの文脈づくりに戻したいからです。
たとえば、記事を公開する。LinkedInで共有する。訪問者が来る。地域や再訪の傾向を見る。問い合わせやCTA反応と合わせて、次に何を書くべきか、どの導線を改善すべきかを考える。
これは、小さなSystem of Contextです。
ただし、そのためには、まず公式に取得できるデータの範囲をはっきりさせる必要があります。
今回分かったのは、SalesIQの公式visitor list APIは、Basic visitor informationが有効になれば基本情報の取得には使えるということです。
そして、画面にAPI Permissionsが出ない場合でも、サポートに相談することで、正規のルートで有効化できる場合があります。
かなりマニアックですが、こういう小さな詰まりを一つずつ解消していくと、CRMやWeb解析のデータをAIが扱える形に近づけられます。
裏技ではなく、公式機能を組み合わせて、記録から文脈へ、文脈から次の行動へつなげていく。
今回のSalesIQ API Permissionsの件は、そのための地味だけれど大事な一歩でした。
