Zia開発者コンソール

処理の実行中にフックとして機能する関数には、次の3種類があります。

• 処理実行（必須） - すべてのパラメーターが入力された後、処理の最後に呼び出されます。
• パラメーターローダー（オプション） - すべての静的パラメーターが入力された後に呼び出されます。
• コンテキストハンドラー（オプション） - 処理の過程でユーザーが入力するたびに呼び出されます。

処理の実行フロー

ユーザーがZiaに文を入力するたびに、Ziaはユーザー入力を解釈して、設定された処理のいずれかと一致するかどうかを確認してください。いずれかの設定した処理と一致すると、会話としての処理の実行に必要なパラメーターの入力を求められます。すべてのユーザー入力に対して、コンテキストハンドラー関数が呼び出されます。すべての静的パラメーターが入力されると、パラメーターローダー関数は1回だけ呼び出されます。

設定したすべてのパラメーターをユーザーから受信すると、Ziaが処理実行関数を実行し、実行関数によって返されたメッセージをユーザーに返信します。

新しい処理の追加

新しい処理は、［カスタマイズ］タブから追加できます。カスタマイズは、サンドボックスと同様の環境を提供します。この環境で、新しい処理を開発してテストできます。新しい処理の追加に関連する手順について、以下で説明します。

新しい処理を追加するには

1. ［処理の追加］をクリックしてください。
2. ［処理名］を入力してください。
3. 目的の処理に基づいて、処理が質問に回答するか、操作を実行するかを選択してください。
4. 処理が質問に回答する場合は、回答を直接提供するか、CRMから作成するかを選択してください。
5. サンプル文とパラメーターを定義します。
6. ［次へ］をクリックしてください。
   
7. 必要に応じて、パラメーターローダー関数とコンテキストハンドラー関数を設定してください。
8. ［実行コードの編集］をクリックしてください。
9. 実行関数を定義します。
10. ［完了］をクリックしてください。
    目的の処理が作成され、Ziaのチャットで公開されたときにのみ使用できるようになります。

サンプル文の定義

サンプル文の定義は、処理を定義する上で重要です。Ziaに対して処理のトリガーを指示する内容となるためです。いくつかのサンプル文を見てみましょう。

• 操作を実行する処理の場合は、「この操作の呼び出し方法」セクションでサンプル文を定義する必要があります。
• 質問に回答する処理の場合は、「この質問の方法」セクションの下にサンプル文を定義する必要があります。
• サンプル文として入力したテキストは、選択してパラメーターとして設定できます。テキストを選択すると、選択したテキストに任意のパラメーターを関連付けるためのポップアップが表示されます。または、テキストに関連付ける新しいパラメーターを作成できます。

サンプル文を追加するには「+」アイコン、特定の文を削除するには「-」アイコンをクリックしてください。

また、サンプル文のテキストボックスの横にある並べ替えアイコンで文を並べ替えて、よく使用する文を一番上に表示することもできます。

ユーザーが追加する最初の3つのサンプル文は、処理を呼び出すための提案として表示されます。したがって、覚えやすい明確な文を使用することをお勧めします。

パラメーターの定義

パラメーターは、処理を完了するためにユーザーから受信する必要がある入力データです。処理に新しいパラメーターを追加するには、サンプル文のパラメーターをマークするときに表示されるパラメーターリストかパラメーター提案ダイアログから、［新規］オプションをクリックしてください。

［新規］パラメーターのポップで、次の情報を入力してください。

ユーザーはこれらすべてのデータ型に英語で値を指定でき、Ziaはリテラル文を宣言されたデータ型に変換します。

1. パラメーター名 - 有効なパラメーター名は次の点に従う必要があります。
   • 有効なパラメーター名は、小文字のアルファベットで始める必要があります。
   • アルファベット、数字、アンダースコア記号以外の文字は使用できません。
   • パラメーター名は、処理に対して一意である必要があります。
   • 次の名前は、Ziaの予約語であるため、パラメーターとして使用できません（userInput、previousParam、additionalParams、sessionData、broadcast、previousUserMsgs、cache、org、user）。
2. パラメータータイプ - パラメーターにaptデータ型を選択してください。Ziaは、次のデータ型をサポートしています。
   • テキスト - 任意の文字列
   • 数値 - 任意の有効な数値
   • 時刻 - 任意の有効な時刻
   • 日付 - 任意の有効な日付
   • 単一選択配列 - 1つのオプションを選択できる使用可能なオプションのリスト。
   • 複数選択配列 - 複数のオプションを選択できる使用可能なオプションのリスト。
3. 配列型パラメーター - 配列型パラメーターの場合は、次の追加情報を入力する必要があります。
   • 配列の値 - 1つまたは複数のオプションを選択できるオプションのリストを含めることができます。また、すべてのオプションのIDを入力するか、値のみを入力するときに自動作成IDを使用することもできます。
   • 入力方法 - 配列パラメーターがユーザーに確認を表示する方法を指定します。テキストまたはビジュアルのいずれかを使用できます。テキストが選択されている場合、ユーザーは、配列パラメーターに割り当てる任意の値を入力するか（チャットの場合）読み上げる（音声の場合）ことができます。ビジュアルモードの入力の場合、ユーザーは、ラジオボタン（単一選択の場合）またはチェックボックス（複数選択の場合）として表示される配列値から、クリックまたはタッチして入力を選択する必要があります。
     
4. 確認メッセージ - Ziaとユーザーの会話の一部として、パラメーター値の入力を取得するためにZiaからユーザーに尋ねる質問です。たとえば、予定作成処理のパラメーター「starttime」の値を取得するには、確認メッセージを「予定の開始時刻は何時ですか？」または「予定はいつからですか？」に設定する必要があります。または、コンテキストハンドラー関数を使用して、パラメーターの確認メッセージを上書きすることもできます。

パラメーターの並び替え - Ziaの会話フローは、定義されているパラメーターの順序によって異なります。処理が検出されると、Ziaは定義された順序で、すべてのパラメーターを、それぞれの確認メッセージを使用して1つずつ確認します。パラメーターを作成した後でも、任意の位置に個々のパラメーターをドラッグアンドドロップするだけで、パラメーターを並び替えることができます。

関数の定義

会話フローと処理の実行は、特定の処理に定義されている関数によって決まります。関数は処理の開発者が記述する処理で、処理の実行中に、apt呼び出しポイントでZiaによって呼び出されます。

すべての関数はDelugeで記述されています。Delugeは、Zohoクラウド環境のオンラインスクリプト言語です。Delugeの詳細なチュートリアルについては、このガイドを参照してください。

Ziaの実行中に、フックとして機能する3つの関数があります。Ziaは、apt呼び出しポイントですべての引数の正確な値を使用して関数を呼び出します。すべての定義済み関数は、指定されたデータ型の値を返す必要があります。

次のシステム定義の入力引数は、特定の関数引数に加えて、すべての関数で使用できます。

上記のシステム定義引数に加えて、処理用に定義されたすべての静的パラメーターも、すべての関数の入力引数として使用できます。すべての静的パラメーターは、それ自体がすべての関数の引数になります。

Ziaは、すべての変数のapt値を入力し、すべての関数の入力引数として渡します。

各関数には、独自の戻りデータ仕様があります。ユーザーの処理が適切に機能するための設定は開発者の責任です。

パラメーターローダー関数の定義

パラメーターローダー関数は、統計的に定義されたパラメーターに加えて、実行時に処理に新しいパラメーターを動的に追加するために使用します。これは通常、パラメーターがユーザーに基づいて異なるときに、事前に処理のパラメーターが分からない場合に便利です。パラメーターローダー関数の定義はオプションです。

たとえば、CRM内でタスクを作成する処理を記述する場合、タスクの作成フォームは、設定のレイアウト構成に基づいてユーザーごとに異なります。このような場合は、タスクの作成フォームの項目を、パラメーターローダー関数を介して動的パラメーターとしてロードするので、Ziaはこれらのパラメーターを1つずつ確認して、タスクを作成できます。

Ziaは、呼び出し文に記述されている可能性のあるパラメーターローダー関数からロードされた動的パラメーターの値を検出できません。Ziaは、パラメーターローダー関数の各パラメーターに対して宣言される確認メッセージを使用して、動的パラメーターを1つずつユーザーに確認するだけです。

呼び出しポイント

Ziaがユーザーの入力の処理を検出すると、入力に存在する可能性のある静的パラメーター値も検出されます。不足している静的パラメーターは、定義されている順序で1つずつユーザーに確認されます。すべての静的パラメーターが入力されると、Ziaは、すべての入力引数に対してapt値を指定してパラメーターローダー関数を呼び出します。

静的パラメーターが定義されていないと、Ziaが処理を検出するたびに、パラメーターローダー関数が呼び出されます。パラメーターローダー関数は、処理実行サイクル中に1回だけ呼び出されます。

入力引数

パラメーターローダー関数では、システム定義の入力引数に加えて、次の入力引数も使用できます。

戻り値

戻り値関数は、次の形式のマップを返す必要があります。

additionalParams（必須） - このキーの値はパラメーター要素のリストである必要があります。各パラメーターはマップデータ型である必要があります。パラメーターマップのオブジェクトのプロパティーを以下に示します。

1. 名前 - パラメーターの名前。
2. データ型 - パラメーターのデータ型。これには、以下のいずれかの値を使用できます。
   • text
   • number
   • date
   • time
   • boolean
   • array_checkbox
   • array_radio
3. prompt_msg - パラメーターの確認メッセージ。
4. options - リストとしての配列型パラメーターのオプション。各オプションは、キー「id」と「label」を持つマップです。
5. input_mode - 配列型パラメーターの入力モード。値はTEXTUALまたはVISUALのいずれかです。
   -必須- このようなキーがパラメーターのマップに存在する必要があります。
6. assign（オプション） - このキーの値はマップである必要があります。このキーを使用して、値を関数の変更可能な入力引数のいずれかに変更できます。すべての静的パラメーターとシステム定義の引数「cache」は変更可能です。

コンテキストハンドラー関数の定義（オプション）

コンテキストハンドラー関数は、処理の会話フローを制御するために使用されます。実行時にユーザーに対してパラメーターが確認される順序を変更できます。また、一部のパラメーターをスキップしたり、パラメーター値のカスタム検証を実行したり、実行時に処理を実行する前に確認を求めたりすることもできます。

コンテキストハンドラー関数は、静的パラメーターが定義されている順序を上書きできます。コンテキストハンドラー関数が有効になっている場合、Ziaは、パラメーターの定義中に宣言した順序ではなく、コンテキストハンドラー関数によって指示された順序でパラメーターを確認します。

呼び出しポイント

Ziaがユーザー入力の処理を検出すると、ユーザー入力に存在する可能性のある静的パラメーター値が検出されます。次に、Ziaは、最初に不足している静的パラメーターをユーザーに確認します。ユーザーがパラメーター確認に応答すると、Ziaはコンテキストハンドラー関数を呼び出します。したがって、コンテキストハンドラー関数は、会話で確認されるすべてのパラメーターで呼び出されます。これは、静的パラメーターと動的パラメーターの両方に適用可能です。処理にパラメーターがまったくない場合、コンテキストハンドラー関数は、実行関数の前に1回実行されます。

入力引数

システム定義の入力引数に加えて、コンテキストハンドラー関数では次の入力引数も使用できます。

戻り値

パラメーターローダー関数は、次の形式のマップを返す必要があります。

todo（必須） - コンテキストハンドラー関数の完了後に、Ziaに実行する内容を指示するために使用されます。このキーは、コンテキストハンドラー関数のレスポンス内に存在する必要があります。次のいずれかの値のみを使用できます。

1. prompt - ユーザーからのパラメーターを確認するようにZiaに指示します。
2. confirm - 処理の実行関数を呼び出すための最終確認を求めるようにZiaに指示します。
3. execute - 処理実行関数を呼び出すようにZiaに指示します。

prompt（“todo” = “prompt”の場合にのみ適用可能） - ユーザーに確認するパラメーターを指定するマップが含まれています。「todo」が「prompt」に設定されていても、このキーが指定されていないと、Ziaはパラメーター定義の順序に従って次のパラメーターを確認します。そのため、パラメーター定義のデフォルトの順序を使用する必要がある場合は、このキーをスキップできます。マップ値には、次のキーを含めることができます。

1. param_name * - 確認を表示するパラメーターの名前。パラメーター名は、宣言された静的パラメーターまたは動的パラメーターのいずれかである必要があります。
2. options - パラメーターへの提案として表示されるオプション。これは、配列型パラメーターにのみ適用できます。
3. msg - パラメーターのデフォルトの確認メッセージを一時的に上書きするために使用されます。

confirm（“todo” = “confirm”の場合にのみ必須） - ユーザーに確認する必要がある処理実行の確認メッセージを指定するマップが含まれています。マップ値には、次のキーのみを含めることができます。

1. message - ユーザーに確認する必要がある確認メッセージ。

assign - このキーの値はマップである必要があります。このキーを使用して、値を関数の変更可能な入力引数のいずれかに変更できます。すべての静的パラメーターとシステム定義の引数「cache」は変更可能です。

実行関数

実行関数は、処理実行のエンドポイントです。処理の実行を定義します。処理が実際に実行され、処理の完了の結果として、最終的な成功（または失敗）を示すメッセージがユーザーに送信されます。ユーザーへのレスポンスは、プレーンテキストまたはカードの集合（ビジュアル要素）です。

呼び出しポイント

実行関数は、処理のエンドポイントで呼び出されます。デフォルトでは、処理のエンドポイントは、すべてのパラメーター値が確認され、適切な値が入力された後に発生します。また、エンドポイントはコンテキストハンドラー関数（“todo” : “execute”）から定義することもできます。実行関数が呼び出されると、処理は完了し、ユーザーからの以後の会話は新しい処理と見なされます。

入力引数

システム定義の入力引数に加えて、実行関数では次の入力引数も使用できます。

戻り値

実行関数は、次の形式のマップを返す必要があります。

message（必須） - プレーンテキストメッセージをユーザーへの返信として指定します。プレーンテキストは、通信メディアに応じて音声またはテキストとしてレンダリングされます。

card（オプション） - 視覚的にフォーマットされたメッセージをユーザーへの返信として提供します。カードとは、テーブルや画像などの視覚的要素の集合です。カードは、通話メディアとチャットメディアの両方で画面に表示されます。このキーの値は、マップオブジェクトのリストです。各マップオブジェクトは、カード内のUI要素を表します。1枚のカードに、同じタイプの複数の要素を含めることができます。カード内のすべての要素が、返信メッセージ内で上から下に表示されます。

以下は、ZiaがサポートするUI要素のリストです。

処理の公開

独自の処理はサンドボックス環境で作成されており、組織の他のユーザーは使用できません。すべてのユーザーが独自の処理を使用できるようにするには、処理データをZiaに更新する必要があります。

Zoho CRM用に作成されたすべての処理を更新するには、Zoho CRMタブの下にある［更新］ボタンをクリックしてください。［更新］ボタンは、ユーザーが作成したカスタム処理のいずれかで利用可能な更新がある場合にのみ表示されます。

Ziaの権限

Zia管理者は、組織内での役割と階層レベルに基づいて、ユーザーにアクセス制御を提供できます。以下のは、各役割の権限を示します。

1. ユーザー - Ziaとチャットまたは通話のみが可能です。
2. 開発者 – Ziaにスキルを記述できます。
3. マネージャー - Ziaにスキルを更新して、すべてのユーザーが利用できるようにすることができます。
4. 管理者 - 他のユーザーを管理できます。
5. 特権管理者 - 主な管理者です。

開発者コンソールにアクセスするために必要な最低限の役割は開発者です。管理者の役割のユーザーは、他のユーザーの役割を変更する権限があります。ユーザーの役割を変更するオプションは、［設定］タブで使用できます。［設定］で、役割を変更するユーザーをクリックしてください。［役割の変更］オプションをクリックし、一覧からユーザーの新しい役割を選択して、［更新］をクリックしてください。ユーザーが新しい役割に移動します。