service-agentforce-channel-configure

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

service-agentforce-channel-configure: Wire an Agentforce agent to a channel

service-agentforce-channel-configure：将Agentforce agent连接到渠道

Adds inbound routing between an existing channel and an existing Agentforce agent. The agent receives work items from the channel; a fallback queue handles overflow when the agent is unavailable.

This skill is generic — it works for any Agentforce agent, not just the Help Agent template.

为现有渠道与现有Agentforce agent添加入站路由。agent将接收来自渠道的工作项；当agent不可用时，回退队列将处理溢出的工作。

此技能为通用技能——适用于任何Agentforce agent，而非仅Help Agent模板。

Scope

适用范围

In scope:

Resolving or creating a fallback queue with the correct
```
QueueSobject
```
SobjectType
Branch A (Enhanced Chat / Enhanced Messaging): deploying
```
sessionHandlerType=AgentforceServiceAgent
```
+
```
sessionHandlerQueue
```
on an existing MessagingChannel, then binding
```
SessionHandlerId
```
via Data API PATCH
Branch B (Voice): assumes the phone number and
```
PstnVoice
```
MessagingChannel already exist (provisioned by the caller, e.g.
```
service-helpagent-coordinate
```
), then creating an inbound RoutingFlow (
```
routingType: Copilot
```
) that routes to the agent with the queue as fallback
Branch C (Email-to-Case): same inbound RoutingFlow, using the org-specific Case-based ServiceChannel
Optional outbound escalation: adding the appropriate
```
connection {type}:
```
block to the agent and republishing

Out of scope:

Creating the agent — use

agentforce-generate

service-helpagent-coordinate

Creating the MessagingChannel — use

service-digital-engagement-channel-configure

Creating the Embedded Service Deployment — use
```
service-digital-engagement-deployment-configure
```
Creating the Voice or Email-to-Case channel infrastructure
Outbound escalation RoutingFlow creation — surface the gap if one is needed and doesn't exist

包含范围：

解析或创建具有正确
```
QueueSobject
```
SobjectType的回退队列
分支A（增强聊天/增强消息）：在现有MessagingChannel上部署
```
sessionHandlerType=AgentforceServiceAgent
```
+
```
sessionHandlerQueue
```
，然后通过Data API PATCH绑定
```
SessionHandlerId
```
分支B（语音）：假设电话号码和
```
PstnVoice
```
MessagingChannel已存在（由调用方预配置，例如
```
service-helpagent-coordinate
```
），然后创建入站RoutingFlow（
```
routingType: Copilot
```
），将请求路由到agent，队列作为回退
分支C（邮件转案例）：使用组织特定的基于案例的ServiceChannel，配置相同的入站RoutingFlow
可选出站升级：为agent添加相应的
```
connection {type}:
```
块并重新发布

排除范围：

创建agent——请使用

agentforce-generate

或

service-helpagent-coordinate

创建MessagingChannel——请使用

service-digital-engagement-channel-configure

创建嵌入式服务部署——请使用

service-digital-engagement-deployment-configure

创建语音或邮件转案例的渠道基础设施
创建出站升级RoutingFlow——如果需要但不存在此流程，请告知用户该缺口

Required inputs

必填输入项

Agent
DeveloperName
and agent label (
```
MasterLabel
```
) — must be an existing, active agent
Channel type — one of: Enhanced Chat, Enhanced Messaging (3rd-party), Voice, Email-to-Case
Channel identifier — MessagingChannel
```
DeveloperName
```
(Branch A), or the channel name/context (Branches B/C)
Target org alias

Agent
DeveloperName
和 agent标签（
```
MasterLabel
```
）——必须是已存在的活跃agent
渠道类型——可选值：Enhanced Chat、Enhanced Messaging（第三方）、Voice、Email-to-Case
渠道标识符——MessagingChannel
```
DeveloperName
```
（分支A），或渠道名称/上下文（分支B/C）
目标组织别名

Workflow

工作流程

Steps are sequential. Read

references/channel-types.md

first to confirm the routing branch before proceeding.

步骤按顺序执行。在开始前，请先阅读

references/channel-types.md

以确认路由分支。

Phase 1 — Verify agent and resolve queue

阶段1 — 验证agent并解析队列

Confirm the agent exists and has an active version:

bash

# Get the definition
sf data query --target-org $ORG --json \
  --query "SELECT Id, DeveloperName, MasterLabel FROM BotDefinition WHERE DeveloperName='{AGENT_DEVELOPER_NAME}'"

# Check for an Active version
sf data query --target-org $ORG --json \
  --query "SELECT Id, Status FROM BotVersion WHERE BotDefinitionId='{BOT_DEFINITION_ID}' AND Status='Active' LIMIT 1"

Stop with a clear message if the definition is not found or no version has

Status = Active

Resolve the fallback queue and routing configuration — follow
```
references/queue-resolution.md
```
:
- Determine SobjectType from the channel type (see
```
references/channel-types.md
```
  )
- Query existing compatible queues; present via
```
AskUserQuestion
```
  or create new
- Query for an existing
```
QueueRoutingConfig
```
  ; create one with the correct capacity percentage if absent
- Capture
```
QUEUE_DEVELOPER_NAME
```
  ,
```
QUEUE_NAME
```
  , and
```
QUEUE_ID
```

确认agent存在且有活跃版本：

bash

# 获取定义
sf data query --target-org $ORG --json \
  --query "SELECT Id, DeveloperName, MasterLabel FROM BotDefinition WHERE DeveloperName='{AGENT_DEVELOPER_NAME}'"

# 检查是否有活跃版本
sf data query --target-org $ORG --json \
  --query "SELECT Id, Status FROM BotVersion WHERE BotDefinitionId='{BOT_DEFINITION_ID}' AND Status='Active' LIMIT 1"

如果未找到定义或没有版本的

Status = Active

，则停止操作并给出明确提示。

解析回退队列和路由配置——遵循
```
references/queue-resolution.md
```
：
- 根据渠道类型确定SobjectType（参见
```
references/channel-types.md
```
  ）
- 查询现有兼容队列；通过
```
AskUserQuestion
```
  展示结果或创建新队列
- 查询现有
```
QueueRoutingConfig
```
  ；如果不存在，则创建一个具有正确容量百分比的配置
- 记录
```
QUEUE_DEVELOPER_NAME
```
  、
```
QUEUE_NAME
```
  和
```
QUEUE_ID
```

Phase 2 — Wire inbound routing

阶段2 — 配置入站路由

Live-traffic warning gate (runs before any branch)

实时流量警告闸门（在任何分支前运行）

Before making any routing change, detect whether the channel already has active inbound routing (Branch A: non-empty

SessionHandlerType

; Branches B/C: any active RoutingFlow assigned to the service channel). If it does, first check whether the user's prompt already answered the timing choice ("do not cut over" / "wire manually" / "review first" → defer silently; "cut over now" / "activate immediately" → proceed silently). Only if the prompt is silent, warn via

AskUserQuestion

and let the user choose "Re-route now" or "Set up, then wire manually" — and on any ambiguous or no-selection response, default to the deferred path (never to a live re-route). When deferred, set

DEFER_INBOUND_ROUTING=true

, skip the channel-activation step in the chosen branch, and print the manual wiring instructions at the end of Phase 2.

If the channel has no existing routing, skip this gate entirely and proceed directly.

Full detection queries, exact

AskUserQuestion

block, deferred-flow rules per branch, and manual-wiring copy:

references/live-traffic-gate.md

在进行任何路由更改前，检测渠道是否已存在活跃入站路由（分支A：

SessionHandlerType

非空；分支B/C：服务渠道已分配任何活跃RoutingFlow）。如果已存在，首先检查用户的提示是否已明确选择切换时机（"不切换" / "手动配置" / "先审核" → 静默延迟；"立即切换" / "立即激活" → 静默继续）。只有当提示未明确说明时，才通过

AskUserQuestion

发出警告，让用户选择**"立即重新路由"或"先配置，再手动切换"**——如果响应模糊或未选择，则默认采用延迟路径（绝不直接进行实时重新路由）。如果选择延迟，设置

DEFER_INBOUND_ROUTING=true

，跳过所选分支中的渠道激活步骤，并在阶段2结束时打印手动配置说明。

如果渠道没有现有路由，则直接跳过此闸门继续操作。

完整的检测查询、精确的

AskUserQuestion

块、各分支的延迟流程规则以及手动配置说明，请参见

references/live-traffic-gate.md

。

Branch A — Enhanced Chat / Enhanced Messaging (3rd-party)

分支A — 增强聊天/增强消息（第三方）

No RoutingFlow required. Deploy the MessagingChannel with

sessionHandlerType

sessionHandlerQueue

only, then bind the bot via a Data API PATCH.

sessionHandlerAsa

is not accepted by the Metadata API at v67 — the deploy silently drops it and

SessionHandlerId

stays null unless you run the PATCH. The bot must be Active before the PATCH ("Only active Agentforce Service Agents are supported" otherwise).

All five steps below are mandatory and must run in order — do not skip the retrieve/edit/deploy and jump straight to the PATCH. Run the retrieve and edit in the current working directory (a real SFDX project), so the edited

.messagingChannel-meta.xml

is saved into the project's

force-app

tree — not a throwaway temp dir. Steps 1–3 record the routing change in source; steps 4–5 apply the binding the Metadata API can't.

Retrieve the current MessagingChannel metadata into the working-directory project:

bash

sf project retrieve start \
  --metadata "MessagingChannel:{CHANNEL_DEVELOPER_NAME}" \
  --target-org $ORG

Edit the retrieved
.messagingChannel-meta.xml
in place — set exactly these two fields (do NOT add
```
<sessionHandlerAsa>
```
):
xml
```
<sessionHandlerType>AgentforceServiceAgent</sessionHandlerType>
<sessionHandlerQueue>{QUEUE_DEVELOPER_NAME}</sessionHandlerQueue>
```
Apply this edit with the file-editing tool (Edit/Write) so the change is saved to the retrieved file at
```
force-app/main/default/messagingChannels/{CHANNEL_DEVELOPER_NAME}.messagingChannel-meta.xml
```
in the working directory — do not hand-edit it through an inline
```
sed
```
/
```
cat
```
heredoc into a temp path. The deploy in step 3 must read this same on-disk file.

Deploy:

bash

sf project deploy start \
  --metadata "MessagingChannel:{CHANNEL_DEVELOPER_NAME}" \
  --target-org $ORG

Bind the bot via Data API PATCH:

bash

CHAN_ID=$(sf data query --target-org $ORG --json \
  --query "SELECT Id FROM MessagingChannel WHERE DeveloperName='{CHANNEL_DEVELOPER_NAME}'" \
  | python3 -c "import sys,json; print(json.load(sys.stdin)['result']['records'][0]['Id'])")
BOT_ID=$(sf data query --target-org $ORG --json \
  --query "SELECT Id FROM BotDefinition WHERE DeveloperName='{AGENT_DEVELOPER_NAME}'" \
  | python3 -c "import sys,json; print(json.load(sys.stdin)['result']['records'][0]['Id'])")
QUEUE_ID=$(sf data query --target-org $ORG --json \
  --query "SELECT Id FROM Group WHERE Type='Queue' AND DeveloperName='{QUEUE_DEVELOPER_NAME}'" \
  | python3 -c "import sys,json; print(json.load(sys.stdin)['result']['records'][0]['Id'])")

sf api request rest --method PATCH -o $ORG \
  "/services/data/v67.0/sobjects/MessagingChannel/${CHAN_ID}" \
  --body "{\"SessionHandlerId\":\"${BOT_ID}\",\"FallbackQueueId\":\"${QUEUE_ID}\"}"
# Expected: HTTP 204

Verify:

bash

sf data query --target-org $ORG --json \
  --query "SELECT SessionHandlerId, FallbackQueueId FROM MessagingChannel WHERE Id='${CHAN_ID}'"

Both

SessionHandlerId

and

FallbackQueueId

must be non-null.

No agent file changes — no republish needed. Proceed to Phase 3 (optional).

无需RoutingFlow。仅需在MessagingChannel上部署

sessionHandlerType

sessionHandlerQueue

，然后通过Data API PATCH绑定bot。在v67版本的Metadata API中，

sessionHandlerAsa

不被接受——部署会静默丢弃该字段，除非运行PATCH，否则

SessionHandlerId

将保持为空。在执行PATCH前，bot必须处于活跃状态（否则会提示"仅支持活跃的Agentforce Service Agents"）。

以下五个步骤均为必填项，必须按顺序执行——请勿跳过检索/编辑/部署步骤直接执行PATCH。在当前工作目录（真实的SFDX项目）中执行检索和编辑，以便将编辑后的

.messagingChannel-meta.xml

保存到项目的

force-app

目录中——而非临时目录。步骤1–3将路由更改记录到源码中；步骤4–5完成Metadata API无法实现的绑定操作。

将当前MessagingChannel元数据检索到工作目录的项目中：

bash

sf project retrieve start \
  --metadata "MessagingChannel:{CHANNEL_DEVELOPER_NAME}" \
  --target-org $ORG

在原地编辑检索到的
.messagingChannel-meta.xml
——仅设置以下两个字段（请勿添加
```
<sessionHandlerAsa>
```
）：
xml
```
<sessionHandlerType>AgentforceServiceAgent</sessionHandlerType>
<sessionHandlerQueue>{QUEUE_DEVELOPER_NAME}</sessionHandlerQueue>
```
使用文件编辑工具（Edit/Write）进行此编辑，确保更改保存到工作目录中
```
force-app/main/default/messagingChannels/{CHANNEL_DEVELOPER_NAME}.messagingChannel-meta.xml
```
的检索文件中——请勿通过内联
```
sed
```
/
```
cat
```
heredoc将编辑内容写入临时路径。步骤3中的部署必须读取此磁盘文件。

部署：

bash

sf project deploy start \
  --metadata "MessagingChannel:{CHANNEL_DEVELOPER_NAME}" \
  --target-org $ORG

通过Data API PATCH绑定bot：

bash

CHAN_ID=$(sf data query --target-org $ORG --json \
  --query "SELECT Id FROM MessagingChannel WHERE DeveloperName='{CHANNEL_DEVELOPER_NAME}'" \
  | python3 -c "import sys,json; print(json.load(sys.stdin)['result']['records'][0]['Id'])")
BOT_ID=$(sf data query --target-org $ORG --json \
  --query "SELECT Id FROM BotDefinition WHERE DeveloperName='{AGENT_DEVELOPER_NAME}'" \
  | python3 -c "import sys,json; print(json.load(sys.stdin)['result']['records'][0]['Id'])")
QUEUE_ID=$(sf data query --target-org $ORG --json \
  --query "SELECT Id FROM Group WHERE Type='Queue' AND DeveloperName='{QUEUE_DEVELOPER_NAME}'" \
  | python3 -c "import sys,json; print(json.load(sys.stdin)['result']['records'][0]['Id'])")

sf api request rest --method PATCH -o $ORG \
  "/services/data/v67.0/sobjects/MessagingChannel/${CHAN_ID}" \
  --body "{\"SessionHandlerId\":\"${BOT_ID}\",\"FallbackQueueId\":\"${QUEUE_ID}\"}"
# 预期结果：HTTP 204

验证：

bash

sf data query --target-org $ORG --json \
  --query "SELECT SessionHandlerId, FallbackQueueId FROM MessagingChannel WHERE Id='${CHAN_ID}'"

SessionHandlerId

和

FallbackQueueId

必须均为非空值。

无需更改agent文件——无需重新发布。继续执行阶段3（可选）。

Branch B — Voice

分支B — 语音

Wires a

PstnVoice

MessagingChannel to the agent via an inbound

Copilot

-type RoutingFlow with the queue as fallback. Distinct from Branch A: no

sessionHandlerAsa

; the channel is bound to the flow (

sessionHandlerType=Flow

), and the agent needs a

modality voice:

block appended before republish.

references/channel-branch-voice.md

end to end. Highlights:

Step 0 — reuse an existing
```
PstnVoice
```
MessagingChannel or have
```
service-helpagent-coordinate
```
provision one first (its
```
references/channel-voice.md
```
); abort if the org uses a partner telephony provider (see
```
references/channel-types.md
```
).
Steps 1–3 — write and deploy the inbound RoutingFlow using the template in
```
references/routing-flow.md
```
, verifying
```
ActiveVersionId
```
is non-null.

Step 4 — deploy a

MessagingChannel

metadata file for

{CHANNEL_DEVELOPER_NAME}

with

sessionHandlerType=Flow

sessionHandlerFlow={FLOW_DEVELOPER_NAME}

sessionHandlerQueue={QUEUE_DEVELOPER_NAME}

. Without this the flow is never executed and calls hang up. Verify

SessionHandlerId

starts with

Step 5 — append the platform-default
```
modality voice:
```
block (voice_id
```
UgBBYS2sOqTuMpoF3BR0
```
, "Mark", en_US) to the
```
.agent
```
file if missing; do not ask the user. Republish per
```
references/agent-wiring.md
```
.

Proceed to Phase 3 (optional).

通过入站

Copilot

类型的RoutingFlow将

PstnVoice

MessagingChannel连接到agent，队列作为回退。与分支A的区别：无需

sessionHandlerAsa

；渠道绑定到流程（

sessionHandlerType=Flow

），且agent需要在重新发布前添加

modality voice:

块。

完整遵循

references/channel-branch-voice.md

的步骤。重点内容：

步骤0——重用现有
```
PstnVoice
```
MessagingChannel，或先让
```
service-helpagent-coordinate
```
预配置一个（参见其
```
references/channel-voice.md
```
）；如果组织使用合作伙伴电话提供商，则终止操作（参见
```
references/channel-types.md
```
）。
步骤1–3——使用
```
references/routing-flow.md
```
中的模板编写并部署入站RoutingFlow，验证
```
ActiveVersionId
```
非空。

步骤4——为

{CHANNEL_DEVELOPER_NAME}

部署

MessagingChannel

元数据文件，设置

sessionHandlerType=Flow

、

sessionHandlerFlow={FLOW_DEVELOPER_NAME}

、

sessionHandlerQueue={QUEUE_DEVELOPER_NAME}

。如果不执行此步骤，流程将永远不会运行，呼叫会被挂断。验证

SessionHandlerId

以

开头。

步骤5——如果
```
.agent
```
文件中缺少平台默认的
```
modality voice:
```
块（voice_id
```
UgBBYS2sOqTuMpoF3BR0
```
，"Mark"，en_US），则添加该块；无需询问用户。按照
```
references/agent-wiring.md
```
重新发布。

继续执行阶段3（可选）。

Branch C — Email-to-Case

分支C — 邮件转案例

Same inbound RoutingFlow shape as Branch B, but using the org-specific Case-based ServiceChannel. Additionally requires an outbound

connection service_email:

and a mandatory manual BotEmailDefinition step in Setup — these are not optional and cannot be deferred to Phase 3.

references/channel-branch-email.md

end to end. Highlights:

Step 0 — verify
```
emailToCase.enableEmailToCase
```
and
```
emailToCase.enableOnDemandEmailToCase
```
are
```
true
```
in CaseSettings via the Tooling API; if either is off, deploy a settings file that enables both (safe-fields-only pattern) before continuing.
Step 1 — reuse an existing
```
EmailRoutingAddress
```
or create one for the support email address, then patch
```
caseOrigin
```
/
```
saveEmailHeaders: true
```
/
```
addressType: EmailToCase
```
for that entry in
```
CaseSettings.Metadata.caseEmailRoutingAddresses
```
via Tooling-API PATCH (fallback:
```
sf project deploy start --metadata Settings:Case
```
). Inform the user about the verification email but do not block on it.
Step 2 — query the Case-based ServiceChannel (see
```
references/channel-types.md
```
), then write and deploy the inbound RoutingFlow using the template in
```
references/routing-flow.md
```
; verify
```
ActiveVersionId
```
is non-null.
Step 3 — mandatory outbound: reuse or create
```
{AgentDevName}_Outbound_Email_Flow
```
(QueueBased template in
```
references/routing-flow.md
```
Part 2), then add
```
connection service_email:
```
to the agent and republish per
```
references/agent-wiring.md
```
.
Step 4 — mandatory manual: prompt the user to create an Email Configuration for Agentforce Service Agent at
```
{ORG_INSTANCE_URL}/lightning/setup/AsaForEmail/home
```
and set the Agentforce Configuration field on the Email-to-Case routing address. Wait for user confirmation.

Branch C is complete once the user confirms Step 4. Skip Phase 3 for Email-to-Case (outbound escalation is already handled inline).

入站RoutingFlow的结构与分支B相同，但使用组织特定的基于案例的ServiceChannel。此外，还需要出站

connection service_email:

块和Setup中必须手动完成的BotEmailDefinition步骤——这些不是可选操作，不能延迟到阶段3执行。

完整遵循

references/channel-branch-email.md

的步骤。重点内容：

步骤0——通过Tooling API验证CaseSettings中的
```
emailToCase.enableEmailToCase
```
和
```
emailToCase.enableOnDemandEmailToCase
```
是否为
```
true
```
；如果其中任何一个为关闭状态，则先部署启用这两个设置的配置文件（仅安全字段模式），然后再继续。
步骤1——重用现有
```
EmailRoutingAddress
```
或为支持邮箱创建一个，然后通过Tooling-API PATCH在
```
CaseSettings.Metadata.caseEmailRoutingAddresses
```
中更新该条目的
```
caseOrigin
```
/
```
saveEmailHeaders: true
```
/
```
addressType: EmailToCase
```
（备选方案：
```
sf project deploy start --metadata Settings:Case
```
）。告知用户会发送验证邮件，但无需等待验证完成。
步骤2——查询基于案例的ServiceChannel（参见
```
references/channel-types.md
```
），然后使用
```
references/routing-flow.md
```
中的模板编写并部署入站RoutingFlow；验证
```
ActiveVersionId
```
非空。
步骤3——必填出站配置：重用或创建
```
{AgentDevName}_Outbound_Email_Flow
```
（
```
references/routing-flow.md
```
第2部分中的QueueBased模板），然后为agent添加
```
connection service_email:
```
并按照
```
references/agent-wiring.md
```
重新发布。
步骤4——必填手动操作：提示用户在
```
{ORG_INSTANCE_URL}/lightning/setup/AsaForEmail/home
```
创建Agentforce Service Agent的邮件配置，并在邮件转案例路由地址上设置Agentforce配置字段。等待用户确认。

当用户确认步骤4完成后，分支C操作结束。邮件转案例场景跳过阶段3（出站升级已在分支C中处理）。

Phase 3 — Outbound escalation (optional — Branches A/B only)

阶段3 — 出站升级（可选 — 仅分支A/B）

Branch C (Email-to-Case): outbound escalation was handled inline in Branch C above. Do not run Phase 3 for Email-to-Case.

After inbound routing is confirmed (Branches A or B), ask the user:

"Inbound routing is now set up — the channel will route to [agent name]. Do you also want to configure outbound escalation so the agent can hand off to a human when requested?"

If yes:

Resolve the escalation queue — follow the escalation queue resolution steps in
```
references/queue-resolution.md
```
(Step 6). The user may want a different queue for escalation than the inbound fallback. Capture
```
ESCALATION_QUEUE_DEVELOPER_NAME
```
and
```
ESCALATION_QUEUE_ID
```
.
Determine the outbound flow name from the channel type (see naming table in
```
references/routing-flow.md
```
Part 2).

Check if an active outbound flow already exists:

bash

sf data query --target-org $ORG --json \
  --query "SELECT ApiName, ActiveVersionId FROM FlowDefinitionView WHERE ApiName='{OUTBOUND_FLOW_DEVELOPER_NAME}' AND ProcessType='RoutingFlow'"

Row exists with non-null
```
ActiveVersionId
```
→ reuse it; skip to step 4.
Row missing or
```
ActiveVersionId
```
null → create the flow using the QueueBased template in
```
references/routing-flow.md
```
Part 2, substituting
```
ESCALATION_QUEUE_DEVELOPER_NAME
```
for
```
QUEUE_DEVELOPER_NAME
```
. Deploy and verify
```
ActiveVersionId
```
is non-null before continuing.

Add the connection block to the agent's
```
.agent
```
file and republish — follow
```
references/agent-wiring.md
```
. The connection key depends on channel type:
- Enhanced Chat (EmbeddedMessaging) →
```
connection customer_web_client:
```
- Enhanced Messaging (3rd-party) →
```
connection messaging:
```
- Voice →
```
connection telephony:
```
- Email-to-Case →
```
connection service_email:
```

分支C（邮件转案例）： 出站升级已在分支C中处理。请勿为邮件转案例执行阶段3。

在确认入站路由配置完成后（分支A或B），询问用户：

"入站路由已配置完成——渠道将路由到[agent名称]。是否还需要配置出站升级，以便agent在接到请求时可以将对话转交给人工客服？"

如果用户选择是：

解析升级队列——遵循
```
references/queue-resolution.md
```
中的升级队列解析步骤（步骤6）。用户可能希望使用与入站回退不同的升级队列。记录
```
ESCALATION_QUEUE_DEVELOPER_NAME
```
和
```
ESCALATION_QUEUE_ID
```
。
根据渠道类型确定出站流程名称（参见
```
references/routing-flow.md
```
第2部分中的命名表）。

检查是否已存在活跃的出站流程：

bash

sf data query --target-org $ORG --json \
  --query "SELECT ApiName, ActiveVersionId FROM FlowDefinitionView WHERE ApiName='{OUTBOUND_FLOW_DEVELOPER_NAME}' AND ProcessType='RoutingFlow'"

存在记录且
```
ActiveVersionId
```
非空 → 重用该流程；跳至步骤4。
无记录或
```
ActiveVersionId
```
为空 → 使用
```
references/routing-flow.md
```
第2部分中的QueueBased模板创建流程，将
```
QUEUE_DEVELOPER_NAME
```
替换为
```
ESCALATION_QUEUE_DEVELOPER_NAME
```
。部署并验证
```
ActiveVersionId
```
非空后再继续。

将连接块添加到agent的
.agent
文件并重新发布——遵循
```
references/agent-wiring.md
```
。连接键取决于渠道类型：
- Enhanced Chat（EmbeddedMessaging） →
```
connection customer_web_client:
```
- Enhanced Messaging（第三方） →
```
connection messaging:
```
- Voice →
```
connection telephony:
```
- Email-to-Case →
```
connection service_email:
```

Rules / constraints

规则/约束

Rule	Rationale
Verify the agent exists and is Active before making any changes	Wiring a channel to a non-existent or inactive agent silently fails at runtime
If the channel already has active inbound routing, honor an explicit defer/cutover intent in the prompt without asking; otherwise warn via `AskUserQuestion` and default to defer on ambiguity	Re-routing takes effect immediately and affects live traffic — queue and RoutingFlow creation always proceed; only the activation step is gated, and the safe default is non-destructive
When deferred, print exact manual wiring instructions before Phase 3	The operator needs to know precisely what to run when they're ready to cut over
Never modify the MessagingChannel without retrieving the current metadata first	Overwriting without retrieval discards existing settings
Branch A: no RoutingFlow, no agent republish; deploy `sessionHandlerType` + `sessionHandlerQueue` via metadata, then bind `SessionHandlerId` via Data API PATCH	`sessionHandlerAsa` is not accepted by the Metadata API at v67 — the deploy silently drops it, so bot binding must happen via the Data API PATCH after deploy. Bot must be Active before the PATCH
Branches B/C: always create a new RoutingFlow — never reuse existing org flows	OOB platform flows commonly have `ActiveVersionId: null` and cannot be referenced
Branches B/C: use `routingType: Copilot` and `copilotLabel` — not `QueueBased`	`QueueBased` routes to the queue directly; `Copilot` routes to the agent first with the queue as fallback
Queue `Id` must be queried and embedded in the RoutingFlow XML	The `queueId` parameter requires a hardcoded 18-char record Id — do not leave it empty
Queue naming: `{ChannelTypeLabel} Queue`	Named after the channel type, not the agent
Outbound escalation is optional for Branches A/B — mandatory for Branch C (Email-to-Case)	BotEmailDefinition (Email Configuration in Setup) requires `connection service_email:` to already be on the agent; it cannot be created before the connection block is deployed

规则	理由
在进行任何更改前，验证agent存在且处于活跃状态	将渠道连接到不存在或非活跃的agent会导致运行时静默失败
如果渠道已存在活跃入站路由，遵循提示中明确的延迟/切换意图，无需询问；否则通过 `AskUserQuestion` 发出警告，模糊响应时默认采用延迟路径	重新路由会立即生效并影响实时流量——队列和RoutingFlow的创建始终执行；仅激活步骤受闸门控制，安全默认值为非破坏性操作
如果选择延迟，在阶段3前打印精确的手动配置说明	操作人员需要明确知道准备切换时应执行的操作
绝不未检索当前元数据就修改MessagingChannel	不检索就覆盖会丢弃现有设置
分支A：无需RoutingFlow，无需重新发布agent；通过元数据部署 `sessionHandlerType` + `sessionHandlerQueue` ，然后通过Data API PATCH绑定 `SessionHandlerId`	在v67版本的Metadata API中， `sessionHandlerAsa` 不被接受——部署会静默丢弃该字段，因此必须在部署后通过Data API PATCH完成bot绑定。执行PATCH前bot必须处于活跃状态
分支B/C：始终创建新的RoutingFlow——绝不重用组织现有流程	平台默认流程通常 `ActiveVersionId: null` ，无法被引用
分支B/C：使用 `routingType: Copilot` 和 `copilotLabel` ——而非 `QueueBased`	`QueueBased` 会直接路由到队列； `Copilot` 会先路由到agent，队列作为回退
必须查询Queue `Id` 并嵌入到RoutingFlow XML中	`queueId` 参数需要硬编码的18字符记录ID——不能为空
队列命名： `{ChannelTypeLabel} Queue`	按渠道类型命名，而非agent名称
分支A/B的出站升级为可选操作——分支C（邮件转案例）为必填操作	BotEmailDefinition（Setup中的邮件配置）要求agent上已存在 `connection service_email:` ；无法在连接块部署前创建该配置

Verification checklist

验证清单

Queue

队列

Queue has a
```
QueueSobject
```
record with the correct
```
SobjectType
```
for the channel type
Running user is a member of the queue (if newly created)
Queue has a
```
QueueRoutingConfig
```
with the correct
```
CapacityPercentage
```
(50 / 100 / 25 for Chat / Voice / Email)

队列具有与渠道类型匹配的正确
```
SobjectType
```
的
```
QueueSobject
```
记录
当前用户是队列成员（如果是新创建的队列）
队列具有正确
```
CapacityPercentage
```
的
```
QueueRoutingConfig
```
（聊天/语音/邮件分别为50/100/25）

Branch A — MessagingChannel

分支A — MessagingChannel

SessionHandlerType = AgentforceServiceAgent

after deploy

Bot is Active before the Data API PATCH
```
SessionHandlerId
```
is non-null after the Data API PATCH (matches the bot's
```
BotDefinition.Id
```
, starts with
```
0Xx
```
)
```
FallbackQueueId
```
is non-null after the Data API PATCH (matches the resolved queue Id)

部署后

SessionHandlerType = AgentforceServiceAgent

执行Data API PATCH前，Bot处于活跃状态
执行Data API PATCH后
```
SessionHandlerId
```
非空（与bot的
```
BotDefinition.Id
```
匹配，以
```
0Xx
```
开头）
执行Data API PATCH后
```
FallbackQueueId
```
非空（与解析后的队列ID匹配）

Branches B/C — RoutingFlow

分支B/C — RoutingFlow

RoutingFlow
```
ActiveVersionId
```
is non-null
```
routingType = Copilot
```
in the flow's
```
routeWork
```
action
```
copilotLabel
```
matches the agent's exact
```
MasterLabel
```
```
queueId
```
is populated (non-empty)

RoutingFlow的
```
ActiveVersionId
```
非空
流程的
```
routeWork
```
操作中
```
routingType = Copilot
```
```
copilotLabel
```
与agent的
```
MasterLabel
```
完全匹配
```
queueId
```
已填充（非空）

Branch C — Email routing address

分支C — 邮件路由地址

If new:
```
EmailRoutingAddress
```
record created with correct
```
PersonalName
```
and
```
Address
```

If new: CaseSettings patched with

caseOrigin

saveEmailHeaders: true

addressType: EmailToCase

If new: user informed that a verification email was sent to the support address (non-blocking)

如果是新创建的：
```
EmailRoutingAddress
```
记录已创建，且
```
PersonalName
```
和
```
Address
```
正确
如果是新创建的：CaseSettings已更新，设置
```
caseOrigin
```
、
```
saveEmailHeaders: true
```
、
```
addressType: EmailToCase
```
如果是新创建的：已告知用户会向支持邮箱发送验证邮件（非阻塞）

Branch C — BotEmailDefinition

分支C — BotEmailDefinition

User has confirmed creation of Email Configuration for Agentforce Service Agent at
```
/lightning/setup/AsaForEmail/home
```
Email-to-Case routing address has the Agentforce Configuration field set

用户已确认在
```
/lightning/setup/AsaForEmail/home
```
创建了Agentforce Service Agent的邮件配置
邮件转案例路由地址已设置Agentforce配置字段

Optional Phase 3 — Outbound escalation

可选阶段3 — 出站升级

Correct connection block used:
```
customer_web_client:
```
for EmbeddedMessaging,
```
messaging:
```
for 3rd-party,
```
telephony:
```
for Voice,
```
service_email:
```
for Email-to-Case
```
outboundRouteName
```
and
```
outboundRouteType
```
present in the correct
```
<plannerSurfaces>
```
entry of the deployed bundle
Agent status is Active after republish

使用了正确的连接块：EmbeddedMessaging使用
```
customer_web_client:
```
，第三方消息使用
```
messaging:
```
，语音使用
```
telephony:
```
，邮件转案例使用
```
service_email:
```

部署的包中，正确的

<plannerSurfaces>

条目包含

outboundRouteName

和

outboundRouteType

重新发布后agent状态为活跃

Reference file index

参考文件索引

File	When to read
`references/channel-types.md`	Phase 1 — determine SobjectType and routing branch
`references/queue-resolution.md`	Phase 1 — queue lookup, creation, and Id capture
`references/live-traffic-gate.md`	Phase 2 — detection queries, deferred-flow rules, and manual wiring copy for the live-traffic warning gate
`references/channel-branch-voice.md`	Branch B — full Voice inbound wiring: PstnVoice channel selection, RoutingFlow, MessagingChannel assignment, `modality voice:` republish
`references/channel-branch-email.md`	Branch C — full Email-to-Case wiring: CaseSettings flags, EmailRoutingAddress + read-modify-write patch, inbound RoutingFlow, mandatory outbound `connection service_email:` , BotEmailDefinition manual step
`references/routing-flow.md`	Branches B/C — inbound RoutingFlow XML template, deploy, verify
`references/agent-wiring.md`	Phase 3 (optional) — outbound escalation `connection messaging:` block

文件	阅读时机
`references/channel-types.md`	阶段1 — 确定SobjectType和路由分支
`references/queue-resolution.md`	阶段1 — 队列查找、创建和ID记录
`references/live-traffic-gate.md`	阶段2 — 实时流量警告闸门的检测查询、延迟流程规则和手动配置说明
`references/channel-branch-voice.md`	分支B — 完整的语音入站配置：PstnVoice渠道选择、RoutingFlow、MessagingChannel分配、 `modality voice:` 重新发布
`references/channel-branch-email.md`	分支C — 完整的邮件转案例配置：CaseSettings标志、EmailRoutingAddress + 读取-修改-写入补丁、入站RoutingFlow、必填出站 `connection service_email:` 、BotEmailDefinition手动步骤
`references/routing-flow.md`	分支B/C — 入站RoutingFlow XML模板、部署、验证
`references/agent-wiring.md`	阶段3（可选） — 出站升级 `connection messaging:` 块