Message UI and Experiences

This guide is for partners building end-user experiences: what users see in the MorisBox app, and which APIs and payloads to use for rich messages, menus, and multi-step flows.

It is not a design system for the documentation site.

What users see

In the mobile partner space / Client Application:

Area	Purpose
Messages	Your hub list - notifications, media, newsletters, and flow cards, newest first
Forms	Available interactive flows
Conversations	Support threads opened by the user
Bots	Your bots available in-app

Automated partner sends go to Messages. Do not place campaign content in support conversations.

Building blocks (content types)

Use POST /api/v1/messages with content_type and the media, link, or HTML fields. Complete reference: Media and Content Types, Messages.

Text

A simple notification or caption.

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

User UI: simple list row / bubble.

Image

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

User UI: image preview; tap to open full size.

Document / audio / video

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

Type	User UI
`document`	File row (name, type, and open action)
`audio`	Audio row; open / play
`video`	Video card; open

CTA link

A rich card with a title, description, button, and optional image.

{
  "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"
}

User UI: card and primary button; opens the URL.

HTML newsletter

A rich image, video, and HTML layout. It opens full-screen when the user taps the hub row, without showing a miniature preview first.

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

User UI: list title = subject; tap → complete HTML reader.
Details: HTML Newsletters.

Flow invitation

An interactive multi-screen form for registration, waiting lists, and more.

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

{ "phone": "+228XXXXXXXX" }

User UI: flow card; opens the form runner; after completion, the same card becomes a read-only summary.
Details: Interactive Flows.

Bot conversation UI (menus and steps)

When a user runs a bot session, the runtime can present:

Event / step type	User experience
`message` / `flow_message`	Text in the flow / bot UI
`menu` (button)	Vertical choice list
`menu` (list)	Sectioned list (WhatsApp-list style)
`flow_screen` + `form`	Multi-field form (inputs, select, phone, email, and more)
`flow_screen` + `input` / `select`	Single field or options
`payment`	Payment confirmation (stub / future)
`flow_completed`	Completion and optional summary

Form field types (flow screens)

Define these in a form step's fields_json:

`type`	Control
`text`	Text input
`phone`	Phone number (E.164 validation)
`email`	Email address (validated)
`number`	Numeric input
`date`	`YYYY-MM-DD` date
`boolean`	Yes / No
`select`	Option list (`options: [{id, label}]`)

Server-side validation: Field Validation.

Form-step definition example

[
  {
    "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" }
    ]
  }
]

Choose the right building block

Goal	Use
One-time alert	`text` or a template
Display a photo / PDF	`image` / `document`
Direct users to your portal	CTA `link`
Rich monthly email-style content	`html` newsletter
Multi-step registration / waiting list	Flow invitation and form steps
Guided service menu	Bot menus (`local` or `service`)
Ongoing support chat	Conversation started by the user (agent replies)

Separators and rich-content structure

In HTML newsletters, structure content with:

Headings (h1–h3) for sections
Horizontal rules (<hr>) or spaced blocks for visual separation
Bordered div cards for CTAs
Lists (ul / ol) for scannable points

In flows, prefer separate steps (screens) over one long form when possible for a better mobile experience.

End-to-end patterns

1. Campaign: image and link

Send an image with a caption
Send a CTA link to “Complete my request”

2. Onboarding waiting list

POST …/flows/waitlist/invite
User completes identity and preference forms
Card changes to completed with a summary

3. Newsletter with media

Build HTML with <img> and <video>
Set content_type=html and subject
User opens the complete reader from the hub

Topic	Page
Send messages	Messages
Media types	Media and Content Types
Newsletters	HTML Newsletters
Flows	Interactive Flows
Bots	360Bots
Bot authentication	Bot Credentials and Webhooks
Validation	Field Validation