Documentation Index Fetch the complete documentation index at: https://mintlify.com/photon-hq/advanced-imessage-kit/llms.txt
Use this file to discover all available pages before exploring further.
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 The chat GUID where the poll will be created
The poll question or title (optional, can be empty string)
Array of poll options (minimum 2 required)
Returns
The created poll message Unique message GUID for the poll (use this for voting, unvoting, and adding options)
Bundle ID for polls: "com.apple.messages.MSMessageExtensionBalloonPlugin:0000000000:com.apple.messages.Polls"
Raw poll data containing the poll definition (parse with parsePollDefinition())
Timestamp when the poll was created
Always true for created polls
Message text (usually empty for polls)
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