Einstein Bots Platform API のご紹介



+ [Einstein ボットの作成](https://help.salesforce.com/s/articleView?id=service.bots_service_create.htm&type=5)
+ [Get Started with Einstein Bots API](https://developer.salesforce.com/docs/service/einstein-bot-api/guide/prerequisites.html)

+ [Introducing the Einstein Bots Platform API](https://developer.salesforce.com/blogs/2022/05/introducing-the-einstein-bots-platform-api)

Einstein Bots Platform API は、任意のクライアントから Einstein Bots と対話できる新しい REST API です。このブログ投稿では、この新しい API を使用してボットと対話する方法について説明します。このシリーズの後の投稿では、特定のケースについて詳しく説明します。


# Einstein ボットとは何ですか?

ボットは、システムやユーザーと対話できる自律プログラムです。一般的な使用例としては、注文の確定、顧客サポートの提供、FAQ の表示などがあります。ボットは、エンド カスタマーにサービスを提供する際に人間による対話の必要性を最小限に抑えます。

ボットは、人工知能 (AI) によって、より賢く、より有能になります。データの力に支えられたボットは、エンドユーザーのためにより複雑なタスクを解決するのに役立ち、人間のエージェントの必要性を減らします。その結果、このような AI 搭載ボットを採用する企業は、多額の費用を節約できます。

Einstein Bots はまさに上記の機能に加え、さらに多くの機能を備えています。Einstein Bots は Salesforce の広大なクラウド エコシステムに完全に統合されているため、Salesforce が現在および将来提供するすべての優れたツールとテクノロジーのパワーを直接活用できます。Einstein Botsの ドキュメントで、その素晴らしさについて詳しく読むことができます。

# Einstein ボットを定義して使用する方法は?

このブログ投稿の背景を説明するために、まず、顧客の組織で Einstein ボットを定義して使用する方法を理解する必要があります。次の手順で概要を説明します。

ボットの構築:ボット ビルダーで Einstein ボットを定義します。この手順には、新しいボットを機能させるために必要なすべてのボット ダイアログ、要素、ルールなどの作成が含まれます。また、ここで、ボットの NLP 機能を使用するために Einstein NLP モデルを定義/トレーニングします。必要なすべての詳細は、開始ドキュメントに記載されています。手順 1 で定義したボットは、チャネルに依存しません。

![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/328136/b6a5a886-8169-443e-8fcf-07898b217f1b.png)

1. ボットをテストする:ボットの構築フェーズが完了したら、ボット プレビューで Einstein ボットをアクティブ化してテストできます。ボット プレビューは、エンド ユーザーと同じようにボットを操作できるプレイグラウンドです。

2. チャネルの追加: Einstein ボットの準備ができたら、実際の運用環境で使用できるように顧客に提供します。Salesforce は、Web、SMS、WhatsApp、Facebook などのすぐに使用できるチャネルを提供しており、Einstein ボットはこれらの Salesforce チャネル経由でのみエンドユーザーに提供されます。

次のシステム図は、Einstein ボットを構築および展開するときにさまざまなシステムがどのように相互作用するかを示しています。

![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/328136/065e8b45-b5ab-476e-8a50-a5c82f2c6139.png)

しかし、ボット管理者として、これらの Salesforce チャネル/接続を超えてボットを活用する必要がある場合はどうなるでしょうか? ここで、Einstein Bots Platform API が役立ちます。

# Einstein Bot と統合するその他の方法

前のセクションで説明したように、Einstein ボットを顧客エンゲージメント インフラストラクチャに統合する唯一の方法は、さまざまな Salesforce チャネルを使用することです。これは、以前にリリースされたバージョンの Einstein ボットの制限でした。しかし、現在、この制限を完全に取り除く新しい Einstein ボット プラットフォーム API がリリースされました。Einstein ボットは、現在のチャネルで引き続き優れた機能を発揮しますが、カスタム チャネルとクライアント実装を追加できるようになりました。

Einstein Bots Platform API とは何ですか?
Einstein Bots Platform API は、任意のクライアントから Einstein Bots とやり取りできる REST API です。これは、あらゆる顧客エンゲージメント環境で Einstein Bots を公開するための真のプラットフォーム ソリューションです。たとえば、エンドユーザー エンゲージメント クライアントが React Native モバイル アプリであるユース ケースを想像してください。Einstein Bots Platform API がなければ、このようなカスタム クライアントと Einstein Bots を統合することは不可能でした。しかし、Einstein Bots Platform API を使用すると、上記のカスタム クライアントと Einstein Bots を簡単に統合できるようになりました。詳細については、[開発者ガイド](https://developer.salesforce.com/docs/service/einstein-bot-api/overview)を参照してください。

次のシステム図は、新しい Einstein Bots Platform API を含むさまざまなコンポーネントがどのように相互作用して、Salesforce の顧客が Einstein Bots を顧客に提供できるようにするかを示しています。

![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/328136/5f4ae367-4035-4317-9701-1a035c117bc5.png)

# APIの使い方

入門的なコードサンプルから始めましょう。API を使用するには、上記の「Einstein ボットの定義と使用方法」セクションで説明した手順 1 と 2 は同じままです。ただし、手順 3 (つまり、接続/チャネルの追加) に進むと、以下に示すように API オプションを選択します。

![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/328136/da7ab6df-5462-462d-b13c-af5c3a7d742a.png)

API 接続を選択すると、以下に示すように、統合の詳細と Salesforce 接続アプリケーション名を入力するように求められます。統合名には任意の文字列を指定できます。

![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/328136/c5dee650-2af2-493d-a4c9-4b2ba194c4f2.png)

# Salesforce Connected Appsについて

Salesforce 接続アプリケーションは、Salesforce API とやり取りする外部システムを承認するために使用されるフレームワークです。Einstein Bots Platform API では、接続アプリケーションを使用して OAuth アクセス トークンが生成され、このトークンが外部リクエストに認証ヘッダーとして含められます。Einstein Bots API は、このような認証ヘッダーを受信すると、受信した OAuth アクセス トークンを検査し、リクエストが有効かどうかを判断します。詳細については、接続アプリケーションの ドキュメントを参照してください。Einstein Bots API 専用の接続アプリケーションを設定するには、Bot API 開発者ガイドの前提条件セクションを参照してください。また、このブログ投稿では、 JWT ベアラー フロー用に接続アプリケーションを設定し、Einstein Bots Platform API との通信に使用できる OAuth アクセス トークンを取得する方法について詳しく説明しています。


# コーディングの時間です!

Einstein Bot を定義し、OAuth 対応の Salesforce 接続アプリケーションを設定し、それをボットに接続すると、Einstein Bots Platform API を使用する準備が整います。次のコード スニペットは、Python Flask サーバーを使用して Einstein Bots API と通信する例を示しています。

```Python
import logging
import requests
import json
from app import app
from flask import request
from app.auth import get_oauth_access_token
from app.constants import INIT_CHAT_URI, SEND_MESSAGES_URI, END_CHAT_URI, ORG_ID_HEADER_KEY, END_SESSION_HEADER_KEY

@app.route("/start/<bot_id>", methods=["POST"])
def init(bot_id):
    request_url = get_request_url(INIT_CHAT_URI.format(bot_id))
    response = send(request.json, request_url)
    return response

@app.route("/chat/<session_id>", methods=["POST"])
def chat(session_id):
    request_url = get_request_url(SEND_MESSAGES_URI.format(session_id))
    return send(request.json, request_url)

@app.route("/end/<session_id>", methods=["DELETE"])
def end(session_id):
    request_url = get_request_url(END_CHAT_URI.format(session_id))
    headers = get_headers()
    headers[END_SESSION_HEADER_KEY] = request.headers.get(END_SESSION_HEADER_KEY)
    response = requests.delete(request_url, headers=headers)
    validate_response(response)
    return json.loads(response.text)

def send(data, url):
    headers = get_headers()
    response = requests.post(url, headers=headers, data=json.dumps(data))
    validate_response(response)
    return json.loads(response.text)

def validate_response(response):
    # check status code
    if response.status_code != 200:
        raise ValueError("Invalid response code from Bot server. Error=" + response.text)    

def get_request_url(uri):
    return app.config.get("BOTS_SERVER_URL") + uri

def get_headers():
    token = get_oauth_access_token()
    orgId = app.config.get("ORG_ID")
    return {
        "Authorization": "Bearer " + token,
        "Content-Type":"application/json",
        "Accept": "application/json",
        ORG_ID_HEADER_KEY: orgId 
    }

if __name__ == "__main__":
    app.run()
```

注: 各ルートの実装では、認証ヘッダーを明示的に追加します。このヘッダーには、関数で取得される OAuth アクセス トークンが必要です。この関数の完全な実装については、コード リポジトリget_oauth_access_tokenを参照してください。

関数init、chat、 は、end3 つの Einstein Bot API に対応しています。これらの各呼び出しのリクエストとレスポンスの構造は、API クライアント ガイドに詳しく記載されており、上記の Python Flask サーバーでも同じものを使用できます。Python Flask サーバーに行われたリクエストのサンプルを次に示します。

チャットセッションを開始します:

```bash
curl --location --request POST 'http://127.0.0.1:5000/start/<bot-id>' \
--header 'Content-Type: application/json' \
--data-raw '{
    "forceConfig": {
        "endpoint": "<ForceConfig Endpoint shown in the Add Connection Dialog>"
    },
    "externalSessionKey": "UUID"
}'
```

既存のチャット セッションでメッセージを送信します。

```bash
curl --location --request POST 'http://127.0.0.1:5000/chat/<sessionId from the response of the Initiate Chat Session request>' \
--header 'Content-Type: application/json' \
--data-raw '{
    "message": {
        "type": "text",
        "text": "Hellow",
        "sequenceId":1
    }
}'
```

チャットセッションを終了します:

```bash
curl --location --request DELETE 'http://127.0.0.1:5000/end/<sessionId from the response of the Initiate Chat Session request>' \
--header 'Content-Type: application/json' \
--header 'X-Session-End-Reason: UserRequest'
```

# 次は何ですか？

このシリーズの今後の投稿では、カスタムパラメータを使用してボットセッションを初期化する方法や、Einstein Bots Platform API を使用したボットからケースへのエスカレーションシナリオなど、具体的なケースについて詳しく説明します。