iMessage threaded replies API
Add reply_to to a send and the message is threaded under the one it answers, the way a swipe to reply looks in Messages. Replies they send arrive the same way, with a reply_to object on the message.
Pro is $49/month per number. Limits apply to every send.
Answer the message they asked.
Add reply_to with the id of any message in the conversation. The reply threads under that message, not under the latest one.
Their replies come back threaded.
When they reply to a message, your webhook gets it with a reply_to object that names the original.
Reply with a text, photo, video or poll.
A voice message cannot be a reply.
How it works
- Pick the original.
reply_tois theidof a message (a number, or a string of digits) or its iMessageguid. It must be a message, photo, video, voice message or poll in this conversation on your account that reached iMessage, so it has aguid. - Send the reply. Add
reply_totoPOST /api/imessage/sendwith text, a photo, a video or a poll. On their Apple phone it is threaded under the message it answers, the way a swipe to reply looks in Messages. - Read replies in both directions. Any message that is a reply carries
reply_to: in the send response’srecord, inGET /api/imessage/messagesand in webhooks (message.received,message.sent,message.failed). Replies they send arrive the same way.
POST /api/imessage/send
{"to": "+18055559876", "text": "Friday at 3 works.",
"reply_to": 44}
// the record carries reply_to
{"id": 47, "kind": "message", "direction": "out",
"handle": "+18055559876", "text": "Friday at 3 works.",
"status": "sent", "guid": "9C0E…",
"reply_to": {"id": 44, "guid": "5A6F…",
"text": "Do you have anything Friday?"}}
// a reply they send arrives the same way
{"event": "message.received",
"message": {"direction": "in", "text": "See you then.",
"reply_to": {"id": 47, ...}}}
The reply_to object
A message that is not a reply has no reply_to key at all.
| Field | What it holds |
|---|---|
id | The original’s id. null when the original isn’t stored on the line, because it predates the line or was deleted. |
guid | The original’s iMessage GUID. |
text | The original’s text, up to 200 characters. null when the original isn’t stored on the line. |
Limits and plans
What a reply can be
Text, a photo or a video (with or without a caption), or a poll. A voice message cannot be a reply (422 invalid_request). A poll’s question follows it into the same thread.
422 invalid_reply_to
reply_to names a message in another conversation, on another line than the one you named, a reaction or a poll vote, or a send that never reached iMessage. Nothing is sent or stored.
404 reply_target_not_found
reply_to names no message on your account. Use an id or guid from your messages. Nothing is sent or stored.
Several numbers
A reply goes out from the number its original is on. Naming a different line or line_id is 422 invalid_reply_to.
409 reply_unsupported
This line needs an update before it can send replies. A poll reply needs a later update than a text reply. Nothing is sent or stored.
Original not found
If the line can’t find the original in the conversation, the send fails with 502 send_failed, record.status is failed and nothing was sent.
Group chats
A reply in a group works the same, and reply_to must name a message in that same group (422 invalid_reply_to otherwise).
iMessage only
An inline reply 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
How do I send an inline reply with the iMessage API?
Add reply_to to POST /api/imessage/send, for example {"to": "+18055559876", "text": "Friday at 3 works.", "reply_to": 44}. On their Apple phone the message is threaded under the one it answers.
What does reply_to take?
The id of a message, as a number or a string of digits, or its iMessage guid. It must be a message, photo, video, voice message or poll in the same conversation on your account that reached iMessage.
How do I know when someone replies to a specific message?
Any message that is a reply carries a reply_to object. When they reply, message.received has it, and so do GET /api/imessage/messages and the send response for your own replies. reply_to.guid is the original’s iMessage GUID.
What can a reply contain?
Text, a photo, a video (with or without a caption) or a poll. A voice message cannot be a reply, and a send with audio_b64 and reply_to answers 422 invalid_request.
What if the original is not stored on the line?
reply_to.id and reply_to.text are null when the original predates the line or was deleted. guid is still there.
Do threaded replies work in group chats?
Yes. reply_to on a group send must name a message in that same group, or the send answers 422 invalid_reply_to.
What happens if the number’s phone is out of date?
The send answers 409 reply_unsupported and nothing is sent or stored. Send it without reply_to, or try again after the update.
Send your first threaded reply
Get a number, then add reply_to to a send with the id of any message in the conversation.