编写指令与发送

在消息中编写指令，通过测试发送确认值后再保存。

指令分为调用 API 的行和使用响应的行。

• 路径和查询字符串中可以使用 {{ userId }}、{{ tags.* }} 等个性化变量。域名部分不能使用。
• 像电子邮件地址这样可能包含 @、+、& 的值，请用 url_encode 包起来。否则值在传递时可能会被破坏。

{% connected_content https://api.example.com/coupon?uid={{ userId }} %}
{% connected_content https://api.example.com/member?email={{ email | url_encode }} :save member %}

域名中包含变量时无法保存。

{% connected_content https://{{ tags.domain }}/coupon %}

POST 示例

收件人的值会填入 :body 中 {{ userId }} 的位置。如果收件人的 userId 是 abc123，就会发送 uid=abc123。

{% connected_content https://api.example.com/recommend :method post :body uid={{ userId | url_encode }} :save rec %}
推荐商品：{{ rec.product_name }}

以 JSON 格式发送时，body 也请按 键=值 的格式填写，并用 url_encode 包住值。FlareLane 会将其转换为 JSON 后发送，即使值中含有引号等特殊字符也不会被破坏。选项较多时，可以分行填写。

即使姓名是 金 "Flare" Lane，也会正确发送为 {"uid": "…", "name": "金 \"Flare\" Lane"}。

{% connected_content https://api.example.com/recommend
     :method post
     :content_type application/json
     :body uid={{ userId | url_encode }}&name={{ name | url_encode }}
     :save rec %}

如果直接写 JSON，值中含有引号的收件人的 body 会被破坏，API 会返回 400 错误，值以空白发送。

{% connected_content https://api.example.com/recommend
     :method post
     :content_type application/json
     :body {"name": "{{ name }}"}
     :save rec %}

• 将在使用准备步骤中复制好的认证信息附加在地址后面。
• 一个指令中不能同时使用 Basic 和 Token。

响应是 JSON 还是纯文本，由 API 的 Content-Type 响应头决定。请对照开发团队提供的响应示例确认。两种格式的读取方式不同。

用 :save 指定名称，然后在名称后加点（.）读取字段。同一个值可以在多处使用，之后要增加读取的值也很方便。

{% connected_content https://api.example.com/points?uid={{ userId }} :save point %}
您有 {{ point.amount }} 积分即将过期，请在 {{ point.expires_at }} 前使用。

请直接在值要出现的位置写指令。下面的示例通过公开的天气服务填入用户所在城市的当前气温。

今天 {{ tags.city }} 的气温是 {% connected_content https://wttr.in/{{ tags.city }}?format=%t %}，出门前请注意穿着！

调用失败时，值的位置会留空。建议从以下三种方式中选择一种提前写好。

如果只想在有值时显示，或者不发送，可以用条件语句判断调用是否失败。判断方法有两种。

条件语句中也请用字段而不是名称来判断。只写名称会导致消息无法保存。

{% if point == blank %}{% abort_message %}{% endif %}

再次调用同一地址时，不会每次都调用 API，而是在一定时间内复用之前收到的响应。大多数情况下保持默认行为即可，只在需要更改时填写选项。

• 例如：只包含 tags.city 的天气调用会在同一城市之间复用响应，即使收件人很多，也只按城市数量调用。
• 同时处理的收件人较多时，即使是同一地址也可能被调用多次。缓存只是减少调用次数，并不保证只调用一次。

:cache_max_age 可设置的范围请查看限额汇总。

• 建议在发送前通过测试发送确认最终消息。
• 测试发送与实际发送相同。
  • 会实际调用您的 API。
  • 同样会进行第 5 步的自动检查。
  • 如果指定的号码或电子邮件没有关联的用户，{{ userId }} 等用户信息可能为空。

• 在即时发送，以及保存定时发送、周期性发送、旅程自动化、电子邮件模板时，系统会自动检查指令。不符合编写规则时，无法保存或发送。
• 编写规则请查看保存被拒绝的情况。