Skip to main content

​
Sending an iMessage

Send rich iMessage content to your users with automatic fallback to SMS when iMessage is not available.
iMessage messages require the recipient to have an Apple device with iMessage enabled. If iMessage is not available, you can configure automatic fallback to SMS.
const res = await contiguity.imessage.send({
  to: "+1234567890",
  message: "Hello via iMessage!",
  // from: "+15555555555",
  fallback: { 
    when: ["imessage_unsupported", "imessage_fails"], 
    from: "+15555555555" 
  },
  attachments: ["https://example.com/image.png"]
});
You can also send a simple iMessage without attachments: 
const res = await contiguity.imessage.send({
  to: "+1234567890",
  message: "Hello from your app!"
});

​
Fetch a message

const res = await contiguity.imessage.get("msg_...");

​
Conversation history

const res = await contiguity.imessage.history({
  to: "+1234567890",
  from: "+15555555555",
  limit: 20   // optional
});

​
Reactions

await contiguity.imessage.react("add", {
  tapback: "love",
  message_id: "msg_..."
});
// Or: to + from + message
await contiguity.imessage.react("remove", { tapback: "thumbsup", to: "+1234567890", from: "+15555555555", message: "Hello" });

​
Mark as read

await contiguity.imessage.read({ to: "+1234567890", from: "+15555555555" });

​
Check iMessage availability

const res = await contiguity.imessage.availability({ to: "+1234567890" });

​
Parameters

​
to
string
required
Recipient phone number in E.164 format.

​
Response

​
available
boolean
Whether the number supports iMessage.
​
metadata
object
Request metadata: id, timestamp, api_version, object.

​
Typing Indicators

Show typing indicators to create a more interactive messaging experience. Start typing indicator: 
const res = await contiguity.imessage.typing({
  to: "+1234567890", 
  action: "start"
});
Stop typing indicator: 
const res = await contiguity.imessage.typing({
  to: "+1234567890", 
  action: "stop"
});

​
Parameters

​
imessage.send(params)

​
to
string
required
The recipient’s phone number in E.164 format (e.g., “+1234567890”).
​
message
string
required
The message content to send via iMessage.
​
from
string
Optional leased phone number to use as the sender. Must be a number you have leased from Contiguity.
​
fallback
object
Fallback configuration for when iMessage is not available.
​
attachments
string[]
Array of attachment URLs to include with the message. Supports images and other media.
​
fast_track
boolean
Optional. Bypass recommended rate limiting on leased numbers. Requires Fast Track entitlement.

​
Response

​
message_id
string
Unique identifier for the sent iMessage, used for tracking delivery status.
​
metadata
object
Request metadata including ID, timestamp, and API version.

​
imessage.typing(params)

​
to
string
required
The recipient’s phone number in E.164 format (e.g., “+1234567890”).
​
action
string
required
The typing indicator action. Options: "start" to show typing, "stop" to hide typing.
​
from
string
Optional leased phone number to use as the sender.

​
imessage.get(id)

​
id
string
required
Message ID (same endpoint as text get; conversations).

​
imessage.history(params)

​
to
string
required
Recipient E.164.
​
from
string
required
Sender E.164.
​
limit
number
Optional. Max messages to return.

​
imessage.react(action, params)

​
action
string
required
"add" or "remove".
​
tapback
string
required
e.g. "love", "thumbsup", etc.
​
message_id
string
Message ID, or use to + from + message.

​
imessage.read(params)

​
to
string
required
Recipient E.164.
​
from
string
required
Sender E.164.

​
imessage.availability(params)

​
to
string
required
Recipient E.164 phone number.

​
Response (send / get / history / react / availability)

​
message_id
string
Message ID (send/react).
​
metadata
object
Request metadata: id, timestamp, api_version, object.