Voting | Weei

Widget ID: voting. API: documented below.

Purpose

Polls with 2–8 options, single or multiple choice. Results update live. Only the author can close a poll; participants who join later receive the open polls of authors who are present. A notification announces new and closed polls even when the window is closed.

Good to know

Polls are kept in memory only and disappear when the author leaves.
Votes are sent to the poll's author, who counts them and shares the results. A participant cannot vote while the author is disconnected.

Getting the API

The API is available as soon as loadWeei() resolves, if the widget is enabled for your site. The widget window does not need to be open.

JavaScript

const weei = await window.weeiReady;
const voting = weei.widgetsApi.get('voting');
if (!voting) throw new Error('Voting is not enabled for this site.');

TypeScript

interface VotingApi {
  getPolls(): PollSummary[];
  subscribe(listener: (polls: PollSummary[]) => void): () => void;
  create(input: { question: string; options: string[]; multiple?: boolean }): Promise<PollSummary>;
  vote(pollId: string, choices: number[]): Promise<void>;
  close(pollId: string): Promise<void>;
  whenClosed(pollId: string): Promise<PollSummary>;
}

interface PollSummary {
  id: string;
  owner: string;                    // peer ID of the author
  ownerName: string;
  question: string;
  options: string[];
  multiple: boolean;
  status: 'open' | 'closed';
  votes: Record<string, number[]>;  // option indexes chosen by each voter, by peer ID
  counts: number[];                 // votes per option, in the order of options
  voters: number;                   // participants who voted
  myChoices: number[];              // this browser's choice; [] if it has not voted
  mine: boolean;                    // created by this browser
  createdAt: number;                // ms since epoch
  closedAt?: number;
}

Every action returns a promise that rejects with an Error whose message says why, for example an unknown ID or a participant that is not allowed to act. subscribe() calls the listener at once with the current list, then on every change, and returns a function that unsubscribes. Lists are copies: changing them has no effect.

Method	Behavior
`getPolls()`	Polls known to this browser, newest first: its own and those of authors who are connected. Up to 50.
`create(input)`	Starts a poll for everyone and resolves with it. The question is up to 200 characters; 2–8 distinct options of up to 80 characters each. `multiple` is ignored with only two options. The author's name is the participant's display name.
`vote(id, choices)`	Sets or replaces this participant's choice, as option indexes from 0. Exactly one index unless the poll allows several. Rejects if the poll is closed or its author is not connected.
`close(id)`	Closes the poll for everyone. Only the author can close it.
`whenClosed(id)`	Resolves with the final results once the poll is closed. It does not resolve if the author leaves first.

Example: ask from your page and save the result

JavaScript

const weei = await window.weeiReady;
const voting = weei.widgetsApi.get('voting');

const poll = await voting.create({
  question: 'Which plan should we propose?',
  options: ['Starter', 'Team', 'Enterprise']
});

setTimeout(() => voting.close(poll.id), 60_000);   // one minute to vote

const result = await voting.whenClosed(poll.id);
const winner = result.options[result.counts.indexOf(Math.max(...result.counts))];
console.log(winner, result.counts, result.voters + ' voted');