Update to Speak AI

{
  "description": "Run async voice and video surveys in Speak AI end to end. Use this when someone asks to collect recorded answers from customers, candidates, or users without booking calls, to set up a survey or recorder, to write or change its questions, to brand it, to get a shareable link to send out, to check whether it is still accepting submissions, to list what has come back, or to analyze the responses as a set. Covers create_recorder, update_recorder_questions, update_recorder_settings, generate_recorder_url, check_recorder_status, get_recorder_recordings, list_recorders, get_recorder_info, clone_recorder and delete_recorder, then hands off to the transcript and insight tools once responses arrive.",
  "included_files": [
    {
      "relative_path": "agents/openai.yaml",
      "size_in_bytes": 289
    }
  ],
  "name": "surveys-and-recorders",
  "skill_md_contents": "---\nname: surveys-and-recorders\ndescription: Run async voice and video surveys in Speak AI end to end. Use this when someone asks to collect recorded answers from customers, candidates, or users without booking calls, to set up a survey or recorder, to write or change its questions, to brand it, to get a shareable link to send out, to check whether it is still accepting submissions, to list what has come back, or to analyze the responses as a set. Covers create_recorder, update_recorder_questions, update_recorder_settings, generate_recorder_url, check_recorder_status, get_recorder_recordings, list_recorders, get_recorder_info, clone_recorder and delete_recorder, then hands off to the transcript and insight tools once responses arrive.\nmetadata:\n  server-version: \"1.41.1\"\n  categories: \"recorders-surveys, media, magic-prompt\"\n---\n\n# Surveys and recorders\n\nThe user's explicit instructions take priority over this skill. When they ask for something different from the steps below, do what they asked, and confirm with them before any action that deletes, overwrites, or sends data outside Speak AI.\n\nA recorder is a public page that collects audio or video answers. You send a link, people\nrecord replies on their own time, and each submission lands in the workspace as normal\nmedia with a transcript and insights. It replaces booking a call for every participant.\n\nUse this for customer research, candidate screening, onboarding feedback, testimonials, or\nany question you would otherwise ask on a call.\n\n## Step 1: Create the recorder\n\n`create_recorder` needs only `name`. Everything else is optional, so create it first and\nconfigure it in the next steps rather than trying to pass everything at once.\n\nUseful optional arguments:\n\n- `description`, shown to the respondent.\n- `folderId`, so submissions land somewhere findable instead of the workspace root.\n- `isAutoAnalyze`, so each submission is transcribed and analyzed on arrival. Set this\n  unless the user wants to review raw recordings first.\n- `sourceLanguage`, a transcription language code such as `en-US`.\n- `notifyUsers`, an array of user IDs to alert on each new submission. Get IDs from\n  `list_users`.\n\nKeep the returned `recorderId`. Every later step except the status check uses it.\n\n## Step 2: Write the questions\n\n`update_recorder_questions` takes `recorderId`, optional `name` and `email` booleans for\nwhether to collect respondent details, and a `questions` array.\n\n**The answer types are a fixed set, and there is no free-text, rating, or number type:**\n\n`single`, `multiple`, `checkbox`, `radiobutton`, `dropdownlist`, `date`, `time`, `datetime`\n\nThat surprises people, so do not offer the user a rating scale or a short-answer box and\nthen fail. The recorded answer *is* the free text. The typed question is for structured\ndetail alongside the recording, so a satisfaction score belongs in a `radiobutton` or\n`dropdownlist` with the options spelled out.\n\nAsk fewer questions than feels natural. Every extra question lowers completion, and the\nrecording already carries the depth.\n\n## Step 3: Brand and configure it\n\n`update_recorder_settings` takes `recorderId` and the presentation and behaviour options:\nbranding, captions, duration limits as `{ minDuration, maxDuration }` in seconds, and\nnotification toggles.\n\nSet a `maxDuration`. Without one, a rambling answer becomes an expensive transcript and a\nworse dataset. Two to three minutes suits most questions.\n\n## Step 4: Get the link and share it\n\n`generate_recorder_url` takes `recorderId` and returns a public URL. Anyone with the link\ncan submit, so treat it as public.\n\nConfirm with the user before sending it anywhere on their behalf.\n\n## Step 5: Check it is accepting submissions\n\n`check_recorder_status` **takes `token`, not `recorderId`.** This is the one call in the\nworkflow keyed on something else, and passing the recorder id fails. The token comes from\n`get_recorder_info` or the recorder record.\n\nUse it when a user says responses are not arriving, before assuming nobody replied.\n\n## Step 6: Collect the responses\n\n`get_recorder_recordings` takes `recorderId` and lists submissions. Each one is media, so\nfrom here the normal tools apply:\n\n- `get_media_status` to confirm a submission finished processing. States run `queued`,\n  `preparing`, `processing`, `preparingAnalysis`, then `processed` or `failed`. Insights\n  are empty before `processed`.\n- `get_transcript` for what the person actually said.\n- `get_media_insights` for topics, sentiment, keywords, and action items.\n\nDo not report on a set while some of it is still processing. Say how many are ready.\n\n## Step 7: Analyze the set, not one reply at a time\n\nOnce several responses are in, the question is what they say collectively.\n\nRead the responses and do the analysis yourself. `list_media` with the `folderId` that\nholds the submissions and `include: [\"transcription\"]` returns their transcripts in one\ncall; page through if there are more than one page. Cite the respondent for each claim so\nit traces back to a reply. When you need to count how many people said a thing, go through\nthe responses one at a time and tally them, rather than writing a blended summary.\n\nFor themes, quotes, and comparisons across a larger set, use the `research-analysis` skill.\nIt covers scoping, citation, and pulling verbatim quotes properly.\n\n## Managing recorders\n\n- `list_recorders` takes optional `page`, `pageSize` up to 500, and `sortBy` such as\n  `createdAt:desc`. Use it to find an existing recorder before creating a duplicate.\n- `get_recorder_info` takes `recorderId` and returns the full configuration, including the\n  token the status check needs.\n- `clone_recorder` takes `recorderId` and optional `name`, `description`, and `folderId`.\n  Use it to run the same study with a new cohort rather than rebuilding the questions.\n- `delete_recorder` is permanent. Confirm with the user first, and check\n  `get_recorder_recordings` for submissions that would be orphaned.\n\n## What goes wrong\n\n- **Offering a question type that does not exist.** Rating and short-answer are not\n  options. Map them to a choice type or leave it to the recording.\n- **Passing `recorderId` to `check_recorder_status`.** It takes `token`.\n- **Reading insights too early.** A submission has no transcript until it reaches\n  `processed`.\n- **Sharing the link without asking.** It is public and unauthenticated.\n- **Deleting a recorder to \"clean up\".** Confirm first, it takes the configuration with it.\n\n## Confirm before running\n\n- `delete_recorder`, which is permanent.\n- `generate_recorder_url` when you are about to distribute the link rather than show it.\n- `update_recorder_questions` on a recorder that already has submissions, since it changes\n  what later answers mean relative to earlier ones.\n\n## Tools this skill uses\n\nRecorders: `create_recorder`, `list_recorders`, `get_recorder_info`, `clone_recorder`,\n`get_recorder_recordings`, `generate_recorder_url`, `update_recorder_settings`,\n`update_recorder_questions`, `check_recorder_status`, `delete_recorder`.\n\nFollow-on: `get_media_status`, `get_transcript`, `get_media_insights`, `list_media`,\n`list_users`.\n\nPer-tool documentation: `https://docs.speakai.co/mcp/tools/recorders-surveys/<tool_name>/`\n"
}