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.

Harbor Dental

Harbor Dental

Their replies come back threaded.

When they reply to a message, your webhook gets it with a reply_to object that names the original.

Your server
// waiting for a reply: pick a message under the phone

Reply with a text, photo, video or poll.

A voice message cannot be a reply.

Text
Photo
Video
Poll
Voice message 422 invalid_request

How it works

  1. Pick the original. reply_to is the id of a message (a number, or a string of digits) or its iMessage guid. It must be a message, photo, video, voice message or poll in this conversation on your account that reached iMessage, so it has a guid.
  2. Send the reply. Add reply_to to POST /api/imessage/send with 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.
  3. Read replies in both directions. Any message that is a reply carries reply_to: in the send response’s record, in GET /api/imessage/messages and in webhooks (message.received, message.sent, message.failed). Replies they send arrive the same way.
Reply, and read replies
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, ...}}}
reply_to takes the id of a message, or its iMessage guid. The full reference is in our docs.

The reply_to object

A message that is not a reply has no reply_to key at all.

Fields of reply_to
FieldWhat it holds
idThe original’s id. null when the original isn’t stored on the line, because it predates the line or was deleted.
guidThe original’s iMessage GUID.
textThe 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.