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.

    The request

    Votes come back to your server.

    Each vote, changed vote or removed vote fires poll.voted with the poll's results so far.

    Your server
    // waiting for a vote: tap an option on the phone
    Harbor Dental

    Every poll carries its tally.

    Read it from a webhook, from the messages list, or from GET /api/imessage/messages/{id}/poll.

    Which day works?voter_count 5
    1. Tue1
      +18055550101
    2. Wed3
      +18055550102+18055550103+18055550104
    3. Thu2
      +18055550101+18055550105
    Each option has votes and voters, oldest vote first. A person can choose several options.

    How it works

    1. Send the poll. Put a poll with a question and 2 to 12 options in POST /api/imessage/send instead of text. It goes to someone who has replied to this number, or into a group chat with chat_id.
    2. 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.
    3. Your webhook gets every vote. poll.voted fires when someone votes, changes their vote or removes it. Its message is a poll_vote with that person’s whole selection, and poll holds the results after the vote.
    Send, vote, tally
    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, ...}}}
    The full reference is in our docs.

    How polls reach you

    Three places carry a poll and its results.

    Poll events and reads
    WhereWhen it happensWhat it carries
    poll.votedSomeone 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.receivedThey send you a poll.A record with kind: "poll". Votes on it arrive as poll.voted.
    GET /api/imessage/messages/{id}/pollYou 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.