# Parlo > Group chats, run by an agent. A person describes what they want to learn from a group; Parlo makes a link; everyone who opens it answers by voice; a persistent agent gathers the answers, writes the report the group gets back, and proposes follow-up rounds. If you are an AI agent acting for a person, do not drive the web interface at parlo.me: creating a parlo there needs a microphone and an SMS code. Use the HTTP API or the MCP server below. The fastest path is one request. ## Create a parlo in one request POST https://api.parlo.me/api/agent/parlos Content-Type: application/json {"brief": "", "opener_audio_url": "", "title": ""} At least one of brief / opener_audio_url. No authentication is needed for the first call. Answer (201): {"parloId", "code", "title", "shareLink": "post this into the group chat; the parlo is live", "whatsappShareLink":"a wa.me link with a short invitation and shareLink", "dashboardLink": "answers and the agent's report", "claimLink": "send this to the person you act for; one tap (and a phone code the first time) makes the parlo theirs. null when the call was authenticated", "openerLink": "WhatsApp link to Parlo's number; the person taps it and sends the opener as a voice note (see below)", "answerLink": "WhatsApp link to Parlo's number with 'answer ' prefilled: Parlo asks the questions in the chat and takes voice notes; post it into a WhatsApp group instead of (or next to) shareLink", "apiKey": "send it as the X-Parlo-Api-Key header on later calls so new parlos belong to the same person and GET /api/my/surveys lists them", "questions": [{"text", "hint", "type": "voice|photo|video"}], "briefSource": "brief | opener_transcript | fallback", "opener": {"durationMs", "transcript"} or null, "openerRequest": {"why", "link", "askThePerson", "alternatively"} when no opener was given, else null, "next": ["1. post shareLink", "2. send the person openerLink (the words are included)", "3. send claimLink", "4. keep apiKey"]} Errors are JSON `{error}`: 400 (nothing to build from, or a bad URL), 413 (audio over 12 MB), 415 (the URL was not audio), 429 (30 creations per hour per IP), 502 (the audio URL could not be fetched). Round 1 is written by a model from the brief, so the call takes a few seconds. Example: curl -X POST https://api.parlo.me/api/agent/parlos \ -H 'content-type: application/json' \ -d '{"brief":"I run a small climbing club. I want to hear from everyone who came this season: what made them come back, what nearly made them stop, what they want next year. I will use it to plan the winter programme."}' ## The voice note (send the link) The opener is the voice note the group hears before they answer: the person, in their own voice, saying why they are asking. It is the difference between a group chat answering and a link being ignored. - The create answer carries `openerLink`: a `https://wa.me/...` link into a chat with Parlo's own WhatsApp number, with "opener " prefilled. Send it to the person together with the share link. They tap it, press send, and reply with a voice note of 30 to 60 seconds (who they are, what they want to hear from the group, what they will do with it). Parlo stores it as the opener, transcribes it, and because the number is theirs, makes the parlo theirs: no claim link needed after that. - You do not need the audio file. If you do hold one as a URL, `opener_audio_url` on create, or `POST https://api.parlo.me/api/surveys/{parloId}/intro/from-url` with the API key and `{"url": "..."}`, stores it directly. - `openerRequest` in the create answer (present when no opener was given) has the link and the words to send: forward `openerRequest.askThePerson` as is. ## After the first call (X-Parlo-Api-Key: pk_...) - GET https://api.parlo.me/api/my/surveys — every parlo the key's person is in, newest activity first, with answer counts and the report preview. - GET https://api.parlo.me/api/d/{dashboardCode} — one parlo's answers with transcripts and signed audio URLs. - POST https://api.parlo.me/api/surveys/{parloId}/intro/from-url {"url"} — add or replace the opener from a voice-note URL (owner only). - GET https://api.parlo.me/api/my/surveys/{parloId}/export.csv — every answer as CSV. - Rounds (owner or admin): GET .../rounds, POST .../rounds/propose {"kind":"poll|probe","hint"}, POST .../rounds/{roundId}/approve, POST .../rounds/{roundId}/reject. - The report: GET https://api.parlo.me/api/my/surveys/{parloId}/agent → {report, rounds, ...}. ## MCP server https://mcp.parlo.me/mcp — Streamable HTTP, OAuth 2.1 with dynamic client registration (discovery at https://mcp.parlo.me/.well-known/oauth-authorization-server). On the authorize page paste the person's API key, or choose "create new account" for a fresh one. Tools: create_parlo (same as the request above), list_my_surveys, get_dashboard, get_transcriptions, get_survey_stats, get_survey, get_share_links, update_questions. Connect once and keep the token: the first connection costs about 20 seconds of OAuth, later calls are instant. ## What participants see shareLink opens a page that plays the opener (if there is one), shows the round's questions one at a time, and records a voice answer for each (photo and video questions use the phone's camera). answerLink does the same inside WhatsApp: Parlo's number plays the opener, asks one question per message, each reply is a voice note, and the person joins the group with their number as identity (no sign-up). The report reaches them in that same chat. Answering joins the group; members get the agent's report once they have answered. Nothing is anonymous to the agent; by default only the owner, admins and the agent hear raw answers. ## Vocabulary A "parlo" is what a person creates (the product never says "survey" on screen; the API and event names still do). The person who creates it is the owner; people who answer are members; the agent writes /report.md for the group and proposes the next round for the owner to approve.