Campaign YAML

Instead of stitching together API calls, you can describe a campaign declaratively in a YAML file and create it with ontora campaigns create -c campaign.yaml.

Example

name: Q2 facility-ops interviews
goal: Map current scheduling workflows and identify automation opportunities
description: |
  Talk to facility managers and shift leads about how they assign daily work.
channel: in_app_chat          # or: slack, teams
duration_minutes: 30
default_language: en          # participant-facing language; omit for workspace default

# Scheduling (optional): a future timeframe_start holds the invitations until
# the campaign opens — date-only values send at 08:00 in `timezone`.
timeframe_start: "2026-08-03"
timeframe_end: "2026-08-14"   # soft response deadline shown to participants
timezone: "Europe/Berlin"     # required when timeframe_start is set

participant_review_enabled: false
result_summary_enabled: false

interview_context_for_employee: |
  We're trying to understand how scheduling actually happens day-to-day —
  not the official process, but the real one.

topics:
  - name: Daily scheduling
    goal: Understand how shifts are assigned each morning
    priority: required
    success_threshold: "Can describe the assignment process end-to-end with the friction points"
    sub_topics:
      - Who decides assignments
      - What inputs they use
      - Where the friction is
    questions:
      - text: "Walk me through how this morning's shift assignment happened."
        required: true
      - text: "What's the worst that's happened when scheduling went wrong?"
      - text: "Rank these steps by how much time they cost you."
        type: ranking
        component_config:
          items:
            - { id: intake, label: "Intake" }
            - { id: approval, label: "Approval" }
            - { id: handoff, label: "Hand-off" }

  - name: Tooling
    goal: Identify what tools facility managers actually use
    priority: important

contacts:
  - { name: Sam Rivera,    email: sam@example.com,    department: Operations }
  - { name: Jess Thompson, email: jess@example.com,   department: Operations, seniority_level: 4 }

Then:

ontora campaigns create -c campaign.yaml           # creates in draft
ontora campaigns create -c campaign.yaml --start   # creates and launches

With a future timeframe_start, --start activates the campaign but holds the invitations until the start date (08:00 in the campaign’s timezone). Without one, invitations go out immediately on launch. The CLI prints the campaign id (--json emits the full created campaign for scripting); if you skipped --start, launch with ontora campaigns start <id> when you’re ready. For larger contact lists, leave contacts out of the YAML and import them after creation:

ontora contacts import <id> contacts.csv

Field reference

Top-level

Field	Required	Description
`name`	yes	Display name
`goal`	yes	Research goal — drives agent behavior (min. 20 characters to launch)
`description`	no	Internal context
`channel`	no	`in_app_chat` (default — email invitation with a personal interview link), `slack` (Slack DM), `teams` (Microsoft Teams chat). Slack/Teams need the workspace integration connected
`duration_minutes`	no	Target conversation length (default 30)
`completion_threshold`	no	Percent of contacts that must complete before synthesis (integer, default 90 — earlier CLI versions defaulted to 80)
`default_language`	no	Participant-facing language: `en`, `de`, `fr`, `es`, `it`, `pt`, `ro`, `ru`, `uk`, `he`. Omit to inherit the workspace default
`timeframe_start`	no	ISO date or datetime. A future value schedules the invitation send instead of sending at launch (email/Slack; Teams always sends at launch)
`timeframe_end`	no	Soft response deadline shown to participants — late responses still count
`timezone`	no*	IANA name (e.g. `Europe/Berlin`). *Required when `timeframe_start` is set
`start_immediately`	no	Defaults to `false` when a future `timeframe_start` is given, else `true`
`participant_review_enabled`	no	Participants review + submit their answers after the conversation
`result_summary_enabled`	no	Offer participants the result summary (requires review)
`is_anonymous` / `anonymity_level`	no	Redaction: `none`, `name_hidden`, `transcript_hidden`, `audio_disabled`, combinations, `report_only`
`interview_context_for_employee`	no	Shown to participants before the conversation
`agent_behavior`	no	Style guidance for the interview agent
`invitation_email_message`	no	Custom text in the invitation email
`teams_invitation_message`	no	Custom Teams chat invitation (placeholders `{name}`, `{title}`, `{workspace}`, `{duration}`); interview links are appended automatically
`welcome_screen` / `closing_message`	no	Copy overrides for session start/end
`topics`	yes	Array — see below
`contacts`	no	Array — see below

Topic

Field	Required	Description
`name`	yes	Topic title
`goal`	no	What we want to learn
`priority`	no	`required \| important \| optional` (default `required`)
`success_threshold`	no	Free-text description of when the topic counts as sufficiently covered
`sub_topics`	no	Array of strings
`questions`	no	Array of question objects (the agent improvises follow-ups)

Question

Field	Required	Description
`text`	yes	The question
`required`	no	Must be covered before the interview can end (default `false`)
`type`	no	`open_ended` (default), `single_choice`, `multiple_choice`, `likert_scale`, `ranking`, `statement`, `range_slider`, `matrix`
`options`	no	Choice labels for choice/likert types
`component_config`	no	Required for `ranking` (`{items: [{id, label}]}`), `matrix` (`{rows: [{id, label}], columns: [{id, label}]}`), `range_slider` (`{min, max, step}`)

Contact

- name: Sam Rivera
  email: sam@example.com
  department: Operations
  job_title: Shift Lead
  seniority_level: 4        # 1 (IC) … 6 (C-level)
  slack_user_id: U0123ABC   # for Slack campaigns
  is_required: false

Email is required for invitations on in_app_chat; Slack campaigns need slack_user_id or email per contact. For bulk lists, prefer ontora contacts import <id> contacts.csv after creating the campaign — see Commands. CSV columns: name,email,phone,job_title,department,seniority_level. Only name is required.

Get started

Core concepts

Guides

MCP server

CLI

Webhooks

Example

Field reference

Top-level

Topic

Question

Contact

​Example

​Field reference

​Top-level

​Topic

​Question

​Contact

Example

Field reference

Top-level

Topic

Question

Contact