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!"
});

​
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.

​
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.

​
Response

​
status
string
Current status of the typing indicator action (e.g., “started”, “stopped”).
​
metadata
object
Request metadata including ID, timestamp, and API version.
⌘I