執筆者：Salesforce 統合エンジニア
背景と応用シナリオ
現代のビジネス環境において、顧客との接点は多岐にわたります。ウェブサイト、モバイルアプリ、ソーシャルメディア、メッセージングアプリなど、顧客が利用するチャネルは日々多様化しています。これらすべてのチャネルで一貫性のある優れた顧客体験を提供することが、企業にとっての大きな課題であり、成功の鍵となります。ここで中心的な役割を果たすのが Salesforce の Digital Engagement (デジタルエンゲージメント) 機能です。
Digital Engagement は、Service Cloud の一部として提供され、SMS、WhatsApp、Facebook Messenger、そしてカスタムのメッセージングチャネルなど、さまざまなデジタルチャネルを Salesforce プラットフォームに統合し、顧客との対話を一元管理することを可能にします。これにより、サービスエージェントは慣れ親しんだ Service Console 上で、複数のチャネルからの問い合わせに効率的に対応できます。
私たち Salesforce Integration Engineer (Salesforce 統合エンジニア) の視点から見ると、Digital Engagement の真価は、その標準機能だけでなく、API を通じた柔軟な拡張性にあります。多くの企業は、独自のブランド体験を提供するためにカスタムビルドのモバイルアプリやウェブアプリケーションを保有しています。これらのカスタムアプリケーション内にチャットやメッセージング機能を組み込み、それを Salesforce のサービス基盤とシームレスに連携させたいというニーズは非常に高まっています。
応用シナリオ
具体的なシナリオを考えてみましょう。ある金融機関が、自社のモバイルバンキングアプリ内にセキュアなメッセージング機能を実装しています。顧客がアプリから住宅ローンに関する質問をすると、そのメッセージが Salesforce Service Cloud に自動的にルーティングされ、専門のエージェントに割り当てられます。エージェントは Service Console から応答し、その返信はリアルタイムで顧客のモバイルアプリに表示されます。この対話の履歴はすべて Salesforce の顧客レコードに紐づき、後から参照可能です。
このような高度な連携を実現するためには、Salesforce が提供する Messaging for In-App and Web REST API の活用が不可欠です。この API を利用することで、外部システムはプログラム経由で Salesforce とのメッセージングセッションを開始、メッセージを送受信し、セッションを終了させることができます。本記事では、統合エンジニアの視点から、この API を活用してカスタムメッセージングチャネルを Salesforce に統合するための原理、具体的な実装方法、そして注意点について詳しく解説します。
原理説明
Salesforce の Digital Engagement を API 経由で統合する際の仕組みを理解するためには、いくつかの主要なコンポーネントと API の流れを把握する必要があります。中心となるのは Messaging for In-App and Web REST API であり、この API は外部アプリケーション（クライアント）と Salesforce 間で非同期のメッセージング対話を実現するためのエンドポイントを提供します。
主要コンポーネント
1. Messaging Channel (メッセージングチャネル):
これは Salesforce 側での設定項目であり、統合する外部チャネル（例：自社モバイルアプリ）を定義します。設定時に一意の Developer Name (開発者名) と Messaging Platform Key (メッセージングプラットフォームキー) が生成されます。API リクエストを送信する際、これらの情報を使ってどのチャネルへのリクエストであるかを識別します。
2. Connected App (接続アプリケーション):
外部アプリケーションが Salesforce API にアクセスするための認証・認可の仕組みです。OAuth 2.0 プロトコルを利用して、安全にアクセストークンを取得します。統合エンジニアは、適切なスコープ（例えば `api`, `messaging_user` など）を持つ接続アプリケーションを作成し、そのコンシューマキーとコンシューマシークレットを外部アプリケーション側で安全に管理する必要があります。
3. Messaging Session (メッセージングセッション):
一人のエンドユーザー（顧客）とエージェントとの間の一連の対話を表すオブジェクトです。外部アプリケーションが対話を開始する際に、API を通じてこのセッションを作成します。セッションがアクティブである間、メッセージの送受信が行われます。
4. Messaging User (メッセージングユーザー):
対話を行うエンドユーザーを表すオブジェクトです。通常、Contact (取引先責任者) や Lead (リード) レコードと関連付けられます。
5. Conversation (会話):
メッセージングセッション内で、特定のエージェントとエンドユーザーの間で行われる具体的なやり取りの単位です。API はこの会話 ID を使ってメッセージを送信します。
API のフロー
典型的な統合フローは以下のようになります。
ステップ 1: 認証とアクセストークンの取得
外部アプリケーションは、事前に設定された Salesforce の Connected App の情報（コンシューマキー、シークレットなど）を使い、OAuth 2.0 フロー（例えば JWT Bearer Flow や Web Server Flow）を実行してアクセストークンを取得します。以降の API リクエストでは、このアクセストークンを `Authorization` ヘッダーに含めて送信します。
ステップ 2: メッセージングセッションの開始
エンドユーザーがカスタムアプリでチャットを開始すると、外部アプリケーションは Salesforce の /messaging/sessions エンドポイントに対して POST リクエストを送信します。リクエストボディには、どのチャネルを使用するかを示す `messagingPlatformKey` や、エンドユーザーの情報（名前、メールアドレスなど）を含めます。成功すると、Salesforce は `sessionId` や `conversationId` を含むレスポンスを返します。
ステップ 3: メッセージの送信
エンドユーザーからのメッセージは、/messaging/conversations/{conversationId}/messages エンドポイントへの POST リクエストによって Salesforce に送信されます。このリクエストを受け取った Salesforce は、Service Console 上でエージェントに新しいメッセージとして表示します。
逆に、エージェントが Service Console から返信すると、Salesforce は設定された Outbound Notification Webhook に対してそのメッセージ内容を POST します。外部アプリケーション側では、この Webhook を受け取るエンドポイントを実装し、受け取ったメッセージをリアルタイムでエンドユーザーの画面に表示する必要があります。
ステップ 4: メッセージングセッションの終了
対話が完了した際、/messaging/sessions/{sessionId} エンドポイントに対して PATCH リクエストを送信し、セッションのステータスを `Ended` に変更することでセッションを明示的に終了させます。
この一連のフローにより、外部のカスタムアプリケーションと Salesforce Service Cloud が連携し、シームレスなメッセージング体験が実現されます。
サンプルコード
ここでは、cURL を用いて Messaging for In-App and Web REST API を呼び出す具体的な例を示します。これらの例を実行する前に、有効なアクセストークン（`YOUR_ACCESS_TOKEN`）、インスタンス URL（`YOUR_INSTANCE_URL`）、および設定済みのチャネル情報が必要です。
1. メッセージングセッションの開始
エンドユーザーがチャットを開始する際に、新しいセッションを作成します。
curl -X POST 'https://YOUR_INSTANCE_URL/services/data/v58.0/messaging/sessions' \
-H 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
-H 'Content-Type: application/json' \
-d '{
"messagingPlatformKey": "YOUR_MESSAGING_PLATFORM_KEY",
"channelDeveloperName": "YOUR_CHANNEL_DEVELOPER_NAME",
"sessionKey": "UNIQUE_SESSION_IDENTIFIER_FROM_YOUR_APP",
"endUser": {
"contact": {
"FirstName": "Taro",
"LastName": "Yamada",
"Email": "taro.yamada@example.com"
}
},
"channelVariables": [
{
"name": "PreChat_OperatingSystem",
"value": "iOS 16.5"
},
{
"name": "PreChat_AppVersion",
"value": "2.3.1"
}
]
}'
詳細な注釈：
messagingPlatformKey: Salesforce のメッセージングチャネル設定で取得したプラットフォームキー。channelDeveloperName: 同じくチャネル設定で定義した一意の開発者名。sessionKey: 外部アプリケーション側で生成する一意のセッション識別子。冪等性の確保に役立ちます。endUser: エンドユーザーの情報。ここでは既存の Contact (取引先責任者) との紐付けを試みています。新しいユーザーを作成することも可能です。channelVariables: オプションの変数。OS バージョンやアプリバージョンといったコンテキスト情報を Salesforce に渡し、ルーティングやエージェントへの情報提供に活用できます。
2. エンドユーザーからのメッセージ送信
セッション開始後に取得した conversationId を使って、ユーザーのメッセージを Salesforce に送信します。
curl -X POST 'https://YOUR_INSTANCE_URL/services/data/v58.0/messaging/conversations/YOUR_CONVERSATION_ID/messages' \
-H 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
-H 'Content-Type: application/json' \
-d '{
"message": {
"text": "こんにちは。製品の在庫について教えてください。"
},
"sender": {
"type": "EndUser"
}
}'
詳細な注釈：
YOUR_CONVERSATION_ID: セッション開始 API のレスポンスで返された会話 ID。message: 送信するメッセージの内容。ここではプレーンテキストを送信しています。画像などのリッチコンテンツもサポートされています。sender.type: 送信者が `EndUser`（エンドユーザー）であることを明示します。
3. メッセージングセッションの終了
対話が完了したら、セッションを終了します。
curl -X PATCH 'https://YOUR_INSTANCE_URL/services/data/v58.0/messaging/sessions/YOUR_SESSION_ID' \
-H 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
-H 'Content-Type: application/json' \
-d '{
"status": "Ended"
}'
詳細な注釈：
YOUR_SESSION_ID: セッション開始 API のレスポンスで返されたセッション ID。status: セッションのステータスを `Ended` に更新します。これにより、エージェント側でもセッションが終了したことが通知されます。
注意事項
Digital Engagement API を利用した統合を実装する際には、いくつかの重要な点に注意する必要があります。
権限 (Permissions)
API を呼び出すユーザーには、適切な権限が必要です。通常、インテグレーション専用のユーザーを作成し、以下の権限を付与します。
- API Enabled (API 有効) ユーザー権限。
- Messaging User (メッセージングユーザー) 権限セットライセンスと、それに対応する権限セット。
- 接続アプリケーションで定義されたプロファイルまたは権限セットへのアクセス権。
- MessagingSession, MessagingEndUser, ConversationEntry といった関連オブジェクトに対する参照、作成、編集権限。
権限が不足している場合、API は 403 Forbidden エラーを返す可能性があります。
API 制限 (API Limits)
Messaging for In-App and Web REST API の呼び出しは、組織の合計 API リクエスト制限にカウントされます。これは、24時間あたりのコール数に基づいています。大規模な統合を設計する際には、この制限を考慮に入れる必要があります。
- 大量のメッセージが予想される場合は、API コール数を最適化する設計（例えば、複数の短いメッセージをまとめて送信するなど）を検討します。ただし、リアルタイム性を損なわないように注意が必要です。
- Salesforce の「組織の制限」ページで現在の API 使用状況を常に監視し、上限に達しないように計画を立てることが重要です。
エラー処理 (Error Handling)
API 統合では、堅牢なエラー処理が不可欠です。API は標準的な HTTP ステータスコードを返します。
- 400 Bad Request: リクエストボディの形式が正しくない、必須項目が欠けているなどの場合に返されます。レスポンスボディに含まれる詳細なエラーメッセージを解析し、原因を特定する必要があります。
- 401 Unauthorized: アクセストークンが無効または期限切れの場合に返されます。トークンを再取得するロジックを実装する必要があります。
- 404 Not Found: 指定されたセッション ID や会話 ID が存在しない場合に返されます。
- 500 Internal Server Error: Salesforce 側で予期せぬエラーが発生した場合に返されます。リトライロジック（Exponential Backoff など）を実装することが推奨されます。
すべての API コールにおいて、レスポンスのステータスコードを確認し、エラー発生時には詳細をログに記録して、迅速なトラブルシューティングができるように設計してください。
まとめとベストプラクティス
本記事では、Salesforce Integration Engineer の視点から、Digital Engagement の Messaging for In-App and Web REST API を活用して、カスタムアプリケーションと Salesforce Service Cloud を連携させる方法について解説しました。この API を利用することで、企業は自社ブランドに沿った独自の顧客体験を構築しつつ、Salesforce の強力なサービス基盤を最大限に活用することができます。
成功する統合プロジェクトのためには、以下のベストプラクティスを遵守することが重要です。
1. 認証情報の安全な管理:
Connected App のコンシューマシークレットや、サーバー間連携で使用する秘密鍵などを、外部システムのコードにハードコーディングせず、Key Vault や環境変数などの安全な場所に保管してください。
2. 適切な OAuth フローの選択:
サーバーサイドで完結するシステム間連携の場合は、ユーザーの操作を介さない OAuth 2.0 JWT Bearer Flow が最適です。これにより、安全かつ自動化された認証プロセスを構築できます。
3. 冪等性の確保:
ネットワークの問題などで API リクエストがタイムアウトした場合、クライアントはリクエストが成功したかどうか判断できません。セッション作成時に一意の sessionKey を含めるなど、リトライによって重複したセッションが作成されないように設計することが重要です。
4. Webhook の高可用性設計:
Salesforce からエージェントのメッセージを受け取る Webhook エンドポイントは、常に利用可能である必要があります。サーバーレスアーキテクチャ（AWS Lambda, Azure Functions など）を利用して、スケーラビリティと可用性を確保することを検討してください。また、Webhook が一時的にダウンした場合に備え、メッセージをキューイングする仕組みも有効です。
5. 詳細なロギング:
API のリクエストとレスポンス、特にエラー発生時の詳細はすべてログに記録してください。これにより、問題発生時の原因特定が迅速に行えます。
Salesforce Digital Engagement の API は、単なるチャットツール連携以上の可能性を秘めています。コンテキスト情報を活用した高度なルーティング、ボットとの連携、そして CRM データと連動したパーソナライズされた対話など、その応用範囲は多岐にわたります。私たち統合エンジニアは、これらの技術を深く理解し、ビジネス要件と結びつけることで、真に価値のある顧客体験を創造する役割を担っています。
コメント
コメントを投稿