What an iMessage API thread can do

A ZeroSettle thread can carry tapbacks, polls, photos, voice memos, inline replies, chat backgrounds, effects and your business name and photo. Each one is a call to the send API or an event on your webhook, from $49/month per number.

See how plain-text SMS fallback works.

Features

Everything a thread can do.

Tapbacks, polls, photos, voice memos, inline replies, chat backgrounds, effects and your business name and photo. Each one is a call to the send API or an event on your webhook.

One call for each.

Reactions

On their Apple phone. A tapback appears on the corner of the bubble it answers, the same as when a person reacts in Messages.

Your code. Send POST /api/imessage/reactions with a message_id and a reaction. Put remove_ in front to take one back.

Read the reactions page

The request
POST /api/imessage/reactions
{"message_id": 46,
 "reaction": "love"}
Your webhook
// when they react, your webhook gets
{"event": "reaction.received",
 "message": {"kind": "reaction",
             "target_id": 46}}

Polls

On their Apple phone. A poll appears in the conversation. On iOS 26 or later they vote right there.

Your code. Pass poll instead of text to POST /api/imessage/send, with a question and 2 to 12 options.

Read the polls page

The request
POST /api/imessage/send
{"to": "+18055559876",
 "poll": {"question": "Which day works?",
          "options": ["Tue", "Wed", "Thu"]}}
Your webhook
// when they vote, your webhook gets
{"event": "poll.voted",
 "message": {"kind": "poll_vote",
             "target_id": 46,
             "vote": {"option_ids": ["9A1C…"]},
             "poll": {"voter_count": 1, ...}}}

Photos

On their Apple phone. A photo arrives as a native photo bubble, with your caption in the same bubble. A voice message arrives as the native audio bubble.

Your code. Send image_b64 (with optional text as the caption) or audio_b64 through POST /api/imessage/send.

Read the photos page

The request
POST /api/imessage/send
{"to": "+18055559876",
 "image_b64": "/9j/4AAQSkZJRg…",
 "text": "Your booking"}
Your webhook
// when they send you one, your webhook gets
{"event": "message.received",
 "message": {"id": 52,
            "image": {"url": "…"}}}
// fetch it with your API key from
GET /api/imessage/messages/52/image

Threads

On their Apple phone. The message is threaded under the one it answers, the way a swipe to reply looks in Messages.

Your code. Add reply_to to a send. It is the id or the iMessage guid of a message in the same conversation.

Read the threads page

The request
POST /api/imessage/send
{"to": "+18055559876",
 "text": "Tuesday works.",
 "reply_to": 46}
Your webhook
// a reply carries a reply_to object
{"event": "message.received",
 "message": {"text": "Great, see you then",
             "reply_to": {"id": 46, ...}}}

Backgrounds

On their Apple phone. On iOS 26 the conversation shows a background picture. Applying or removing one changes it for both people in that conversation.

Your code. Send POST /api/imessage/background with to and exactly one of preset, image_b64, archive_b64 or remove: true.

Read the backgrounds page

The request
POST /api/imessage/background
{"to": "+18055559876",
 "preset": "aurora"}
Your webhook
// when they change theirs, your webhook gets
{"event": "background.changed"}
// never message.received

Name and photo

On their Apple phone. They see “<name> shared a name and photo with you” and can save it to their contacts.

Your code. Set the profile once with PUT /api/imessage/profile, passing name and image_b64. Every send then shares it on the first message of a conversation.

Read the name and photo page

The request
PUT /api/imessage/profile
{"name": "Harbor Dental",
 "image_b64": "/9j/4AAQSkZJRg…"}
Your webhook
// nothing to receive
POST /api/imessage/profile/share
// re-shares on demand

Effects

On their Apple phone. The message arrives the way Send with effect does in Messages: it slams, shakes, grows, hides under invisible ink, or plays a screen effect such as balloons or confetti.

Your code. Add effect to a text, photo or video send. Not on polls or voice messages.

The request
POST /api/imessage/send
{"to": "+18055559876",
 "text": "Welcome aboard",
 "effect": "confetti"}
Your webhook
// the message carries its effect
{"event": "message.received",
 "message": {"effect": "confetti", ...}}

The features at a glance

How you send it, what arrives in your webhook when the other person uses it, and the main limit.

What a thread can do (our docs, checked November 11, 2026)
FeatureYour code sendsYour code receivesMain limit
SMS fallbacktext on POST /api/imessage/sendmessage.received with service: "SMS"One-to-one plain text to phone numbers
ReactionsPOST /api/imessage/reactionsreaction.receivedOnly on a message, photo, voice message or video
Pollspoll on POST /api/imessage/sendpoll.votedVoting needs iOS 26 or later
Photos and voice memosimage_b64 or audio_b64 on sendmessage.received with a file linkOnly to someone who has replied
Threadsreply_to on sendreply_to on the messageNot for voice messages
Chat backgroundsPOST /api/imessage/backgroundbackground.changedNeeds an existing conversation
Your name and photoPUT /api/imessage/profileNothing to receiveName up to 64 characters, photo under 3 MB
Effectseffect on sendeffect on the messageNot on polls or voice messages

Limits that apply to all of it

  • Photos, voice messages, videos and polls go only to someone who has replied to your number. Text them first.
  • Pro includes 5 new contacts a day per number. Growth raises the daily limit. People who text first never count. See the plans.
  • At most 2 texts to a contact who has never replied, and STOP is honoured.
  • Reactions, typing indicators, name and photo sharing and chat backgrounds are not new contacts.
  • Some features need a recent iOS on the recipient’s Apple phone, or an update to your line. The error codes above say which.

Frequently asked questions

Can I send tapbacks through the iMessage API?

Yes. POST /api/imessage/reactions takes a message_id and one of love, like, dislike, laugh, emphasize or question. Add remove_ to take one back. Reactions they send arrive as reaction.received events.

Do iMessage polls work on older Apple phones?

Recipients on iOS 26 or later vote in the conversation. On older Apple phones they see “Sent a poll” and cannot vote.

Can I send photos and voice memos to anyone?

Only to people who have replied to your number. Until then the send answers 403 attachment_before_reply, so start with a text.

Can my business name and photo show up in Messages?

Yes. Set a name and photo once with PUT /api/imessage/profile. Each conversation gets the card on your first message, and the recipient can save it to their contacts.

Do these features count toward my limits?

Polls, photos, voice messages and videos count as messages, and to someone new they count as a new contact. Reactions, name and photo sharing, typing indicators and chat backgrounds do not count as new contacts. Videos also use credits.

Try it on your own number

Get a number and send your first poll, photo or tapback.