精通 Salesforce Service Cloud：Omni-Channel API 开发者指南

九月 17, 2025

作者：Salesforce 开发人员

背景与应用场景

作为一名 Salesforce 开发人员，我们经常面临的挑战不仅仅是实现业务逻辑，更重要的是提升用户体验和工作效率。在客服领域，Salesforce Service Cloud 提供了强大的功能集合，而其核心之一便是 Omni-Channel (全渠道) 路由引擎。Omni-Channel 能够将来自不同渠道（如电话、聊天、消息、个案）的工作项 (Work Items) 智能地推送给最合适、最空闲的客服座席 (Agent)。

虽然标准的 Omni-Channel 组件已经非常强大，但在许多复杂的业务场景下，企业需要更高程度的定制化来满足其独特的工作流程。例如：

1. 构建自定义座席控制台

企业可能希望将 Omni-Channel 的状态控制功能无缝集成到他们自定义的 Lightning Web Components (LWC) 中，而不是使用标准的 Omni-Channel 工具栏。这可以创造一个统一、品牌化的座席工作界面，将所有必要工具整合在一起，减少座席在不同组件间的切换。

2. 与第三方 CTI 系统深度集成

当集成一个外部的计算机电话集成 (Computer Telephony Integration, CTI) 系统时，我们可能需要在电话呼入时自动将座席的 Omni-Channel 状态设置为“忙碌(通话中)”，并在通话结束后自动将其恢复为“在线”。这种自动化的状态同步需要通过编程方式来控制 Omni-Channel。

3. 自动化座席工作流程

在某些场景下，我们希望根据特定事件自动改变座席状态。例如，当座席完成一个特别复杂的个案后，系统可以自动将其状态设置为“整理工作中 (Wrap-Up)”几分钟，让他们有时间记录笔记，然后再自动切换回“在线”状态接收新的工作。

为了满足这些高级定制化需求，Salesforce 提供了 Omni-Channel Toolkit API。这个基于 JavaScript 的客户端 API 允许开发人员在 Lightning Experience 的控制台应用中，通过编程方式与 Omni-Channel 进行交互，从而实现对座席状态、工作项的精细化控制。

原理说明

Omni-Channel Toolkit API 是一套功能强大的 JavaScript 方法和事件集合，专为在 Salesforce 控制台应用中运行的 Lightning 组件（包括 LWC 和 Aura 组件）而设计。它的核心工作原理是提供一个与 Salesforce 后端 Omni-Channel 引擎通信的桥梁，使得前端组件可以监听 Omni-Channel 事件并调用其功能。

作为开发人员，我们主要通过 LWC 中的 lightning/omniToolkitApi 模块来使用这个 API。这个模块暴露了一系列返回 Promise 的异步方法，使我们能够执行各种操作。

核心概念

1. 客户端 API： Omni-Channel Toolkit API 是一个纯粹的客户端 API。这意味着它只能在用户的浏览器中，在 Salesforce 控制台应用的上下文中被调用。它无法在 Apex、Visualforce 或 Salesforce 外部的系统中直接使用。

2. 事件驱动模型： 除了调用方法，API 的另一个强大之处在于监听事件。例如，我们可以监听 omniToolkitApi.subscribe() 方法来捕获座席登录、注销、接收新工作、工作被分配等关键事件，从而在我们的自定义组件中做出相应的响应。

3. 异步操作： 所有对 Omni-Channel 状态的更改（如登录、更改在线状态、接受工作）都是异步的。因此，API 中的方法都返回 Promise 对象。我们在编写代码时必须正确处理这些 Promise，使用 .then() 来处理成功的结果，使用 .catch() 来捕获和处理可能发生的错误。

关键 API 方法

以下是 lightning/omniToolkitApi 模块中一些最常用的方法：

login(servicePresenceStatusId): 使用指定的服务在线状态 ID 将座席登录到 Omni-Channel。
logout(): 将座席从 Omni-Channel 注销。
getServicePresenceStatusId(): 获取当前座席所有可用的服务在线状态的 ID 和开发者名称。这对于构建一个自定义的状态选择器至关重要。
setServicePresenceStatus(statusId, statusApiName): 更改当前登录座席的在线状态。这是实现状态自动同步的核心方法。
acceptWork(workId): 接受一个已分配给座席的工作项。
declineWork(workId, reason): 拒绝一个已分配的工作项，并可提供拒绝原因。
getWorkInfo(workId): 获取关于特定工作项的详细信息。

通过组合使用这些方法，我们就能构建出功能丰富、高度定制化的客服座席工具，极大地提升 Service Cloud 的使用体验和效率。

示例代码

下面的示例展示了如何创建一个简单的 LWC 组件，该组件可以获取当前用户所有可用的 Omni-Channel 在线状态，并允许用户通过点击按钮来更改他们的状态。这个例子完美地诠释了如何使用 lightning/omniToolkitApi。

这个示例直接来源于 Salesforce 官方开发者文档，确保了其准确性和最佳实践。

omniStatusChanger.html

<template>
    <lightning-card title="Omni-Channel Status Changer" icon-name="standard:service_crew_member">
        <div class="slds-m-around_medium">
            <template if:true={presenceStatuses.data}>
                <p class="slds-m-bottom_small"><b>Select your status:</b></p>
                <template for:each={presenceStatuses.data.statuses} for:item="status">
                    <lightning-button
                        key={status.id}
                        label={status.label}
                        data-status-id={status.id}
                        onclick={handleStatusChange}
                        class="slds-m-left_x-small">
                    </lightning-button>
                </template>
            </template>
            <template if:true={presenceStatuses.error}>
                <p>Error loading statuses: {presenceStatuses.error}</p>
            </template>
        </div>

        <div class="slds-m-around_medium">
            <lightning-button label="Login to Omni" onclick={handleLogin} variant="brand"></lightning-button>
            <lightning-button label="Logout from Omni" onclick={handleLogout} variant="destructive" class="slds-m-left_x-small"></lightning-button>
        </div>
    </lightning-card>
</template>

omniStatusChanger.js

import { LightningElement, wire } from 'lwc';
import { ShowToastEvent } from 'lightning/platformShowToastEvent';
import { getServicePresenceStatusId, setServicePresenceStatus, login, logout } from 'lightning/omniToolkitApi';

export default class OmniStatusChanger extends LightningElement {
    // 使用 wire service 来响应式地获取所有可用的服务在线状态
    // 当状态数据加载完成或发生变化时，`presenceStatuses` 会被自动更新
    @wire(getServicePresenceStatusId)
    presenceStatuses;

    // 处理状态变更按钮的点击事件
    handleStatusChange(event) {
        // 从被点击的按钮的 dataset 中获取状态 ID
        const statusId = event.target.dataset.statusId;
        
        // 调用 setServicePresenceStatus API 方法来更新座席状态
        // 这是一个异步操作，返回一个 Promise
        setServicePresenceStatus({ statusId: statusId })
            .then(result => {
                // 当 Promise 成功解析时，显示成功提示
                this.showToast('Success', 'Presence status set to ' + result.statusName, 'success');
            })
            .catch(error => {
                // 当 Promise 被拒绝时，捕获错误并显示错误提示
                console.error('Error setting presence status', JSON.stringify(error));
                this.showToast('Error', 'Failed to set presence status: ' + error.message, 'error');
            });
    }

    // 处理登录按钮的点击事件
    handleLogin() {
        // 确保状态列表已加载
        if (this.presenceStatuses.data && this.presenceStatuses.data.statuses.length > 0) {
            // 使用第一个可用的“在线”状态进行登录
            // 在实际应用中，您可能需要更复杂的逻辑来选择默认登录状态
            const onlineStatus = this.presenceStatuses.data.statuses.find(status => status.statusType === 'Online');
            if (onlineStatus) {
                login({ statusId: onlineStatus.id })
                    .then(result => {
                        this.showToast('Success', 'Logged in to Omni-Channel', 'success');
                    })
                    .catch(error => {
                        console.error('Error logging in', JSON.stringify(error));
                        this.showToast('Error', 'Failed to login: ' + error.message, 'error');
                    });
            } else {
                this.showToast('Error', 'No "Online" status found to login.', 'error');
            }
        }
    }

    // 处理登出按钮的点击事件
    handleLogout() {
        logout()
            .then(result => {
                this.showToast('Success', 'Logged out from Omni-Channel', 'success');
            })
            .catch(error => {
                console.error('Error logging out', JSON.stringify(error));
                this.showToast('Error', 'Failed to logout: ' + error.message, 'error');
            });
    }

    // 辅助方法，用于显示 Toast 通知
    showToast(title, message, variant) {
        const event = new ShowToastEvent({
            title: title,
            message: message,
            variant: variant,
        });
        this.dispatchEvent(event);
    }
}

注意事项

在使用 Omni-Channel Toolkit API 时，开发人员必须注意以下几点，以确保应用的稳定性和安全性：

1. 权限与配置

使用此 API 的用户必须被分配了 "Omni-Channel User" 或等效的权限集。此外，必须在 Salesforce 中正确配置 Omni-Channel，包括设置服务渠道 (Service Channels)、路由配置 (Routing Configurations)、在线状态 (Presence Statuses) 和在线配置 (Presence Configurations)。如果配置不当，API 调用将会失败。

2. 运行环境限制

如前所述，该 API 只能在 Lightning Experience 的控制台应用中运行。如果尝试在标准导航应用、Salesforce Classic、Visualforce 页面或外部网站中调用这些方法，将会抛出错误。在开发 LWC 时，请确保其元数据文件 (js-meta.xml) 中指定了正确的目标，例如 lightning__UtilityBar 或 lightning__RecordPage，并将其部署到控制台应用中。

3. 错误处理

所有 API 方法都返回 Promise。这意味着网络延迟、服务器错误或配置问题都可能导致 Promise 被拒绝 (reject)。开发人员必须为每个 API 调用实现健壮的 .catch() 逻辑，向用户提供清晰的错误信息，并记录详细的错误日志以供调试。忽略错误处理可能导致组件在用户面前静默失败，严重影响用户体验。

4. API 限制

虽然功能强大，但 API 也有其限制。例如，它无法创建或修改 Omni-Channel 的配置（如创建新的在线状态），这些操作仍需通过 Salesforce Setup 界面完成。API 的主要作用是与座席的运行时状态进行交互。

总结与最佳实践

Omni-Channel Toolkit API 是 Salesforce Service Cloud 平台为开发人员提供的一把利器。它打破了标准界面的束缚，让我们能够构建完全定制化、高度集成的客服座席体验，从而显著提升客服中心的运营效率和座席满意度。

最佳实践

构建可重用组件： 将与 Omni-Channel 相关的逻辑封装在独立的、可重用的 LWC 中。例如，创建一个通用的状态管理组件，可以在多个不同的控制台应用或页面布局中复用。
提供明确的视觉反馈： 当通过 API 改变座席状态或工作状态时，务必在 UI 上提供清晰、即时的反馈。例如，高亮显示当前状态按钮，或在接受工作后显示一个简短的成功动画。
考虑用户上下文： 设计组件时，要充分考虑座席的工作流程。避免不必要或干扰性的自动化。例如，在座席正在输入时，不要自动弹出窗口或改变其状态。
充分测试： 在配置完整的 Sandbox 环境中进行详尽的测试。模拟各种场景，包括高负载、网络不稳定和并发操作，以确保您的自定义组件在真实世界的压力下依然表现稳定。
遵循 Salesforce 平台开发规范： 遵循 LWC 开发的最佳实践，如模块化、错误边界处理和高效的事件通信，确保代码的可维护性和扩展性。

通过遵循这些原则并充分利用 Omni-Channel Toolkit API，您可以将您的 Service Cloud 实施提升到一个新的水平，为您的企业打造世界级的客户服务解决方案。

Salesforce中文网