使用 Copilot Studio 代理時使用 Client API

$pages.agent 物件

使用 Power Pages 用戶端 API $pages.agent 物件及其 SendActivity 方法，在目前使用者可用的 Microsoft Copilot Studio 代理程式中發送訊息或呼叫事件。 回應與錯誤回撥有助於網站處理客服人員的結果。

SendActivity 方法

該SendActivity方法會在指定的 Copilot Studio 代理中發送訊息或呼叫事件，並使用回調函式處理回應與錯誤。

SendActivity 方法語法

$pages.agent.SendActivity(
    agentSchemaName: string,
    inputActivity: object,
    responseSubscriber: function,
    errorSubscriber: function
);

SendActivity 方法參數

參數名稱 類型 Description
agentSchemaName String 活動傳送到的機器人結構名稱。
inputActivity 物體 包含要傳送給機器人的文字或事件的物件。
responseSubscriber 函式 當代理發送回應時執行的回調函式。
errorSubscriber 函式 回調函式處理錯誤。

該 SendActivity 方法返回 void。 要接收代理的回應，請傳遞 responseSubscriber 回調函式。 當代理發送回應時，該方法會呼叫此回調。 傳遞 errorSubscriber 回調函式來處理錯誤。

SendActivity 回應屬性

代理收到的回應物件格式如下：

Name 類型 Description
type String 活動類型，例如訊息。
text String 可選，請由代理人發送訊息。
textFormat String 可選的訊息文字格式，如 markdown、plain 或 xml。
Id String 唯一能識別活動的 ID。
From 物體 指定活動的發送者（包含 ID、姓名（可選）及角色資訊）。
Conversation 物體 包含該活動所屬對話的識別碼。
InputHint String 可選，表示機器人是否接受、期待或忽略使用者輸入。
replyToId String 回覆訊息的識別碼。

Examples

以下範例說明如何定義回應與錯誤回撥，並用來 SendActivity 發送訊息或呼叫事件。

範例 Description
定義回應與錯誤回撥 定義responseSubscribererrorSubscriber處理代理回應與錯誤的回調函式。
發送訊息給代理人 向 Hello! 指定的代理發送文字活動，並使用回調函式處理回應或錯誤。
Invoke client event 呼叫 AgentEvent 客戶端事件並將鍵值有效載荷傳遞給代理程式。

定義回應與錯誤回撥

定義 responseSubscriber 和 errorSubscriber 回調函式來處理代理回應與錯誤。

const responseSubscriber = (response) => {
    // Replace with your response handling.
    console.log('Agent response:', response);
};

const errorSubscriber = (error) => {
    // Replace with your error handling.
    console.error('Error:', error);
};

// Replace with your agent schema name.
const agentSchemaName = 'agent SchemaName';

發送訊息給代理人

此範例會 Hello! 將文字活動傳送給指定的代理，並使用回調函式來處理回應或錯誤。

Microsoft.PowerPages.onPagesClientApiReady(async function ($pages) {
    const inputActivity = {
        text: 'Hello!' // Message to the agent.
    };

    $pages.agent.SendActivity(agentSchemaName, inputActivity, responseSubscriber, errorSubscriber);
});

Invoke client event

此範例會 AgentEvent 呼叫客戶端事件，並將鍵值有效載荷傳遞給代理程式。

Microsoft.PowerPages.onPagesClientApiReady(async function ($pages) {
    const inputActivity = {
        name: 'AgentEvent', // The name of the event to be invoked.
        value: { key1: 'value1', key2: 'value2' } // Open-ended value used to carry additional data or payloads necessary for specific agent operations or responses.
    };

    $pages.agent.SendActivity(agentSchemaName, inputActivity, responseSubscriber, errorSubscriber);
});

錯誤訊息

以下是使用者可能遇到的錯誤訊息及其可能的原因。

錯誤類型 原因 使用者錯誤訊息
代理結構驗證 提供無效的機器人結構名稱，或使用者沒有代理的存取權限 Invalid bot schema name or access denied. Check the bot schema name and try again.
取指錯誤 在擷取直線令牌時發生錯誤 Something went wrong while fetching the token. Please try again.
發佈活動錯誤（重試） 在發佈活動時發生錯誤，需重新嘗試。 Something went wrong while posting the activity: retry.
發文活動錯誤（逾時） 在等待外出訊息或 postActivity 時被超時 Timed out while posting activity: Please retry.
發文活動錯誤（活動無效） 輸入活動沒有文字或名稱來呼叫事件。 Invalid activity: At least one of text, name, or attachments must be provided.
發佈活動錯誤（找不到使用者 ID 或找不到令牌） Token 不存在於會話儲存中，使用者 ID 也不在 Token 中 Error retrieving user ID: {error message}
發佈活動錯誤（一般） 在發佈活動時發生了未說明的錯誤 Something went wrong while posting the activity: Please try again.
直線連接錯誤 在與機器人建立直線連線時發生錯誤。 Something went wrong while creating direct line connection: Please try again.
一般誤差 一個不屬於上述類別的意外錯誤 An unexpected error occurred while sending activity: Please try again.
  • 上次更新時間：