Skip to main content

Method

await sdk.polls.create(options: CreatePollOptions): Promise<PollMessageResponse>
Creates a new poll in an iMessage chat. Polls must have at least 2 options.

Parameters

options
CreatePollOptions
required
Configuration for the poll

Returns

PollMessageResponse
MessageResponse
The created poll message

Examples

Basic Poll

const poll = await sdk.polls.create({
  chatGuid: "iMessage;-;+1234567890",
  title: "What should we have for lunch?",
  options: ["Pizza", "Tacos", "Sushi", "Burgers"],
});

console.log(`Poll created: ${poll.guid}`);

Poll Without Title

// Title is optional - you can create a poll with just options
const poll = await sdk.polls.create({
  chatGuid: "iMessage;-;+1234567890",
  title: "",
  options: ["Yes", "No", "Maybe"],
});

console.log(`Poll created: ${poll.guid}`);

Create Poll and Parse Definition

import { parsePollDefinition } from "@photon-ai/advanced-imessage-kit";

const poll = await sdk.polls.create({
  chatGuid: "iMessage;-;+1234567890",
  title: "Best programming language?",
  options: ["TypeScript", "Python", "Go", "Rust"],
});

// Parse the poll to get option identifiers for voting
const pollData = parsePollDefinition(poll);

if (pollData) {
  console.log(`Poll: ${pollData.title}`);
  console.log(`Creator: ${pollData.creatorHandle}`);
  console.log("Options:");
  
  pollData.options.forEach((option, index) => {
    console.log(`  ${index + 1}. ${option.text} (ID: ${option.optionIdentifier})`);
  });
}

Create Poll in Group Chat

const groupPoll = await sdk.polls.create({
  chatGuid: "iMessage;+;chat123456789",
  title: "When should we meet?",
  options: [
    "Monday 2 PM",
    "Tuesday 3 PM",
    "Wednesday 4 PM",
    "Thursday 2 PM",
  ],
});

console.log(`Group poll created: ${groupPoll.guid}`);

Error Handling

try {
  const poll = await sdk.polls.create({
    chatGuid: "iMessage;-;+1234567890",
    title: "Valid poll?",
    options: ["Only one option"], // ERROR: Less than 2 options
  });
} catch (error) {
  console.error(error.message); // "Poll must have at least 2 options"
}

Notes

  • Polls require at least 2 options (enforced by the SDK)
  • The title field is optional and can be an empty string
  • Save the returned poll.guid to interact with the poll later (voting, adding options, etc.)
  • Use parsePollDefinition() to extract poll details including option identifiers needed for voting
  • Poll options cannot be removed after creation, but new options can be added with addOption()
  • The creator’s handle is automatically included in the poll data

Build docs developers (and LLMs) love