Markdown Workflows Recipe

Creating and managing surveys using markdown syntax with Sibilance.

Overview

Sibilance surveys can be defined using markdown syntax with Mermaid diagrams for visual workflow representation.

Basic Markdown Survey

Simple Survey

# Customer Feedback Survey

## Start
Welcome! We'd like to get your feedback on your recent experience.

## Contact
What's your name?

## Email
What's your email address?

## Rating
On a scale of 1-10, how would you rate your experience?

## Feedback
Any additional comments or feedback?

## End
Thank you for your feedback!

Mermaid Diagrams

Flowchart Syntax

# Survey Title

\`\`\`mermaid
graph LR
  Start[Start] --> Contact[Contact]
  Contact --> Email[Email]
  Email --> Rating[Rating]
  Rating --> Feedback[Feedback]
  Feedback --> End[End]
\`\`\`

## Start
Welcome!

## Contact
What's your name?

## Email
What's your email?

## Rating
Rate your experience 1-10.

## Feedback
Any comments?

## End
Thank you!

Branching Logic

# Project Survey

\`\`\`mermaid
graph TD
  Start[Start] --> ProjectType[Project Type]
  ProjectType -->|Residential| Residential[Residential Details]
  ProjectType -->|Commercial| Commercial[Commercial Details]
  Residential --> End[End]
  Commercial --> End
\`\`\`

## Start
Welcome! What type of project are you interested in?

## Project Type
Is this a residential or commercial project?

## Residential
Tell me about your residential project.

## Commercial
Tell me about your commercial project.

## End
Thank you for your information!

Survey Steps

Step Definition

Each step is defined with a ## heading:

## StepName
This is the script that the AI will say to the user.

Step Scripts

## Introduction
Hello! Welcome to our survey. We'll ask you a few questions about your experience.

## Question1
What's your name?

## Question2
How would you rate your experience on a scale of 1-10?

## Conclusion
Thank you for participating in our survey!

Transitions

Simple Transitions

Transitions are defined in the Mermaid diagram:

\`\`\`mermaid
graph LR
  Start --> Question1
  Question1 --> Question2
  Question2 --> End
\`\`\`

Conditional Transitions

\`\`\`mermaid
graph TD
  Start --> Rating
  Rating -->|High| ThankYou
  Rating -->|Low| FollowUp
  ThankYou --> End
  FollowUp --> End
\`\`\`

## Rating
How would you rate your experience?

## ThankYou
Great! We're glad you had a good experience.

## FollowUp
We're sorry to hear that. Can you tell us more?

## End
Thank you!

Using Markdown Surveys

Direct Survey Config

const client = new SibilanceClient({
  survey: {
    markdown: `
      # My Survey
      ## Start
      Welcome!
      ## End
      Thank you!
    `,
    surveyName: 'My Survey'
  }
});

Fetch from Backend

// Fetch survey markdown from your backend
const response = await fetch('/api/survey-markdown');
const markdown = await response.text();

const client = new SibilanceClient({
  survey: {
    markdown,
    surveyName: 'Fetched Survey'
  }
});

Best Practices

1. Clear Step Names - Use descriptive step names
2. Natural Scripts - Write scripts that sound natural when spoken
3. Logical Flow - Ensure transitions make sense
4. Test Thoroughly - Test surveys before deploying
5. Keep It Simple - Start simple, add complexity as needed

Related

• Survey Builder - Visual survey builder
• Survey Integration - Integration patterns
• Sibilance Client - Core client API