Manifest

The manifest is one JSON document that describes a version of your app. You edit it on the app's Manifest tab. Parsing is strict, so an unknown or misspelled field is an error rather than something silently ignored.

A manifest may be up to 65536 bytes. It must declare a webhook, a web page, or both. Saving stores it as the draft; publishing makes it the version users get, and a published version never changes.

Top-level fields

Scopes

Users see each scope's description and must accept all of them to install the app. Ask only for what you use.

Every call carries user.id, the per-app id, whatever the scopes.

When a new version asks for a scope, your app gets that data from each user only after they accept it; until then they keep using the app without it. A scope you drop in a new version stops at once. You get your own data for every declared scope while testing, but testers must install the app before it receives theirs.

Commands

{ "id": "lunch.start", "command": "/lunch", "title": "Start a lunch order", "description": "Pick a restaurant and a time", "roomTypes": ["PRIVATE_GROUP", "PUBLIC_GROUP"], "flow": "start" }

Flows and views

A flow is the form behind a command or a card button. Flow ids use lower-case letters, digits, dashes and underscores, up to 32 characters.

• "mode": "submit" (the default): the phone walks the user through every view and sends all answers in one call. Forms with two or more views end with a review page.
• "mode": "dynamic": the phone sends each view's answers as it is completed, and your webhook decides what comes next. See Multi-step forms.
• A flow with no views runs at once, without a form. If the app has the location.coarse scope, the phone first shows only the "include my location" switch.

A flow has up to 10 views. A view is:

Blocks

• {"type": "text", "text": "..."}: instructions, up to 1000 characters. **bold** and *italic* are the only formatting.
• {"type": "divider"}: a separator line.
• {"type": "input", ...}: a question, described below.

Inputs

Every input has these fields. Only the fields that apply to its kind are accepted.

{ "type": "input", "id": "email", "label": "Email", "input": "text", "required": true,
  "maxLength": 120, "pattern": "[^@\\s]+@[^@\\s]+", "placeholder": "you@example.com" }

{ "type": "input", "id": "toppings", "label": "Toppings", "input": "multiselect", "style": "chips",
  "minSelected": 1, "maxSelected": 3,
  "options": [ { "value": "cheese" }, { "value": "olives" }, { "value": "basil" } ] }

{ "type": "input", "id": "when", "label": "When", "input": "datetime", "min": "2026-01-01T00:00" }

The phone checks answers as the user types, and the platform checks them again before calling your webhook. A value that breaks a rule, a missing required answer, or a key that is not an input of the flow is refused with an error to the user, and your webhook is not called.

A larger example

A lunch order started with /lunch. Its card, from the order_open template, lets everyone in the room add a dish through a second flow, and lets the organiser close the order. The open_flow payload pre-fills the order input of that flow.

{
  "contract": 1,
  "name": "Team Lunch",
  "description": "Collect a lunch order from the whole room.",
  "scopes": ["profile.name", "conversation.ref", "post.cards"],
  "allowedLinkHosts": ["lunch.example.com"],
  "allowedImageHosts": ["cdn.lunch.example.com"],
  "webhook": { "url": "https://lunch.example.com/banga/hook" },
  "commands": [
    { "id": "lunch.start", "command": "/lunch", "title": "Start a lunch order",
      "description": "Pick a restaurant and a time", "roomTypes": ["PRIVATE_GROUP", "PUBLIC_GROUP"], "flow": "start" }
  ],
  "flows": {
    "start": {
      "mode": "submit",
      "views": [
        { "id": "where", "title": "Where from?", "blocks": [
          { "type": "input", "id": "restaurant", "label": "Restaurant", "input": "select", "required": true,
            "options": [ { "value": "bkk", "label": "Bangkok Kitchen" }, { "value": "sal", "label": "Green Salads" } ] },
          { "type": "input", "id": "time", "label": "Delivery time", "input": "time", "required": true,
            "min": "11:30", "max": "14:00" }
        ] }
      ]
    },
    "add": {
      "mode": "submit",
      "views": [
        { "id": "dish", "title": "Your dish", "submitLabel": "Add", "blocks": [
          { "type": "text", "text": "Add your dish to the order. **One dish** per entry." },
          { "type": "input", "id": "order", "label": "Order number", "input": "text", "required": true, "maxLength": 12 },
          { "type": "input", "id": "dish", "label": "Dish", "input": "text", "required": true, "maxLength": 60 },
          { "type": "input", "id": "qty", "label": "Quantity", "input": "number", "min": 1, "max": 20, "default": 1 },
          { "type": "input", "id": "spicy", "label": "Spicy", "input": "toggle" }
        ] }
      ]
    }
  },
  "cards": {
    "order_open": {
      "blocks": [
        { "type": "title", "text": "Lunch from {{restaurant}}" },
        { "type": "facts", "items": [ { "k": "Delivery", "v": "{{time}}" }, { "k": "Orders so far", "v": "{{count}}" } ] },
        { "type": "status", "text": "Open", "tone": "ok" }
      ],
      "actions": [
        { "type": "open_flow", "label": "Add my dish", "style": "primary", "flowId": "add",
          "payload": { "order": "{{order}}" } },
        { "type": "submit", "label": "Close order", "actionId": "close", "payload": { "order": "{{order}}" } },
        { "type": "open_url", "label": "Menu", "url": "https://lunch.example.com/menu" }
      ]
    }
  }
}