salla-communication-app

Salla 通信应用

通信应用是一种接管消息发送的应用功能，用于短信、电子邮件或 WhatsApp。当商店事件触发时（订单状态变更、OTP 请求、弃购等），Salla 会将已编写好的消息传递给你的函数。你的函数从 context.settings 读取服务商凭据，调用服务商（Twilio / SendGrid / 360dialog / Unifonic / 任意服务商），并通过 Resp 工具返回结果。你负责路由和发送；Salla 负责触发。（概览）

前提条件：了解 App Functions 的基本用法 (salla-app-functions)——此处不再重复介绍运行时、Resp 和沙盒限制。（开始使用）

步骤 1 — 创建应用

按照 salla-app-builder 的说明，将 type 设为 "communication"。 选择「通信应用」类别后，支持的功能部分（步骤 2）才会解锁——否则不会显示渠道选项。 （渠道配置）与通用应用的区别：

• 没有 sub_category_id——通信应用不使用此项（只有 app 和 shipping 类型会用）。发布时仍需要 main_category_id——它来自通用的「应用主题」/「应用影响」列表（salla_reference action=categories → main_categories），而非通信专用类别树。
• 默认 Webhook 数量为 0——不会为你订阅任何内容（配送应用会获得默认的配送事件；通信应用则没有）。
• is_embedded 默认为 true。

检查点：「应用已创建，且 type: "communication"；现在是否已显示『支持的功能』部分？」

步骤 2 — 声明支持的渠道（发布阻断项）

Supported Features 用于声明应用处理哪些渠道。商家安装应用并将其设为某个渠道的活跃处理程序后，Salla 会停止使用默认的投递层，并将每条匹配的消息路由到你的 App Function——你的应用将完全负责处理该类型的消息。发布前，你必须至少声明一个渠道： (渠道配置)

• MCP：salla_settings action=set_features，值可为 sms_local、 sms_international、email_all、whatsapp 中的任意一个。
• 读取当前设置的功能：salla_settings action=list_features。（只返回已配置的功能，不会返回完整的类型架构。有效渠道值——sms_local、sms_international、email_all、whatsapp——来自工具架构，而非 API 响应。该工具封装了支持的功能端点——切勿直接调用这些端点。）

功能	set_features 值	事件	处理内容
本地 SMS	sms_local	communication.sms.send	发送至 KSA 号码（+966…）
国际 SMS	sms_international	communication.sms.send	发送至 KSA 以外地区
电子邮件	email_all	communication.email.send	所有电子邮件
WhatsApp	whatsapp	communication.whatsapp.send	所有 WhatsApp 消息

未设置功能就发布会失败，并返回 403 communication_app_not_have_features （slug 和渠道值会通过 salla_settings 工具架构显示——如果这些值发生变化，请通过 Partners MCP 或 Portal 核实当前值）。

SMS 应用需要 CITC 认证才能发布。 支持 SMS （sms_local / sms_international）的通信应用必须在账户验证表单 （https://portal.salla.partners/account）中上传其 CITC 认证——这是沙特阿拉伯的监管要求。 应用详情会显示 requires_citc（app_publish action=get / salla_apps action=get）： 当其值为 true 时，仍需要提供证书。合作伙伴必须在提交发布请求之前验证账户并上传证书；在此之前，提交会被阻止。发布流程 → salla-publication-consistency。

检查项：“是否已通过 salla_settings action=set_features 声明至少一个渠道——如果是 SMS 应用，requires_citc 是否为 false？”

步骤 3 — 设置服务提供商

在编写代码前，选择一个投递服务提供商并获取其凭据。文档以 Twilio 为例进行说明 (服务提供商/Twilio)： 创建账户、获取电话号码，并保存 Account SID、Auth Token 和 发送方号码（对于 WhatsApp，请使用你自己已验证的号码加入 Twilio 沙盒——在测试期间，消息只能发送到已验证的沙盒号码）。任何服务提供商都采用相同的基本方式（例如 SendGrid API 密钥、Meta Graph 令牌 + 电话号码 ID 等）——只有字段名称不同。

你应将这些内容设为 App Settings，由每位商家提供自己的凭据；切勿将其硬编码。设置的 FORM 定义（字段架构、密钥的 public:false）位于 salla-app-settings；运行时，这些设置会以 context.settings 的形式传入。

第 4 步 — 构建 App Function

这三个事件是 App Function 触发器——根据可挂钩规则，应将它们实现为 App Function（salla-app-functions），而不是 Webhook： 无需服务器，商家的服务商凭据会通过 context.settings 传入。

在 Portal 函数构建器中，点击 选择操作，然后选择要处理的渠道事件。每个渠道使用 一个函数，或者使用一个根据 context.payload.event 分支处理的主函数。处理程序读取 有效负载和设置、调用服务商，并返回 Resp.success() / Resp.error()：

export default async (context: CommunicationEvent): Promise<Resp> => {
  const { payload, settings } = context;
  const { notifiable, content } = payload.data;

  if (!settings.sms_api_key) {
    return Resp.error()
      .setMessage("Missing provider credentials.")
      .setStatus(422);
  }
  try {
    const res = await fetch(`${settings.sms_base_url}/send`, {
      method: "POST",
      signal: AbortSignal.timeout(10_000),
      headers: {
        Authorization: `Bearer ${settings.sms_api_key}`,
        "Content-Type": "application/json",
      },
      body: JSON.stringify({ to: notifiable[0], text: content }),
    });
    return res.ok ? Resp.success() : Resp.error().setStatus(res.status);
  } catch (err: any) {
    return Resp.error().setMessage("Delivery failed.").setStatus(500);
  }
};

每个事件都会在 context.payload.data 中传递相同的有效负载 （notifiable、type、content、entity、meta），并通过 context.settings 传递凭据。 本地 SMS 和国际 SMS 共用单个 communication.sms.send 事件——如果需要针对特定服务商 进行处理，可根据 notifiable[0] 的号码前缀进行路由。完整事件列表、类型化结构、真实示例 和处理模式： references/communication-events.md。

只有在必须通过自己的基础设施运行这些事件的投递时，才改用 Webhook 订阅 （salla-webhooks）。

此应用会向真实客户发送消息，因此请勿将 content、notifiable 和 settings 中的凭据 写入日志，并在调用服务商端点前进行验证——完整的机密信息和个人身份信息规则见 references/communication-events.md。

验收条件：“每个渠道都由 App Function 处理，该函数从 context.settings 读取凭据并返回 Resp.success() / Resp.error()——没有硬编码密钥，也没有自定义服务器？”

第 5 步 — 测试

分为两个阶段（测试并上线）：

1. 预览面板——在函数编辑器中，点击 选择商店（演示商店），输入预览参数 （通常是一个客户 ID，其电话号码是你已验证的测试号码），然后点击 保存并预览。面板会显示执行状态、返回数据、运行时间、console.log() 输出 和错误跟踪。如果 context.settings 为空，说明你还没有在演示商店填写 App Settings 表单。 通过 salla-app-functions-test 进行预览。
2. 从控制面板进行端到端测试——在演示商店安装应用，将你的应用设为 应用 → 设置 → 自定义下的活动处理程序，然后触发一条真实消息 （例如更改订单状态以触发 communication.*.send），并确认消息通过你的服务商送达。 完整的演示商店测试流程：salla-live-testing。

验收条件：“演示商店发出的真实 communication.*.send 事件已通过你的服务商端到端送达？”

第 6 步 — 上线

通过 salla-app-builder 按标准流程发布。验收条件：第 2 步中的 功能已设置，且发送处理程序已通过上述两个测试阶段。发布前，编辑内容会保留在沙盒中； 发布后，已安装应用的商家会自动收到更新后的函数——无需重新安装。 （测试并上线）

注意事项

容易产生的想法	错误原因
“等代码能正常运行后，再声明支持的功能。”	发布时如果未声明任何渠道，就会失败并返回 403 communication_app_not_have_features — 在发布前（步骤 2），通过 salla_settings action=set_features 声明至少一个渠道。
“短信应用能正常发送后，就可以提交了。”	在账户验证表单上上传 CITC 证书之前，短信应用（sms_local/sms_international）会一直受阻 — 请先确认 requires_citc 为 false（步骤 2）。
“我会搭建一个 Webhook 服务来接收发送事件。”	发送事件是 App Function 触发器 — 请将其实现为 App Function（无需服务；凭据会在 context.settings 中提供）。只有在必须通过自己的基础设施运行发送流程时，才退而使用 Webhook（步骤 4）。
“我会把商家的服务提供商密钥存入自己的数据库。”	服务提供商凭据是针对每个商家的 App Settings，运行时从 context.settings 读取 — 切勿将其硬编码，或存储在 salla_settings 之外（步骤 3）。

资源

主题	链接
概览	https://docs.salla.dev/2006115m0.md
入门指南	https://docs.salla.dev/2006118m0.md
应用渠道配置	https://docs.salla.dev/2081234m0.md
设置服务提供商（Twilio）	https://docs.salla.dev/2081235m0.md
构建 App Function	https://docs.salla.dev/2081248m0.md
测试并上线	https://docs.salla.dev/2081250m0.md
事件与负载参考	https://docs.salla.dev/2006119m0.md
示例	https://docs.salla.dev/2006120m0.md