消息 UI 与体验

本指南面向构建最终用户体验的合作伙伴：说明用户在 MorisBox 应用中看到的内容，以及丰富消息、菜单和多步骤流程应使用哪些 API 和有效载荷。

它不是文档网站的设计系统。

用户看到的内容

在移动端合作伙伴空间 / 客户端应用中：

区域	用途
消息	您的中心列表，包括通知、媒体、新闻简报和流程卡片，最新内容优先
表单	可用的交互式流程
对话	由用户发起的支持会话
机器人	您在应用内提供的机器人

合作伙伴自动发送的内容会进入消息。请勿将活动内容放入支持对话。

构建模块（内容类型）

调用 POST /api/v1/messages，并提供 content_type 及媒体、链接或 HTML 字段。完整参考：媒体与内容类型、消息。

文本

简单通知或说明文字。

{
  "phone": "+228XXXXXXXX",
  "content_type": "text",
  "body": "Votre dossier a été mis à jour.",
  "priority": "notification"
}

**用户 UI：**简单列表行 / 气泡。

图片

{
  "phone": "+228XXXXXXXX",
  "content_type": "image",
  "body": "Photo de l’agence",
  "media_url": "https://cdn.example.com/agence.jpg",
  "media_filename": "agence.jpg"
}

**用户 UI：**图片预览；点击打开完整尺寸。

文档 / 音频 / 视频

{
  "content_type": "document",
  "body": "Guide d’affiliation",
  "media_url": "https://cdn.example.com/guide.pdf",
  "media_filename": "guide.pdf"
}

类型	用户 UI
`document`	文件行（名称、类型和打开操作）
`audio`	音频行；打开 / 播放
`video`	视频卡片；打开

CTA 链接

包含标题、说明、按钮和可选图片的丰富卡片。

{
  "content_type": "link",
  "body": "Consultez votre espace assuré.",
  "link_url": "https://morisbox.com",
  "link_title": "Espace assuré SEED",
  "link_description": "Cotisations, demandes et documents.",
  "link_label": "Ouvrir le portail",
  "link_image_url": "https://cdn.example.com/cover.jpg"
}

**用户 UI：**卡片和主按钮；打开 URL。

HTML 新闻简报

包含丰富图片、视频和 HTML 布局的内容。用户点击中心列表行后，它会直接全屏打开，不会先显示微型预览。

{
  "content_type": "html",
  "subject": "SEED Actu · Juillet",
  "html": "<div><h1>Bonjour</h1><img src=\"https://…/photo.jpg\" style=\"max-width:100%\"/><p>…</p></div>"
}

**用户 UI：**列表标题 = subject；点击 → 完整 HTML 阅读器。
详情：HTML 新闻简报。

流程邀请

用于注册、候补名单等场景的交互式多屏表单。

POST /api/v1/bots/{bot_code}/flows/{flow_code}/invite

{ "phone": "+228XXXXXXXX" }

用户 UI：流程卡片；打开表单运行器；完成后，同一张卡片会变成只读摘要。
详情：交互式流程。

机器人对话 UI（菜单和步骤）

用户运行机器人会话时，运行时可显示：

事件 / 步骤类型	用户体验
`message` / `flow_message`	流程 / 机器人 UI 中的文本
`menu`（按钮）	垂直选项列表
`menu`（列表）	分组列表（WhatsApp 列表风格）
`flow_screen` + `form`	多字段表单（输入、选择、手机、电子邮箱等）
`flow_screen` + `input` / `select`	单个字段或选项
`payment`	付款确认（模拟 / 未来功能）
`flow_completed`	完成状态和可选摘要

表单字段类型（流程页面）

在表单步骤的 fields_json 中定义：

`type`	控件
`text`	文本输入
`phone`	手机号码（E.164 验证）
`email`	电子邮箱地址（已验证）
`number`	数值输入
`date`	`YYYY-MM-DD` 日期
`boolean`	是 / 否
`select`	选项列表（`options: [{id, label}]`）

服务器端验证：字段验证。

表单步骤定义示例

[
  {
    "key": "full_name",
    "type": "text",
    "label": "Nom complet",
    "required": true,
    "placeholder": "Ex. Ama Koffi"
  },
  {
    "key": "email",
    "type": "email",
    "label": "E-mail",
    "required": false
  },
  {
    "key": "service",
    "type": "select",
    "label": "Service",
    "required": true,
    "options": [
      { "id": "affiliation", "label": "Affiliation" },
      { "id": "pension", "label": "Pension" }
    ]
  }
]

选择合适的构建模块

目标	使用方式
一次性提醒	`text` 或模板
显示照片 / PDF	`image` / `document`
将用户引导至您的门户	CTA `link`
丰富的月度电子邮件式内容	`html` 新闻简报
多步骤注册 / 候补名单	流程邀请和表单步骤
引导式服务菜单	机器人菜单（`local` 或 `service`）
持续支持聊天	由用户发起的对话（客服人员回复）

分隔符与丰富内容结构

在 HTML 新闻简报中，可以通过以下方式组织内容：

使用标题（h1 至 h3）划分章节
使用水平线（<hr>）或带间距的区块进行视觉分隔
使用带边框的 div 卡片呈现 CTA
使用列表（ul / ol）提供便于浏览的要点

在流程中，为获得更好的移动端体验，应尽可能使用独立的步骤（页面），而不是一个很长的表单。

端到端模式

1. 活动：图片和链接

发送带说明文字的 image
发送 CTA link，引导用户“完成我的申请”

2. 入驻候补名单

POST …/flows/waitlist/invite
用户填写身份和偏好表单
卡片变为 completed 并显示摘要

3. 包含媒体的新闻简报

使用 <img> 和 <video> 构建 HTML
设置 content_type=html 和 subject
用户从中心打开完整阅读器

主题	页面
发送消息	消息
媒体类型	媒体与内容类型
新闻简报	HTML 新闻简报
流程	交互式流程
机器人	360Bots
机器人身份验证	机器人凭证与 Webhook
验证	字段验证