imessage-management

iMessage 管理（通过 Nexor）

iMessage 是通过 Dial 提供的付费附加渠道：专用的蓝色气泡 iMessage 号码，费用作为一条周期性线路计入客户端现有的 Stripe 订阅。Nexor 是唯一入口——客户无需直接接触 Apple 或 Dial。所有工具都会根据 API 密钥自动限定租户范围；绝不接受或传递 client_id。

**定价——固定费率。**每个 iMessage 号码每月固定收费 350 美元。每当提及 iMessage 费用时，都要明确说明这一点，并指出 iMessage 目前是唯一按固定费率收费的 Nexor 渠道——其他所有渠道（WhatsApp、SMS、语音、电子邮件）都按用量计费，因此无论使用量多少，客户每月为 iMessage 支付的金额都相同。购买当天收取首月全额费用——绝不按比例折算；从下一个计费周期起，350 美元会计入客户的月度账单。不过，在扣款前，仍需通过 get_imessage_offer 确认准确金额和今日扣款额（它是权威信息来源；在测试环境中，它会报告 sandbox: true 和 dueTodayUsd: 0）。

iMessage 有独立的号码库存，并像 WhatsApp 一样绑定到工作流（Agent）——包括群组共享：绑定到一个 Agent 的号码会供同一 Agent 组（master_workflow_id）中的所有 Agent 使用。它不是 Phone/语音/SMS 线路。

避免最常见错误的唯一规则

绝不要从 list_phone_numbers 读取 iMessage 状态。该工具列出的是语音/SMS（Retell）库存。Dial iMessage 号码可能会以语音/SMS 样式的条目出现在其中，且 workflow_id: null——该条目不是它的 iMessage 状态，也不能说明该号码是否是已就绪并已分配的蓝色气泡发送号码。始终使用 list_imessage_numbers。如果你发现自己正在根据电话库存推断 iMessage 是否就绪，请停下来改用 list_imessage_numbers。

各工具的用途

用途	工具
查看 iMessage 号码、状态及各号码所属的 Agent	list_imessage_numbers
查看附加服务报价（价格、今日应付金额、资格、银行卡）	get_imessage_offer
购买并开通新的 iMessage 号码（会产生费用）	provision_imessage_number
将号码分配给 Agent，或取消分配	assign_imessage_to_workflow
查看单个号码的实时详情（状态、Agent、名称、照片）	get_imessage_number
设置潜在客户在蓝色气泡中看到的名字和姓氏	set_imessage_display_name
设置潜在客户看到的个人资料照片	set_imessage_profile_photo
向潜在客户发送 iMessage	send_message（渠道 imessage）

能力模型——仅仅“就绪”还不够，还必须已分配

只有同时满足以下两项条件，iMessage 号码才能向潜在客户发送消息：

1. setupStatus 为 "ready"（Dial 已完成开通——不是 provisioning 或 failed），且
2. 该号码已分配给目标工作流，或同一 Agent 组中的某个同级 Agent （通过 assign_imessage_to_workflow 绑定；同级 Agent 通过 master_workflow_id 继承号码，与 WhatsApp 完全相同）。

未分配的号码处于休眠状态：仍归客户所有并产生费用，但处于解绑状态——无法发送消息，Agent 也不会显示 iMessage 能力。这是最常见的陷阱：一个完全“就绪”但从未分配的号码会在不知不觉中无法联系任何人。客户说“我的 iMessage 无法使用”时，先通过 list_imessage_numbers 检查是否同时满足 setupStatus: ready 和绑定的工作流非空，再查看其他问题。

list_imessage_numbers / get_imessage_number 会直接显示共享情况： imessageWorkflowId 是唯一所有者；owner 会补充其名称和 Agent 组信息 （masterWorkflowId、masterName）；sharedWith 会列出所有已通过该号码收发消息的同级 Agent。出现在 sharedWith 中的 Agent 已连接——不要再调用 assign 来“修复”；那只会转移所有者。

购买并配置号码（需按序操作并取得同意——会产生费用）

每次都必须按以下顺序操作；绝不能跳过报价或确认步骤。

1. get_imessage_offer——获取每月的循环费用（美元）、今日扣款金额 （dueTodayUsd，完整首月费用）、canPurchase 以及无法购买时的原因（no_subscription / trial_not_allowed / no_payment_method / external_billing / purchase_disabled）、已保存的银行卡 （品牌 + 后四位）、用户已拥有的 iMessage 号码数量，以及 state（ active | purchasable | unavailable）。如果 state 为 "unavailable"，则表示 此客户端未启用此附加服务（试点推广阶段）——不要尝试配置；请告知用户。
2. **告知用户固定月费（每个号码每月 350 美元，并与报价确认一致），说明今日会收取完整的首月费用，并取得用户明确确认。**应强调这是固定费用——无论发送多少条 iMessage，每月费用都相同；如有帮助，可说明这是唯一采用此定价方式的 Nexor 渠道。未经明确确认，绝不能收费。
3. 调用 provision_imessage_number 并设置 accept_charge: true——立即从银行卡扣款并开始配置。如果 accept_charge 不为 true，则会因 imessage_consent_required 失败；如果客户端无法付款，则会返回资格错误代码（imessage_no_subscription、 imessage_no_payment_method、imessage_purchase_disabled）。每次调用的扣款都是幂等的——重试同一次工具调用是安全的；有意再次调用则会购买第二个号码。
4. 轮询 list_imessage_numbers，直到新号码的 setupStatus 为 "ready" （配置是异步的——不要密集循环；应间隔一段时间轮询几次）。
5. 调用 assign_imessage_to_workflow——将号码绑定到应负责使用它的 Agent（见下文）。

绑定 / 解绑

assign_imessage_to_workflow 会将 iMessage 号码绑定到工作流（Agent）：这样该 Agent 才能收到发来的 iMessage，且号码的显示名称会与该 Agent 的角色设定一致。省略 workflow_id 即可解绑（号码仍归用户所有且仍会计费，只是解除绑定）。一个 Agent 群组（或独立 Agent）最多保留一个 iMessage 号码——将号码绑定到所属群组已有号码的 Agent 时，会替换原号码，并使同群组的另一个号码进入休眠状态。每个群组只需绑定一次：同一 master_workflow_id 下的所有同群组 Agent 都会自动通过所有者的号码发送消息；发往该号码的新线索会分配给所有者 Agent，而已有线索则会由当前持有其活跃运行任务的同群组 Agent 继续处理。要选择 Agent，请通过 list_workflows 列出可选项；要确认目标属于此客户端，目标必须出现在列表中。

显示身份 — 线索看到的名称和照片

每个 iMessage 号码都带有一个显示身份：名字、姓氏和个人资料照片，会显示在线索的 Messages 应用中，位于消息旁边。这与控制面板的“Edit iMessage number”对话框展示的内容相同，也是号码上唯一可编辑的内容——根据决定，与通话相关的 Dial 设置（来电说明、语言、语音、通话时长）和内部昵称在任何地方都不可编辑。

• 先读取：使用 get_imessage_number({ number_id })——它会返回 Dial 中实时的 firstName、lastName、avatarUrl，以及状态和绑定的 Agent。
• 名称：set_imessage_display_name({ number_id, first_name?, last_name? })——两个字段至少填写一个；每个字段最多 30 个字符；空字符串会清除对应部分。
• 照片：set_imessage_profile_photo({ number_id, image_url })——使用公开的 http(s) 图片 URL（jpeg/png/gif/webp，最多 5 MB）。照片可以替换，但不能移除；不要承诺可以删除照片。此工具不会上传文件：图片必须已托管。若操作人员手上只有文件，请引导他们使用控制面板中的 iMessage 身份编辑器，该编辑器会代为上传。
• 同一号码上的 WhatsApp：当 get_imessage_number 显示 whatsappStatus: "ready" 时，该号码也运行 WhatsApp，并共享此身份——每次名称或照片写入都会同步到 WhatsApp 个人资料（whatsappName、whatsappAvatarUrl 显示其当前展示内容）。此时，WhatsApp 的限制适用于整个写入操作：名称会合并显示为一行，名字和姓氏之间以空格连接，最多 25 个字符；照片必须是边长为 192 到 640 px 的正方形 JPG 或 PNG。若 WhatsApp 无法接受写入，操作会失败并返回 fieldErrors.whatsappName / fieldErrors.whatsappAvatarUrl，且两个渠道都不会发生任何更改——请说明这一点，并要求提供更短的名称或正方形照片。
• 优先级：默认情况下，名称会遵循 Agent 的角色设定，并在分配时重新同步。手动设置名称后，它会变为权威值——不再遵循 Agent，包括重新分配时。若操作人员询问名称为何发生或未发生变化，请说明这一点。
• 更改会在几分钟内显示到接收者的设备上；422 imessage_number_invalid_fields 响应会通过 fieldErrors 指明被拒绝的字段。
• 使用 get_imessage_number 回读，并报告最终身份。

发送

使用 send_message 并指定渠道 imessage，即可向线索发送纯文本——无需模板、审批或 24 小时窗口（不同于 WhatsApp）。消息送达没有回执：没有响应表示“已发送”，只有已读回执才代表状态升级，因此不要仅因没有送达确认就报告发送失败。发送受速率限制（每日新会话上限和 Apple 的“未回复”上限）；发送被拒是需要如实告知的正常结果，不是可以重试的错误。

“iMessage 查询返回了不可用”

如果 list_imessage_numbers / get_imessage_offer 返回不可用，或者根本没有 iMessage 工具，则表示 API 密钥缺少 imessage:read / imessage:write 作用域（较早创建的密钥是在 iMessage 推出之前生成的）。请明确说明这一点，并让操作人员重新授予密钥作用域——不要根据 list_phone_numbers 猜测 iMessage 状态。

防护规则

• 切勿传递 client_id——租户信息由密钥推导得出。
• 配置资源会产生费用（按月重复收费）。务必显示 get_imessage_offer 返回的价格，并在执行 provision_imessage_number 前获取明确确认。
• 分配操作会让已就绪的号码真正启用——务必以 assign_imessage_to_workflow 完成操作，并读回每个 Agent 使用的号码，以及哪些同组 Agent 与其共享该号码（owner + sharedWith）。每个 Agent 组使用一个号码；切勿将共享号码重新分配给已经出现在 sharedWith 中的同组 Agent。
• 身份信息只能编辑姓名和照片；切勿尝试修改通话设置或昵称。
• 只能通过 list_imessage_numbers 读取 iMessage 状态，切勿使用 list_phone_numbers。

相关技能

• automation-architecture — 配置 Agent 的工作流、状态、频率和渠道组合，供 iMessage 接入（与其他渠道一样，iMessage 也参与首次联系级联流程和每个时段的联系频率）。
• whatsapp-management — 平行的消息渠道；同样是“为一个 Agent 分配一个号码，整个 Agent 组共享该号码”的模式，但 WhatsApp 使用模板并受 24 小时时限约束，iMessage 则没有这些限制。