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.
POST /api/imessage/reactions
{"message_id": 46,
"reaction": "love"}
// 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.
POST /api/imessage/send
{"to": "+18055559876",
"poll": {"question": "Which day works?",
"options": ["Tue", "Wed", "Thu"]}}
// 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.
POST /api/imessage/send
{"to": "+18055559876",
"image_b64": "/9j/4AAQSkZJRg…",
"text": "Your booking"}
// 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/imageThreads
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.
POST /api/imessage/send
{"to": "+18055559876",
"text": "Tuesday works.",
"reply_to": 46}
// 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.
POST /api/imessage/background
{"to": "+18055559876",
"preset": "aurora"}
// when they change theirs, your webhook gets
{"event": "background.changed"}
// never message.receivedName 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.
PUT /api/imessage/profile
{"name": "Harbor Dental",
"image_b64": "/9j/4AAQSkZJRg…"}
// nothing to receive
POST /api/imessage/profile/share
// re-shares on demandEffects
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.
POST /api/imessage/send
{"to": "+18055559876",
"text": "Welcome aboard",
"effect": "confetti"}
// 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.
| Feature | Your code sends | Your code receives | Main limit |
|---|---|---|---|
| SMS fallback | text on POST /api/imessage/send | message.received with service: "SMS" | One-to-one plain text to phone numbers |
| Reactions | POST /api/imessage/reactions | reaction.received | Only on a message, photo, voice message or video |
| Polls | poll on POST /api/imessage/send | poll.voted | Voting needs iOS 26 or later |
| Photos and voice memos | image_b64 or audio_b64 on send | message.received with a file link | Only to someone who has replied |
| Threads | reply_to on send | reply_to on the message | Not for voice messages |
| Chat backgrounds | POST /api/imessage/background | background.changed | Needs an existing conversation |
| Your name and photo | PUT /api/imessage/profile | Nothing to receive | Name up to 64 characters, photo under 3 MB |
| Effects | effect on send | effect on the message | Not 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.









