iMessage polls API
Send a poll with the same POST you use for texts, with a question and 2 to 12 options. Each vote, change or removal comes back to your webhook as a poll.voted event with the results so far.
Pro is $49/month per number. Limits apply to every send.
Send a poll in one call.
Pass a question and 2 to 12 options to the same endpoint you use for texts. Edit the poll and the request changes with it.
Votes come back to your server.
Each vote, changed vote or removed vote fires poll.voted with the poll's results so far.
Every poll carries its tally.
Read it from a webhook, from the messages list, or from GET /api/imessage/messages/{id}/poll.
voter_count 5- Tue1+18055550101
- Wed3+18055550102+18055550103+18055550104
- Thu2+18055550101+18055550105
How it works
- Send the poll. Put a
pollwith aquestionand 2 to 12optionsinPOST /api/imessage/sendinstead oftext. It goes to someone who has replied to this number, or into a group chat withchat_id. - They vote on their Apple phone. On iOS 26 or later they vote right in the conversation. On older Apple phones they see “Sent a poll” and cannot vote. iOS draws no question on a poll, so the question follows it as a text of its own.
- Your webhook gets every vote.
poll.votedfires when someone votes, changes their vote or removes it. Itsmessageis apoll_votewith that person’s whole selection, andpollholds the results after the vote.
POST /api/imessage/send
{"to": "+18055559876",
"poll": {"question": "Which day works?",
"options": ["Tue", "Wed", "Thu"]}}
// the record that comes back
{"id": 46, "kind": "poll", "direction": "out",
"status": "sent",
"poll": {"question": "Which day works?",
"options": [{"id": "186E…", "text": "Tue", "votes": 0, "voters": []},
...],
"voter_count": 0}}
// when they vote, your webhook gets
{"event": "poll.voted",
"message": {"kind": "poll_vote", "direction": "in",
"target_id": 46,
"vote": {"option_ids": ["9A1C…"]},
"poll": {"voter_count": 1, ...}}}
How polls reach you
Three places carry a poll and its results.
| Where | When it happens | What it carries |
|---|---|---|
poll.voted | Someone votes, changes their vote or removes it. | message.kind is poll_vote, with target_id and target_guid of the poll. vote.option_ids is that voter’s whole selection, and [] means they removed their vote. poll holds the results after this vote, or null if the poll isn’t stored on the line. |
message.received | They send you a poll. | A record with kind: "poll". Votes on it arrive as poll.voted. |
GET /api/imessage/messages/{id}/poll | You want one poll’s current record. | The poll with live results. 404 not_found if that id isn’t a poll on your account. Results are also on every poll in GET /api/imessage/messages and in webhooks. |
Limits and plans
Options
2 to 12 options, each 1 to 150 characters after trimming, all different when case is ignored. The question is optional and up to 300 characters. A poll that breaks a rule answers 422 invalid_request, and error.fields names the offender.
Only a poll
A poll carries no text, image_b64, audio_b64 or video.
Who can get one
A poll goes only to someone who has replied to this number, or the send answers 403 attachment_before_reply. It counts as a message toward every limit.
The question
It follows the poll as a text of its own, a message like any other with its own id and message.sent webhook, and it counts toward your limits. If it cannot be sent, the poll still stands.
Older Apple phones
Voting needs iOS 26 or later. Older Apple phones see “Sent a poll” and cannot vote.
409 poll_unsupported
This line needs an update before it can send polls. Nothing is sent or stored. Send it as text, or try again after the update.
Votes out of order
A vote older than the one already counted for that person changes nothing, so act on the results in the event instead of keeping your own count. A vote that arrives before its poll is counted once the poll is stored.
Replies, reactions and groups
With reply_to a poll is an inline reply, its question too. Reactions work on a poll. Polls work in iMessage group chats.
iMessage only
A poll is an iMessage feature. It has no SMS equivalent.
Plans
Pro is $49/month per number, with 5 new contacts a day per number. Growth has 25+ new contacts a day per number. Details are on the iMessage API page.
Questions
Is there an iMessage polls API?
Yes. Pass poll instead of text to POST /api/imessage/send, with a question and 2 to 12 options. Recipients on iOS 26 or later vote in the conversation, and each vote comes back to your webhook as poll.voted.
How do I send an iMessage poll from code?
Send {"to": "+18055559876", "poll": {"question": "Which day works?", "options": ["Tue", "Wed", "Thu"]}} to POST /api/imessage/send. The response has the same shape as a text send, and the record has kind: "poll" with the options and their live results.
How do I get the votes?
Your webhook gets poll.voted each time someone votes, changes their vote or removes it. The event carries that person’s whole selection in vote.option_ids and the poll’s results in poll. You can also read one poll with GET /api/imessage/messages/{id}/poll.
Who can vote in the poll?
People on iOS 26 or later vote right in the conversation. On older Apple phones they see “Sent a poll” and cannot vote. A line that needs an update returns 409 poll_unsupported.
Can a person choose more than one option?
Yes. voters lists the handles that chose each option and votes counts them. voter_count is how many people have a vote in.
Can I send a poll to someone who has not replied?
No. A poll goes only to someone who has replied to this number, or the send answers 403 attachment_before_reply and nothing is sent. Send text until they reply.
Do polls work in group chats?
Yes. A send with chat_id and a poll puts the poll in the group, every member can vote, and voters lists each member’s handle. Group votes arrive as poll.voted with the chat_id.
Send your first poll
Get a number, then send POST /api/imessage/send with a poll. The votes come back to your webhook.