Rooms and results

A room is one live session of a deck: a six-digit code, a QR, and the audience answering on their phones. The presenter drives it from the presenter view; an agent can drive it over the API with the same five actions.

Start a room

curl -X POST https://test.polltheroom.com/api/v1/rooms \
  -H "Authorization: Bearer ptr_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "deckId": "DECK_ID" }'

{
  "code": "491026",
  "hostToken": "c6f55304-…",
  "joinUrl": "https://test.polltheroom.com/j/491026",
  "presentUrl": "https://test.polltheroom.com/present/491026#host=c6f55304-…"
}

The room waits in the lobby. Hand presentUrl to the person presenting: it opens the presenter view and claims the host key from the fragment, so the person can take over from the agent at any point. joinUrl is what the audience opens.

A deck with uploaded slide pages starts from the editor for now, because the pages are rendered in the browser. start_room answers 409 for such a deck and says so. Decks of blank slides and polls start here.

Starting rooms needs the rooms:start scope, which the Pro plan sells. The room needs every poll to pass readiness; otherwise 400 names the first problem.

Drive it

room_action does what the presenter’s buttons do, and answers with where the room is.

Action	Does
`start`	Begins the session at step 0.
`next`	Locks whatever is live and walks to the next step. After the last step, the session ends.
`prev`	Locks whatever is live and walks back.
`close`	Closes the live poll and reveals the result.
`stop`	Ends the session from anywhere.

curl -X POST https://test.polltheroom.com/api/v1/rooms/491026/actions \
  -H "Authorization: Bearer ptr_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "action": "next" }'

{ "status": "presenting", "stepIndex": 1, "stepCount": 5 }

An action that does not fit the room’s state, next before start for example, answers 409 with a sentence.

Read the results

room_results returns every poll’s results so far, live or ended, as JSON and as a markdown summary ready to paste into a follow-up.

curl https://test.polltheroom.com/api/v1/rooms/491026/results \
  -H "Authorization: Bearer ptr_YOUR_KEY"

{
  "code": "491026",
  "title": "Town hall",
  "status": "ended",
  "joined": 42,
  "pollCount": 4,
  "avgResponseRate": 0.81,
  "liveMinutes": 38,
  "polls": [ { "type": "multiple-choice", "prompt": "Which one?", "counts": { "…": 12 }, "totalAnswers": 34 } ],
  "markdown": "# Town hall\n\nRoom 491026. 42 joined. 4 polls. Live for 38 minutes.\n\n## Which one?\n…"
}

See Read results for what each widget puts in its snapshot.

Rooms live in memory on one server. Results are available while the room is held there, which is until the server restarts. Keeping them for good is on the roadmap.

List rooms

list_rooms returns the team’s rooms, newest first, fifty at most, with each room’s code, status and how many people joined.

Get started

Concepts

Guides

Reference

Start a room

Drive it

Read the results

List rooms

​Start a room

​Drive it

​Read the results

​List rooms

Start a room

Drive it

Read the results

List rooms