アプリの開発
各アプリには独自のアーキテクチャと必要なコンポーネントがありますが、アプリ開発の全体的なプロセスは同じです。
- アプリシェルを作成する
- アプリのコア機能を開発する
- 設定ページと設定DBを作成して接続し、ミドルウェア/コンテクストカードに接続する(オプション)
- マニフェストを更新してアプリを Infobip に接続する
- アプリをテストするを参照してください。
- マーケットプレイスへのリスト(オプション)
アプリ シェルを作成するCreate the app shell
アプリの作成を開始するには、Infobip がアプリの機能を使用するために必要な情報を含むアプリ シェルを作成する必要があります。これにより、OAuthプロセスで使用できるアプリのクライアントIDとクライアントシークレットも作成されます。
アプリシェルが最初に作成されたときは、自分のアカウントで使用できますが、他のユーザーは使用できません。これは、プライベート アクセスと呼ばれます。アプリを他のアカウントで使用できるようにするには、「Exchange マーケットプレースにアプリを掲載する」(./list-your-app) のセクションを参照してください。
アプリシェルを作成するには:
-
Infobipアカウントにログインし、 Exchange (opens in a new tab)に移動します。
-
[公開] をクリックします。 [発行] オプションが表示されない場合は、 Infobip サポート (opens in a new tab) チームに連絡してアクセスを要求してください。
-
[アプリの作成] をクリックします。
-
アプリ名にアプリの名前を入力します 任意の名前を選択できますが、パブリック Exchange マーケットプレースにアプリを一覧表示する場合は、一意の名前を選択する必要があります。
-
[対象製品] ドロップダウン リストから、アプリで使用する製品を選択します。関連するすべての製品を選択することができます。
積 備考 Conversations アプリがコンテクストカードの場合、アプリは Conversations でサポートされているチャネルとネイティブに連携するため、チャネルを選択する必要はありません。 答え アプリがチャットボットブロックの場合、アプリはAnswersでサポートされているチャネルとネイティブに連携するため、チャネルを選択する必要はありません。 Moments フロー アプリが Moments フロー エレメント の場合、アプリは Moments でサポートされているチャネルとネイティブに連携するため、チャネルを選択する必要はありません。 People アプリがPeople APIを介してデータを同期する場合、アプリはPeopleでサポートされているチャネルで動作するため、チャネルを選択する必要はありません。 チャンネル APIを使用してチャネルを製品に統合した場合は、関連するチャネルを選択します。 次に、埋め込まれたテキスト エディターが表示され、値を編集してマニフェストを作成できます。[対象製品] ドロップダウン リストから複数の製品を選択した場合は、統合ポイント マニフェストごとに個別のタブが表示されます。マニフェストの定義に YAML と JSON のどちらを使用するかを選択します。
-
埋め込みテキスト エディターでマニフェストの例を編集して、アプリを Infobip に接続する方法を定義します。この段階では、既定値またはダミー値を使用してアプリを作成できますが、関連情報を入手したら、必ずマニフェストを更新してください。 マニフェストを正しく構成するには、マニフェストの更新 を参照してください。
-
次の URL を指定します。 設定 URL: アプリの設定と構成の場所。これは、ユーザーが設定を保存し、アプリを構成できる Web ページです。このフィールドはオプションです。 認証後にリダイレクトするためのリダイレクト URL。OAuth を使用してアプリを Infobip に接続する場合、これは認証後にアプリにリダイレクトされる URL です。
-
**[ロゴ URL] フィールドで、ロゴの画像に URL を追加します。ロゴ ファイルは SVG 形式 (.svg) で、サイズは 40 x 40 ピクセルである必要があります。
-
Infobip OAuth を使用する場合、またはアプリの機能の一部として Infobip API を使用する場合は、統合で使用する API スコープ を選択します。ベストプラクティスとして、統合に必要なスコープのみを選択します。
-
[アプリの作成] をクリックしてアプリの設定を保存し、Infobip に接続するためのアプリの資格情報を生成します。
アプリが作成され、[Exchange の発行] ページに一覧表示されます。
アプリの詳細には、名前と プライベート ラベルが表示され、自分のアカウントでのみ使用できることを示します。
また、このアプリに関連する Infobip 製品も表示されます。
3ドットメニューには、いくつかのオプションがあります。
| オプション | Description (説明) |
| 編集について | 公開ステージで入力した設定を変更します。また、クライアントID、クライアントシークレット、署名シークレットを表示することもできます。 |
| 構成 | アプリの設定と構成の設定 URL ページを開きます。 |
| ビュー ID | クライアント ID とクライアント シークレット、承認で使用される OAuth 資格情報を表示します。 |
| 削除 | Exchange からアプリを削除します。 |
アプリを作成すると、そのアプリは自分のアカウントでのみ有効になります。アプリにコンテクストカードが含まれている場合、そのカードはアカウント内のすべてのエージェントが使用できます。アプリにAnswers チャットボットブロックが含まれている場合、そのブロックはチャットボットビルダーキャンバスで使用できます。
アプリで OAuth 2.0 フローを使用する場合は、クライアント ID とクライアント シークレットを保存する必要があります。Answers で実行署名を検証するには、署名シークレットを保存する必要があります。
アプリのコア機能を開発する
このステップでは、アプリのコア機能を作成します。アプリのニーズに応じて、iframe、API、またはミドルウェアを介して埋め込まれたWebサイトを介してUIエクスペリエンスを作成し、AnswersからAPIエンドポイントへの呼び出しを解釈できます。
Conversations
Conversations では、次のコア機能を開発できます。
- コンテキスト カード UI: 標準サイズと XL サイズ
- フルページUI
コンテキスト カード UI
Conversations コンテキスト カードを使用すると、エンド カスタマーをサポートするときに、ワークスペース内のコンタクト センター エージェントにカスタム情報を表示できます。コンテクストカード UI は、iframe を使用してエージェント エクスペリエンスに埋め込むことができる Web ページまたは Web サイトである必要があります。
コンテキスト カードには、標準と XL の 2 つのサイズがあります。
標準サイズのコンテキスト カード
標準サイズのコンテキスト カードは、[マイ ワーク] のエージェントのワークスペースの右側のパネルに読み込まれます。既定では、標準サイズのコンテキスト カードは展開されません。エージェントは、コンテクストカードのタイトルをクリックして展開することで、コンテクストカードを開くことができます。
コンテクストカードで最適に表示されるようにするには、アプリのコンテンツを最大サイズ 425 x 500 で設計します。
XL サイズのコンテキスト カード
XL サイズのコンテキスト カードは、[マイ ワーク] のエージェントのワークスペースの別のパネルに読み込まれます。デフォルトでは、XL コンテキスト・カードは会話がロードされるときに展開されます。エージェントには、複数のXLカードが取り付けられていても、1つのXLカードしか表示されません。すべての Infobip アカウントが XL カードをサポートするように構成されているわけではないため、このセットアップを使用する予定がある場合は、お問い合わせください。
XL カードで使用できる領域は、使用可能な画面によって異なるため、レスポンシブ UI が最適に表示されます。ユーザーの画面幅が 750px 未満の場合、XL カードは表示されません。
コンテクストカードの UI と機能の作成
コンテクストカードの UI は、好きなように作成できます。Infobip には、ユーザーのエクスペリエンスを調整するのに役立つ情報がいくつかあります。
ページの読み込み時に、Conversations は UI を読み込み、Conversations ID をクエリ パラメーターとしてリファラー ヘッダーに含めます。
conversations:manage スコープを選択した場合は、Conversations ID と OAuth を使用して、 Conversations API API (opens in a new tab) を使用して会話に関する詳細情報を取得できます。顧客に代わって Infobip API を使用するには、OAuth 2.0 フロー を完了する必要があります。
ヘッダーの内容の例:
{
"user-agent": "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/114.0.0.0 Safari/537.36",
"accept": "text/html,application/xhtml+xml,application/xml;q=0.9,image/avif,image/webp,image/apng,*/*;q=0.8,application/signed-exchange;v=b3;q=0.7",
"accept-encoding": "gzip, deflate, br",
"accept-language": "en-US,en;q=0.9",
"referer": "https://portal.infobip.com/conversations/my-work?conversationId=1f073950-5c7f-417e-990d-ae0efd8af797",
"sec-ch-ua": "\"Not.A/Brand\";v=\"8\", \"Chromium\";v=\"114\", \"Google Chrome\";v=\"114\"",
"sec-ch-ua-mobile": "?0",
"sec-ch-ua-platform": "\"Windows\"",
"sec-fetch-dest": "iframe",
"sec-fetch-mode": "navigate",
"sec-fetch-site": "cross-site",
"sec-fetch-user": "?1",
"upgrade-insecure-requests": "1",
"x-forwarded-for": "89.164.98.239",
"x-forwarded-host": "appendpoint.free.beeceptor.com",
"x-forwarded-proto": "https"
}
次の表は、コンテキスト カードで一般的に使用される機能を示しています。
| アクション | 源 | 必要なスコープ |
|---|---|---|
| 顧客のアカウント キーを取得する | OAuth 2.0 (英語) | 何一つ |
| ユーザーのメールを取得する | OAuth 2.0 (英語) | 何一つ |
| ユーザーの優先言語を取得する | OAuth 2.0 (英語) | 何一つ |
| API 呼び出しで使用する Infobip トークンを取得する | OAuth 2.0 (英語) | 何一つ |
| 顧客のチャネルを取得する | Conversations API: メッセージの取得 (opens in a new tab) | カンバセーション:管理[かんり:かんり |
| 顧客の電話番号またはメールアドレスを取得する | Conversations API: メッセージの取得 (opens in a new tab) | カンバセーション:管理[かんり:かんり |
| 会話メッセージを取得する | Conversations API: メッセージの取得 (opens in a new tab) | カンバセーション:管理[かんり:かんり |
| 会話でメッセージを送信する | Conversations API: メッセージの作成 (opens in a new tab) | カンバセーション:管理[かんり:かんり |
| メモを作成 | Conversations API: ノートを作成 (opens in a new tab) | カンバセーション:管理[かんり:かんり |
| 顧客情報の取得 | People API: 人を得る (opens in a new tab) | 人:読み取り[ひと:よみが] |
| 顧客情報の更新 | People API: Person の更新 (opens in a new tab) | 人:管理[人:かんり] |
| 新しい顧客を作成する | People API: 人を作成 (opens in a new tab) | 人:管理[人:かんり] |
| 顧客へのイベントの作成 | People API: イベントの作成 (opens in a new tab) | 人:管理[人:かんり] 人:使用[人:しよう] |
フルページUI
Conversations フルページアプリを使用すると、コンタクトセンターのエージェントとスーパーバイザーにカスタム情報を Conversations 内の別の領域に表示できます。ページ全体の UI は、iframe を使用して埋め込むことができる Web ページまたは Web サイトである必要があります。このアプリのコンテンツのサイズに制限はありませんが、モバイルを含むさまざまな画面サイズで正しく表示されるように、レスポンシブな方法で UI を作成することをお勧めします。
ページ全体のUIは、好きなように作成できます。Infobip から UI で利用できる情報には、ユーザーのエクスペリエンスを調整するのに役立つものがあります。
ページの読み込み時に、Conversations によって UI が読み込まれます。このエクスペリエンスは特定の会話に関連付けられていないため、参照元には Conversations ID が含まれません。顧客のアカウントに関する情報を取得し、顧客に代わって Infobip API を使用するには、OAuth 2.0 フロー を完了する必要があります。
次の表は、フルページ アプリで一般的に使用される機能を示しています。
| アクション | 源 | 必要なスコープ |
|---|---|---|
| 顧客のアカウント キーを取得する | OAuth 2.0 (英語) | 何一つ |
| ユーザーのメールを取得する | OAuth 2.0 (英語) | 何一つ |
| ユーザーの優先言語を取得する | OAuth 2.0 (英語) | 何一つ |
| API 呼び出しで使用する Infobip トークンを取得する | OAuth 2.0 (英語) | 何一つ |
| エージェントを取得する | Conversations API: エージェントの取得 (opens in a new tab) | カンバセーション:管理[かんざいんしょん:manag] |
| キューの取得 | Conversations API: get Queues (キューの取得) (opens in a new tab) | カンバセーション:管理[かんり:かんり |
| 営業時間の更新 | Conversations API: 勤務時間の更新 (opens in a new tab) | カンバセーション:管理[かんり:かんり |
| 会話のルーティング情報を取得する | Conversations API: ルーティングの取得 (opens in a new tab) | カンバセーション:管理[かんり:かんり |
| 顧客情報の取得 | People API: 人を得る (opens in a new tab) | カンバセーション:管理[かんり:かんり |
| タグのリストを取得する | People API: タグを取得する (opens in a new tab) | 人:読み取り[ひと:よみが] |
| ユーザーのバッチにタグを追加する | People API: タグを追加する (opens in a new tab) | 人:管理[人:かんり] |
| カスタム属性のリストを取得する | People API: タグを取得する (opens in a new tab) | 人:読み取り[ひと:よみが] |
| カスタム属性の作成 | People API: タグを追加 (opens in a new tab) | 人:管理[人:かんり] |
答え
Answersでは、次のコア機能を開発できます。
- Answers への API 接続
- API への変数の受け渡し
- デザイナー体験
- アカウントレベルの変数
- 配列と複雑なデータリスト
- Webhook (英語)
Answers に接続するための API のセットアップ
Answers は API 呼び出しを介してアプリに接続します。API を直接呼び出すことも、ミドルウェアを介して呼び出すこともできます。直接接続はアプリをすばやく作成する方法ですが、いくつかの制限があります。API のニーズとユーザーに提供するエクスペリエンスに応じて、Answers からの呼び出しを API に必要な呼び出し形式に変換するためのミドルウェアを開発する必要があるか、開発したい場合があります。APIの準備ができたら、マニフェストの更新 を使用してAnswers APIに接続します。
API への変数の受け渡し
Answers は、クエリ パラメーターとパス パラメーターの 2 つの方法でチャットボット変数を API に送信できます。ヘッダー パラメーターは現在サポートされていません。API でヘッダーを使用して変数を送信する必要がある場合は、ミドルウェア API を使用して、Answers からの呼び出しを API の正しい形式に変換する必要があります。
注:チャットボット属性のデータセットは安全に保存されないため、プラットフォームの資格情報やトークンなどの情報にはこのオプションをお勧めしません。
Answers Designer エクスペリエンス
API 呼び出しで変数を設定および受信する場合、Answers は Answers デザイナーによってチャットボット 属性 で設定された値を使用します。Answers Designer が特定の変数を属性として取り込む方法を認識していない可能性が高い場合は、統合マネージャーに「構成」ページで変数を定義してもらい、ミドルウェアを使用してチャットボットで設定された属性と構成ページで設定した変数を組み合わせることをお勧めします。
アカウントレベルの変数
一部の変数が特定のアカウント (アカウントの資格情報など) で常に同じ場合は、統合マネージャーに [構成] ページで変数を定義してもらい、ミドルウェアを使用して、チャットボットで設定された属性と構成ページで設定された変数を組み合わせることをお勧めします。
配列と複合データ型
配列は Answers にリストとして格納されます。現時点では、API からの可変長配列応答をリストに直接マップする方法はありません。配列をJSONまたはText属性に戻し、Answers Designerにコードブロックを使用してリストへの応答を解析するように要求することをお勧めします。
Webhook の処理
チャットボットがアプリの状態の変化を待つ必要がある場合は、API またはミドルウェアでこれを管理する必要があります。Answers デザイナーは、チャットボット設定の一部としてチャットボットインスタンスの Webhook を作成できます。Answers デザイナーがコードブロックを使用して属性に sessionId を割り当てると、そのセッション ID を API に送信できます。その後、アプリは https://api.infobip.com/bots/webhook/\{\{sessionId\}\} で Webhook を呼び出すことでチャットボットを続行できます。
Moments - フロー
Moments - フローでは、次のコア機能を開発できます。
- フローへの API 接続
- API への変数の受け渡し
フロー に接続するための API のセットアップ
フロー は API 呼び出しを介してアプリに接続します。API を直接呼び出すことも、ミドルウェアを介して呼び出すこともできます。
直接接続はアプリをすばやく作成する方法ですが、いくつかの制限があります。
API のニーズとユーザーに提供するエクスペリエンスに応じて、フロー からの呼び出しを API に必要な呼び出し形式に変換するためのミドルウェアを開発する必要があるか、開発する必要がある場合があります。API の準備ができたら、マニフェストの更新 して フロー を API に接続します。
フロー 変数と People 属性を API に渡す
変数は、次の方法で API に送信できます。
- パスとクエリ - URL パラメーターとも呼ばれます
- 体
- ヘッダー - フローでのみサポート
認証トークンの処理
API に認証トークンが必要な場合、特に有効期限が切れている場合は、API またはミドルウェア内でトークンのライフサイクルを管理する必要があります。
設定ページと設定DBの作成
このオプションの手順では、構成ページの UI と、必要なサポート データベースと API 接続を設定します。APIにアカウント レベルの情報が必要な場合、ミドルウェアで使用される追加の設定がある場合、またはアプリを使用するように設定するユーザーがより多くの情報を利用できるようにする場合は、最適なユーザーエクスペリエンスを得るために構成ページを使用することをお勧めします。また、設定ページはオンボーディング プロセスを支援するためにも使用でき、ユーザーがアプリを最大限に活用するために必要なテンプレートや追加のドキュメントにアクセスできます。統合マネージャーによって定義された設定を設定データベースに保存し、ミドルウェアを使用して適切な呼び出しを API エンドポイント呼び出しに挿入できます。
構成ページの UI
構成ページを使用すると、統合マネージャーは、アプリのあらゆる使用に適用できる設定を定義できます。 統合マネージャーは、Exchange の [マイ アプリ] セクションからこのページにアクセスできます。構成ページの UI は、iframe を使用して埋め込むことができる Web ページまたは Web サイトである必要があります。このページのコンテンツのサイズに制限はありませんが、モバイルを含むさまざまな画面サイズで正しく表示されるように、レスポンシブな方法で UI を作成することをお勧めします。このページは、アプリ シェルで 設定 URL フィールドに入力することで定義されます。
構成ページの UI は、好きなように作成できます。Infobip から UI で利用できる情報には、ユーザーのエクスペリエンスを調整するのに役立つものがあります。
ページの読み込み時に、Exchange によって UI が読み込まれます。顧客のアカウントに関する情報を取得し、顧客に代わって Infobip API を使用するには、OAuth 2.0 フロー を完了する必要があります。設定ページで一般的に使用される機能には、次のようなものがあります。
| Action | Source |
|---|---|
| 顧客のアカウント キーを取得する | OAuth 2.0 (英語) |
| ユーザーのメールを取得する | OAuth 2.0 (英語) |
| ユーザーの優先言語を取得する | OAuth 2.0 (英語) |
| API 呼び出しで使用する Infobip トークンを取得する | OAuth 2.0 (英語) |
Infobip の API のスコープが アプリ シェル で定義されている場合は、Infobip の API を使用して追加情報にアクセスできます。アプリの公開時に [設定] URL でページの場所を指定するか、アプリの [編集] オプションを選択してこの場所を変更できます。
アプリの設定ページの URL を入力すると、アプリの 3 ドット メニューにも [構成] オプションが表示されます。
アプリの設定を表示できるように設定ページを開くには、 [構成] を選択します。
マニフェストを更新する
マニフェストは、アプリと Infobip の間のインターフェイスです。マニフェストには、Infobip がアプリを表示して使用するために必要なすべての情報が含まれています。
マニフェストは、JSON 形式または YAML 形式のいずれかにすることができます。マニフェストの完全な構造は、Conversations、Answers、Moments のいずれのアプリを構築しているかによって異なります。
Conversations
Conversations マニフェストには、アプリがサポートする各エントリーポイントのディクショナリが含まれています。現在、各アプリは 1 つのコンテクストカードとフルページ アプリをサポートできます。
Conversations マニフェストには、コンテクストカード用の次のキーと値のペアが含まれています。
| カードキー | カード値の説明 |
| カード | コンテクストカードの統合ポイントタイプ。 |
| タイトル | ユーザーに表示されるアプリの名前。これは必須フィールドです。既定の例は My App Name です。 |
| src (ソース) | Conversations の iframe に挿入されるページの URL。HTTPSリンクを強くお勧めします。これは必須フィールドです。デフォルトの例は https://awesome.app.com/context-card です。 |
| 大きさ | Conversations の右側のパネルに表示されるコンテクストカードのサイズ。デフォルトは標準です。 標準: コンテクストカードは他のカードと一緒に表示されます。 XL: コンテクストカードは単独で表示され、画面の高さ全体に広がります。 |
Conversations マニフェストには、フル ページ アプリ用の次のキーと値のペアが含まれています。
| ページキー | ページ値の説明 |
| ページ | フルページの統合ポイントタイプ。 |
| タイトル | ユーザーに表示されるアプリの名前。これは必須フィールドです。既定の例は My App Name です。 |
| src (ソース) | Conversations の iframe に挿入されるページの URL。HTTPSリンクを強くお勧めします。これは必須フィールドです。既定の例は https://awesome.app.com/context-card です。 |
| パス | 統合が提示されるパス。パスは「/」で始まる必要があります。たとえば、/my-app です。 |
これは、Conversations の YAML マニフェストの例です。
card:
title: My App Name
src: https://awesome.app.com/context-card
これは、Conversations の JSON マニフェストの例です。
{
"page": {
"title": "My full-page app",
"src": "https://awesome.app.com/fullpage-source",
"path": "/documents/my-app"
}
}
これは、両方のエントリポイントを使用した Conversations の YAML マニフェストの例です。
card:
title: My Super Context Card
src: https://awesome.app.com/context-card
page:
title: My Super Full-Page App
src: https://awesome.app.com/fullpage
答え
Answers のマニフェストを作成するときに、次のいずれかのレイアウトタイプを選択できます。
- 詳細レイアウト: 入力フィールドと出力フィールドを含む、API 呼び出しで使用される関数の完全な構造を定義します
- 簡略化されたレイアウト: 完全な関数の詳細を返すマニフェストでのエンドポイントの指定
各マニフェストのレイアウトの概要を以下に示します。
Answers マニフェストには、次のキーと値のペアの一部またはすべてが含まれる場合があります。
| 鍵 | 値の説明 |
| 関数 | このディクショナリで使用可能なすべての関数のリストを定義します。 |
| 名前 | 関数の名前 (デフォルトは My Order App)。この値はチャットボットエディターに表示されます。各アプリは複数の機能を持つことができます。 |
| 方式 | 関数を呼び出す方法を定義します。使用できるメソッドは、GET、POST、DELETE、POST、および PATCH です。 |
| 形容 | このフィールドを使用して、関数の動作を記述します。たとえば、この関数は注文 ID で注文の詳細を取得します。この説明は、チャットボットエディターに表示されます。 |
| URI (英語) | これは、チャットボットが関数を実行するために呼び出すエンドポイントです。たとえば、https://my-shopping-app.com/app/8/invoke/getOrderDetails です。 |
| inSchema (英語) | 関数要求への入力となる変数 (変数の型、顧客が判読できる説明、変数名、変数が必要かどうかなど) を定義します。type: 型 (例: object)。required: 必須のプロパティを一覧表示します。これらは、properties フィールドに記述するプロパティです。properties: エンドポイント呼び出しに渡すことができる各プロパティのリスト。複数のプロパティを定義できます。property_name: エンドポイント要求で使用される入力プロパティの名前 (order_id などのプロパティ名など)。 type: プロパティの型。指定できる値は、string、number です。title: 入力プロパティの UI わかりやすい名前。このプロパティのタイトルは、チャットボットエディターに表示されます。example: プロパティの値の例を提供します。これは、この情報がどのように表示されるかをユーザーに示すために使用されます。 |
| outSchema (英語) | 関数応答から出力される変数 (変数の型、顧客が判読できる説明、変数名など) を定義します。type: 型 (例: object)。required: 必須のプロパティを一覧表示します。これらは、properties フィールドに記述するプロパティです。properties: エンドポイントの応答で返される可能性のある各プロパティのリスト。複数のプロパティを定義できます。property_name: エンドポイント要求で使用される出力プロパティの名前。 type: プロパティの型 (整数や文字列など)。title: 入力プロパティの UI わかりやすい名前。このプロパティのタイトルは、チャットボットエディターに表示されます。default: プロパティのデフォルト値。整数型の場合、既定値は 0 です。文字列型の場合、既定値は '' です。example: プロパティの値の例を提供します。これは、この情報がどのように表示されるかをユーザーに示すために使用されます。pattern: 想定されるスキーマ パターン。既定値は ^(.*)$ です |
マニフェストに変更を加える
ユーザーが統合を実装した後にマニフェストを更新する場合は注意してください。オプションの変数を inSchema と outSchema に追加しても影響は最小限に抑えられますが、必須の変数を inSchema に追加すると、本番環境でユーザーが機能しなくなる可能性があります。リストされているアプリのマニフェストに大幅な変更を加える必要がある場合は、contact Infobipを使用して、新しいバージョンのマニフェストに顧客を移行できるようにしてください。
クエリ パラメーターとパス パラメーター
Answers マニフェストでは、サポートするクエリ パラメーターとパス パラメーターを追加できます。これは、チャットボット属性を関数内のパラメーターとして含めることができることを意味します。関数内でチャットボット属性を使用するには、属性を中括弧 { } で囲みます。
たとえば、エンドポイントを呼び出す関数があるとします。
[https://my-shoping-app.com/app/8/invoke/getOrderDetails
チャットボットから orderId を取得すると、マニフェストの uri 値は次のようになります。
https://my-shoping-app.com/app/8/invoke/getOrderDetails/\{orderId\}
クエリ パラメーターを使用する別の例は次のとおりです。
https://my-shoping-app.com/app/orders?limit=\{limit\}
パラメーターを inSchema プロパティとして含める必要はありません。
Answers内でチャットボットブロックを使用する場合、定義された各パラメータの値を選択できます。
マニフェストの詳細レイアウト
このレイアウトは、アプリの全体的な構造が ユーザー から ユーザー に変更されず、エンドポイントや関数スキーマが頻繁に変更されることが予想されない場合は使用します。
マニフェストを定義するには、アプリが使用する各関数、そのエンドポイント、関数が使用するすべての入力フィールドと出力フィールドを指定します。
これは、Answers の YAML 詳細マニフェストの例です。
functions:
- name: getOrderDetails
method: GET
description: Gets Order details by Order ID
uri: https://my-shoping-app.com/app/8/invoke/getOrderDetails
inSchema:
type: object
required:
- order_id
properties:
order_id:
type: number
title: Order ID
outSchema:
type: object
title: The Items Schema
required:
- id
- email
properties:
id:
type: integer
title: The Id schema
default: 0
examples:
- 450789469
email:
type: string
title: The Email Schema
default: ''
examples:
- bob.norman@hostmail.com
pattern: ^(.*)$
これは、Answers の JSON 詳細マニフェストの例です。
{
"functions": [
{
"name": "getOrderDetails",
"method": "GET",
"description": "Gets Order details by Order ID",
"uri": "https://my-shoping-app.com/app/8/invoke/getOrderDetails",
"inSchema": {
"type": "object",
"required": [
"order_id"
],
"properties": {
"order_id": {
"type": "number",
"title": "Order ID"
}
}
},
"outSchema": {
"type": "object",
"title": "The Items Schema",
"required": [
"id",
"email"
],
"properties": {
"id": {
"type": "integer",
"title": "The Id schema",
"default": 0,
"examples": [
450789469
]
},
"email": {
"type": "string",
"title": "The Email Schema",
"default": "",
"examples": [
"bob.norman@hostmail.com"
],
"pattern": "^(.*)$"
}
}
}
}
]
}
これは、getOrderDetails と getShippingDetails の 2 つの関数を持つ Answers の YAML 詳細マニフェストの例です。
functions:
- name: getOrderDetails
method: GET
description: Gets Order details by Order ID
uri: https://my-shoping-app.com/app/8/invoke/getOrderDetails
inSchema:
type: object
required:
- order_id
properties:
order_id:
type: number
title: Order ID
outSchema:
type: object
title: The Items Schema
required:
- id
- email
properties:
id:
type: integer
title: The Id schema
default: 0
examples:
- 450789469
email:
type: string
title: The Email Schema
default: ''
examples:
- bob.norman@hostmail.com
pattern: ^(.*)$
- name: getShippingDetails
method: POST
description: Get shipping details based on an input order id.
uri: https://awesome.app.com/getShippingDetails
inSchema:
type: object
required:
- orderId
properties:
orderId:
type: number
title: Order ID
outSchema:
type: object
properties:
shippingStatus:
type: string
title: Order status
trackingNumber:
type: number
title: Number of items in order
expectedDeliveryDate:
type: string
title: Expected delivery date
簡略化されたマニフェストのレイアウト
このレイアウトは、ログインしているユーザーに基づいて異なるエンドポイントを使用する予定がある場合に使用します。Answers は、このエンドポイントに対してクエリを実行して、関数とその入力と出力の一覧を取得します。
これは、YAML の簡略化されたマニフェストの例です。
uri: https://awesome.app.com/getFunctions
以下は、JSON の簡略化されたマニフェストの例です。
{"url": "https://awesome.app.com/getFunctions"
}
Moments - フロー
Moments - フローマニフェストには、フローエディタでフロー要素を定義する関数が含まれています。Moments – フローマニフェストは、エレメントを構築し、フローでのレンダリング方法を定義するパラメーターで構成されます。
Moments - フローマニフェストは、次のメインセクションで構成されています。
- 関数 - サードパーティのサービスで実行できる任意のプロシージャを定義します。
- アクション - すべてのアクションはフローのエレメントを定義し、フローの開始時に何らかの関数を実行します
- レンダリング - アクションで使用される入力フィールドのリストと、ユーザーがフローエディターで関数を表示する方法を具体的に定義します。
関数
次の表では、Exchange の既定のマニフェストの関数フィールドと例について説明します。
inSchema と outSchema はどちらも https://json-schema.org/ (opens in a new tab) 標準をサポートしています。
| 畑 | フィールドの説明 | 例 |
|---|---|---|
| 名前 | 関数の名前を関数識別子として定義します。各アプリは複数の機能を持つことができます。これは、フロー エレメントが処理されるときに実行される関数です。アクションを定義するときは、アクション名に同じ名前の対応する関数があることを確認してください。フィールド モデルが設定されているすべてのレンダリング オプションに対して、モデルと同じ名前の関数を定義する必要があります。これは、このフィールドの事前定義された値がフェッチされたときに実行される関数です。 | { "関数":[ { "name": "予約を作成", ... } ] } |
| 方式 | 関数を呼び出す方法を定義します。有効なメソッドは、GET、POST、DELETE、POST、および PATCH です。 | { "関数":[ { "name": "予約を作成", "method": "投稿", ... } ] } |
| 形容 | このフィールドを使用して、関数の動作を記述します。この説明は、フローエディターの関数定義としてユーザーに表示されます。 | { "関数":[ { "name": "予約を作成", "method": "投稿", "description": "予約を作成", ... } ] } |
| URI (英語) | これは、関数を実行するためのエンドポイント呼び出しです。このエンドポイントは、関数の実行時に Exchange によって使用されます。 | { "関数":[ { "name": "予約を作成", "method": "投稿", "description": "予約を作成", "uri": "https://restaurant-reservations-demo.azurewebsites.net/exchange/restaurant/reservations (opens in a new tab)", ... } ] } |
| 必要に応じて、サポート クエリ パラメーターとパス パラメーターを追加できます。 これにより、関数内に属性をパラメーターとして含めることができます。関数内で属性を使用するには、属性を中かっこ { } で囲みます。たとえば、endpoint:https://api.example.com/\{path1\}/v1?query1=\{query1 (opens in a new tab)} を呼び出す関数は、パラメーターを inSchema のプロパティにマップします (たとえば、クエリ パラメーター query1={query1} は、次のようにプロパティにマップされます)。 "_query1": { | ..."uri": "https://api.example.com/\{path1\}/v1?query1=\{query1 (opens in a new tab)}", "inSchema": { | |
| inSchema (英語) | 変数の型、顧客が判読できる説明、変数名、変数が必要かどうかなど、関数への入力パラメーターを定義します。inSchema には、次のパラメーターを含める必要があります。
| ... "inSchema": { "タイプ": "オブジェクト"、 "プロパティ":{ "host_name": { "タイプ": "文字列"、 "title": "ホスト名" }, "host_email": { "タイプ": "文字列"、 "title": "ホストのメールアドレス" }, "日付":{ "タイプ": "文字列"、 "title": "予約日" } }, "必須": [ "日付"、 「host_name」 ] }, |
| outSchema (英語) | 関数応答からの出力パラメーター (変数の型、顧客が判読できる説明、変数名など) を定義します。outSchema には、次のパラメーターを含める必要があります。
| ... "outSchema":{ "タイプ": "オブジェクト"、 "プロパティ":{ "id":{ "タイプ": "文字列"、 "title": "予約ID" }, "host_name": { "タイプ": "文字列"、 "title": "ホスト名" }, "host_email": { "タイプ": "文字列"、 "title": "ホストのメールアドレス" }, "日付":{ "タイプ": "文字列"、 "title": "予約日" }, "ステータス": { "パス": "ステータスコード" "タイプ": "文字列"、 "title": "予約状況" }, } |
配列型の使用例: プロパティのマップには、オプション名とオプション ID として SelectView (ドロップダウン) フィールドに使用される値を識別するために、2 つのプロパティを含める必要があります。
| ... |
アクション
次の表では、Exchange の既定のマニフェストのアクション フィールドと例について説明します。
アクションはMoments - フローマニフェストでのみ使用され、他の製品のマニフェストではサポートされていません。
| 畑 | フィールドの説明 | 例 |
|---|---|---|
| 名前 | アクションの名前を定義します。これは文字列です。すべてのアクションには、同じ名前の対応する関数が必要です。たとえば、getActionOne という関数に対応するアクションをマニフェストで定義する場合は、アクション名も getActionOne として定義する必要があります。1 つのアクションに関連する関数は多数存在できますが、アクションと同じ名前の関数が 1 つ必要です。 | {
... "actions": [ { "name": "予約を削除", ... } ] }
|
| レンダ | アクションで使用される入力フィールドのリストを定義します。これらの入力フィールドは、ユーザーがフローエディターで関数を表示する方法を定義するために使用されます。各入力フィールドには、次の項目を指定する必要があります。
| {
..."actions": [ { "name": "予約の作成", "render": [ { "field": "host_name", "viewClass": "TextFieldView", "personalization": true, "dependencies": [] } ... ] ... }, { "name": "予約の削除", "render": [ { "field": "_id", "viewClass": "SelectView", "model": "すべての予約を取得", "personalization": false, "dependencies": [] } ... ] } ] }
|
マニフェストの例
以下は、Moments フロー の JSON マニフェストの例です。このマニフェストは、架空のレストランの予約を管理するためのデモ アプリケーションとの統合を表しています。
次のリンクのデモアプリケーションに移動します: https://restaurant-reservations-demo.azurewebsites.net/ (opens in a new tab)
デモアプリケーションは Github で公開されています: https://github.com/infobip-community/restaurant-reservations-demo (opens in a new tab)
このマニフェストを使用して、Infobip アカウントのアプリとの統合がどのように機能するかをテストできます。
このアプリは、Exchange 統合の表現例として、およびマニフェスト機能を示すためにのみ使用されます。デモ アプリケーションを運用シナリオで使用したり、個人データをアプリケーションと共有したりしないでください。
{
"icon": "https://cdn-web.infobip.com/uploads/2023/01/Infobip-logo.svg",
"functions": [
{
"name": "Get all reservations",
"description": "Get all reservations",
"method": "GET",
"uri": "https://restaurant-reservations-demo.azurewebsites.net/exchange/restaurant/reservations",
"inSchema": {},
"outSchema": {
"type": "object",
"properties": {
"_id": {
"type": "array",
"items": [
{
"type": "object",
"properties": {
"id": {
"type": "string",
"title": "Reservation ID"
},
"host_name": {
"type": "string",
"title": "Host's Name"
},
"host_email": {
"type": "string",
"title": "Host's email"
},
"date": {
"type": "string",
"title": "Reservation date"
},
"hour": {
"type": "string",
"title": "Reservation time"
},
"party_size": {
"type": "number",
"title": "Number of participants"
}
}
}
],
"selectViewOptionIdPath": "$.reservations[*].id",
"selectViewOptionNamePath": "$.reservations[*].host_email"
}
}
}
},
{
"name": "Create reservation",
"description": "Creates a reservation",
"method": "POST",
"uri": "https://restaurant-reservations-demo.azurewebsites.net/exchange/restaurant/reservations",
"inSchema": {
"type": "object",
"properties": {
"host_name": {
"type": "string",
"title": "Host's Name"
},
"host_email": {
"type": "string",
"title": "Host's email"
},
"date": {
"type": "string",
"title": "Reservation date"
},
"hour": {
"type": "string",
"title": "Reservation time"
},
"party_size": {
"type": "number",
"title": "Number of participants"
}
},
"required": [
"date",
"host_name",
"host_email",
"hour",
"party_size"
]
},
"outSchema": {
"type": "object",
"properties": {
"id": {
"type": "string",
"title": "Reservation ID"
},
"host_name": {
"type": "string",
"title": "Host's Name"
},
"host_email": {
"type": "string",
"title": "Host's email"
},
"date": {
"type": "string",
"title": "Reservation date"
},
"hour": {
"type": "string",
"title": "Reservation time"
},
"party_size": {
"type": "number",
"title": "Number of participants"
}
}
}
},
{
"name": "Update reservation",
"description": "Updates a reservation",
"method": "PUT",
"uri": "https://restaurant-reservations-demo.azurewebsites.net/exchange/restaurant/reservations/{id}",
"inSchema": {
"type": "object",
"properties": {
"_id": {
"type": "string",
"title": "Reservation ID"
},
"host_name": {
"type": "string",
"title": "Host's Name"
},
"host_email": {
"type": "string",
"title": "Host's email"
},
"date": {
"type": "string",
"title": "Reservation date"
},
"hour": {
"type": "string",
"title": "Reservation time"
},
"party_size": {
"type": "number",
"title": "Number of participants"
}
},
"required": ["_id"]
},
"outSchema": {
"type": "object",
"properties": {
"id": {
"type": "string",
"title": "Reservation ID"
},
"host_email": {
"type": "string",
"title": "Host Email"
},
"host_name": {
"type": "string",
"title": "Host Name"
},
"hour": {
"type": "string",
"title": "Hour"
},
"date": {
"type": "string",
"title": "Date"
},
"party_size": {
"type": "number",
"title": "Party Size"
}
}
}
},
{
"name": "Delete reservation",
"description": "Deletes a reservation",
"method": "DELETE",
"uri": "https://restaurant-reservations-demo.azurewebsites.net/exchange/restaurant/reservations/{id}",
"inSchema": {
"type": "object",
"properties": {
"_id": {
"type": "string",
"title": "Reservation ID"
}
},
"required": ["_id"]
},
"outSchema": {}
}
],
"actions": [
{
"name": "Create reservation",
"render": [
{
"field": "host_name",
"viewClass": "TextFieldView",
"personalization": true,
"dependencies": []
},
{
"field": "host_email",
"viewClass": "TextFieldView",
"personalization": true,
"dependencies": []
},
{
"field": "date",
"viewClass": "TextFieldView",
"personalization": true,
"dependencies": []
},
{
"field": "hour",
"viewClass": "TextFieldView",
"personalization": true,
"dependencies": []
},
{
"field": "party_size",
"viewClass": "TextFieldView",
"personalization": true,
"dependencies": []
}
],
"async": false
},
{
"name": "Update reservation",
"render": [
{
"field": "_id",
"viewClass": "SelectView",
"model": "Get all reservations",
"personalization": false,
"dependencies": []
},
{
"field": "host_name",
"viewClass": "TextFieldView",
"personalization": true,
"dependencies": []
},
{
"field": "host_email",
"viewClass": "TextFieldView",
"personalization": true,
"dependencies": []
},
{
"field": "date",
"viewClass": "TextFieldView",
"personalization": true,
"dependencies": []
},
{
"field": "hour",
"viewClass": "TextFieldView",
"personalization": true,
"dependencies": []
},
{
"field": "party_size",
"viewClass": "TextFieldView",
"personalization": true,
"dependencies": []
}
],
"async": false
},
{
"name": "Delete reservation",
"render": [
{
"field": "_id",
"viewClass": "SelectView",
"model": "Get all reservations",
"personalization": false,
"dependencies": []
}
],
"async": false
}
],
"triggers": []
API 要求の例
API 要求の例を次に示します。Exchange は、この形式で提供されたデータを使用して、定義された URI を呼び出します。
この例は、"Creation reservation" https://restaurant-reservations-demo.azurewebsites.net/exchange/restaurant/reservations (opens in a new tab) 関数の生の本体を示しています。
{
"host_email": "test@test.com",
"host_name": "Test",
"hour": "11:00",
"date": "2/15/2024",
"party_size": "2"
}
API 応答の例
API 応答の例を次に示します。Exchange は、関数がマニフェスト構成に対してこの形式でデータを返すことを想定しています。
この例は、関数 "Get all reservations" https://restaurant-reservations-demo.azurewebsites.net/exchange/restaurant/reservations (opens in a new tab) の応答を示しています。
{
"reservations": [
{
"host_email": "test@test.com",
"host_name": "Test",
"hour": "15:30",
"date": "2/14/2024",
"party_size": "2",
"additionalFields": [],
"id": "fde30afb-f563-40b1-aa6c-d8106e3f278d"
},
{
"host_email": "bob@test.com",
"host_name": "Bob",
"hour": "11:00",
"date": "2/15/2024",
"party_size": "2",
"additionalFields": [],
"id": "c96734da-1f1c-4aba-8129-5c3e9848ba14"
}
]
}
モデル
関数が入力フィールドのモデルに対応する場合、その inSchema プロパティは array 以外のリストから任意の値にすることができ、outSchema プロパティは array である必要があります。outSchema では、プロパティの名前は render オプションのフィールドの名前と一致する必要があります。また、inSchema では、プロパティ名は、このフィールドが依存するレンダリング オプションのフィールド名と一致する必要があります。マニフェストの例を次に示します。
アクションでのレンダリングのフィールド定義(フィールド field3、field4、field5 は field6 と同じリストで定義されています)。
{
"field": "field6",
"viewClass": "SelectView",
"model": "ref6",
"dependencies": [
"field3",
"field4",
"field5"
],
"personalization": false
}
フィールドのモデルの関数定義:
{
"name": "ref6",
"description": "",
"method": "GET",
"uri": "some uri",
"inSchema": {
"properties": {
"field3": {
"type": "string",
"title": "field3"
},
"field4": {
"type": "string",
"title": "field4"
},
"field5": {
"type": "string",
"title": "field5"
}
}
},
"outSchema": {
"properties": {
"field6": {
"type": "array",
"title": "field6"
}
}
}
}
配列の値の形式は次のとおりです。
[
{
"id": "value1",
"name": "Value 1"
},
{
"id": "value2",
"name": "Value 2"
}
]
これは、id フィールド (処理中に使用) と name フィールド (ドロップダウン メニューに表示) を持つオブジェクトのリストです。
依存 関係
レンダリングオプションの依存関係フィールドには、いくつかのユースケースがあります。次の例は、それがどのように機能するかを示しています。
*大陸を選択し、大陸を選択すると、国を選択できる別の選択フィールドが表示され、国を選択すると、都市を選択するための3番目の選択フィールドが表示されます。
この例では、field0 は TextFieldView で、他のフィールドは SelectView です。依存関係は次のとおりです。
- field1 には依存関係がありません
- field2 は field1 に依存している
- field3 は field1 と field2 に依存します。
- field4 は field3 に依存
- field5 は field3 と field4 に依存
- field6 は field3 、 field4 および field5 に依存
フィールドが解決される順序は、field1 から field6 までの数値です。
field1 の値を選択すると、field2 は事前定義された値を取得し、ロックが解除されます。
次のフィールドの値を選択します。
field2 の値を変更すると、その値に直接依存しないが推移的に依存するすべてのフィールド(この例では field4 )が消去され、無効になります。それに直接依存するフィールドも消去されますが、新しい事前定義された値がフェッチされ、解決可能なフィールドは無効になります。この例では、field3.
マニフェストに変更を加える
ユーザーが統合を実装した後にマニフェストを更新する場合は注意してください。オプションの変数を inSchema と outSchema に追加しても影響は最小限に抑えられますが、必須の変数を inSchema に追加すると、本番環境でユーザーが機能しなくなる可能性があります。リストされているアプリのマニフェストに大幅な変更を加える必要がある場合は、contact Infobipを使用して、新しいバージョンのマニフェストに顧客を移行できるようにしてください。
テストのヒント
アプリをテストするには、まず Infobip 製品にアクセスできることと、Infobip 製品に精通していることを確認します。使用する通信チャネルによっては、送信者/numbersを構成する必要がある場合があります。
最初にシンプルなアプリを作成してから、追加の変数の管理、ページ ナビゲーション、OAuth など、より複雑なエクスペリエンスのレイヤー化を開始することをお勧めします。
一般的な問題については、「トラブルシューティング」(./トラブルシューティング)セクションを参照してください。
Answersチャットボットのテスト
Answersアプリの場合、すべての部分が正しく接続されていることを確認するために、完全なエクスペリエンスの概要を示すチャットボットを設定することをお勧めします。また、チャットボットをエクスポートして顧客に提供し、独自のチャットボットのテンプレートとして使用することもできます。
Momentsのテスト - フロー要素
Moments - フロー要素については、すべての部分が正しく接続されていることを確認するために、完全なカスタマージャーニーの概要を示すフローを設定することをお勧めします。フローをテンプレートとして保存して、再度使用することもできます。
フローエディターの使用とフローの管理について詳しくは、フローの管理を参照してください。