Blocks

Blocks define the structured responses Convosite can return to your application.

A Block describes what data is available, not how that data should look. Your application owns the component, markup, styling, interactions and responsive behaviour used to render it.

For example, a hero Block might define a title, body and image. Convosite can choose that Block and generate values for those fields, while your application decides whether the result is a full-width banner, a card, a modal or something else entirely.

A simple Block

{
  "key": "hero",
  "name": "Hero",
  "description": "A prominent introduction with supporting content and an image.",
  "props": [
    {
      "key": "title",
      "label": "Title",
      "type": "text",
      "required": true
    },
    {
      "key": "body",
      "label": "Body",
      "type": "textarea",
      "required": false
    },
    {
      "key": "image",
      "label": "Image",
      "type": "media",
      "required": true
    }
  ]
}

The important parts are:

• key uniquely identifies the Block in your project.
• name is its human-readable name.
• description explains when the Block is useful.
• props defines the structured data the Block can contain.

TIP

Write Block descriptions for meaning rather than appearance. A description such as “A prominent introduction to a topic” gives Convosite more useful context than “A component with a large heading and two columns”.

Blocks and your UI

A Block definition does not create a frontend component for you. A common pattern is to map each Block key to a component in your application:

const blocks = {
  hero: HeroBlock,
  text: TextBlock,
  product: ProductBlock
}

When Convosite returns a Block, use its key to choose the component and pass the generated content into it.

This separation is intentional:

Convosite decides what structured response to return. Your application decides what that response looks and feels like.

Source control

Block definitions live in your project and should normally be committed to source control alongside the components that render them.

Use the Convosite CLI to create, validate, push and pull definitions. This keeps the developer-owned structure of the experience in code while content such as Knowledge and Media remains manageable through Convosite.

Next steps

Start with Creating Blocks to add your own Block. Then read Fields, Validation and Media for the available schema options.