iMessage Resource

ImessageResource

The imessage resource provides methods for sending iMessages, managing typing indicators, reactions, and read receipts.

send()

await contiguity.imessage.send(params: ImessageSendParams): Promise<{ message_id: string }>

Send an iMessage to a recipient.

params

ImessageSendParams

required

Show properties

string

required

Recipient phone number or email address.

message

string

required

The message content to send.

from

string

Sender phone number. If not provided, a number will be automatically selected.

attachments

string[]

Array of attachment URLs to include with the message.

fallback

object

Fallback configuration for when iMessage fails or is unsupported.

Show properties

when

array

required

Array of conditions: imessage_unsupported or imessage_fails.

from

string

Fallback sender number for SMS delivery.

fast_track

boolean

Enable fast-track delivery for time-sensitive messages.

message_id

string

Unique identifier for the sent message.

const result = await contiguity.imessage.send({
  to: '+1234567890',
  from: '+0987654321',
  message: 'Hello via iMessage!',
  attachments: ['https://example.com/image.jpg'],
  fallback: {
    when: ['imessage_unsupported', 'imessage_fails'],
    from: '+0987654321'
  }
});

console.log(result.message_id); // "msg_..."

reply()

await contiguity.imessage.reply(
  event: WebhookEventBase,
  params: Omit<ImessageSendParams, 'to' | 'from'>
): Promise<{ message_id: string }>

Reply to an incoming iMessage webhook. Automatically fills to and from fields from the webhook event.

event

WebhookEventBase

required

The webhook event received from an incoming iMessage.

params

Omit<ImessageSendParams, 'to' | 'from'>

required

Message parameters (same as send() but without to and from).

message_id

string

Unique identifier for the sent reply.

app.post('/webhook', async (req, res) => {
  const event = contiguity.webhook.parse(req.body);
  
  if (event.type === 'imessage.incoming') {
    await contiguity.imessage.reply(event, {
      message: 'Thanks for your iMessage!'
    });
  }
  
  res.sendStatus(200);
});

typing()

await contiguity.imessage.typing(params: ImessageTypingParams): Promise<any>

Send a typing indicator to show that you’re composing a message.

params

ImessageTypingParams

required

Show properties

string

required

Recipient phone number or email address.

action

'start' | 'stop'

required

Whether to start or stop the typing indicator.

from

string

Sender phone number.

// Show typing indicator
await contiguity.imessage.typing({
  to: '+1234567890',
  from: '+0987654321',
  action: 'start'
});

// Simulate composing message...
await new Promise(resolve => setTimeout(resolve, 2000));

// Stop typing indicator and send message
await contiguity.imessage.typing({
  to: '+1234567890',
  from: '+0987654321',
  action: 'stop'
});

await contiguity.imessage.send({
  to: '+1234567890',
  from: '+0987654321',
  message: 'Here is my response!'
});

get()

await contiguity.imessage.get(id: string): Promise<any>

Retrieve details about a specific iMessage by its ID.

string

required

The message ID returned from send() or reply().

const message = await contiguity.imessage.get('msg_...');
console.log(message);

history()

await contiguity.imessage.history(params: ConversationHistoryParams): Promise<any>

Retrieve iMessage history for a conversation.

params

ConversationHistoryParams

required

Show properties

string

required

One of the participants in the conversation.

from

string

required

The other participant in the conversation.

limit

number

Maximum number of messages to retrieve. Defaults to 20.

const history = await contiguity.imessage.history({
  to: '+1234567890',
  from: '+0987654321',
  limit: 50
});

react()

await contiguity.imessage.react(
  action: 'add' | 'remove',
  params: ImessageReactParams
): Promise<any>

Add or remove a tapback reaction to an iMessage.

action

'add' | 'remove'

required

Whether to add or remove the reaction.

params

ImessageReactParams

required

Show properties

string

required

Recipient phone number or email address.

from

string

required

Sender phone number.

tapback

enum

required

The tapback type. One of: love, like, dislike, laugh, emphasize, question.

message

string

required

The message text to react to.

// Add a tapback
await contiguity.imessage.react('add', {
  to: '+1234567890',
  from: '+0987654321',
  tapback: 'love',
  message: 'Thanks for the help!'
});

// Remove a tapback
await contiguity.imessage.react('remove', {
  to: '+1234567890',
  from: '+0987654321',
  tapback: 'love',
  message: 'Thanks for the help!'
});

read()

await contiguity.imessage.read(params: ImessageReadParams): Promise<any>

Send a read receipt for a conversation.

params

ImessageReadParams

required

Show properties

string

required

The recipient phone number or email address.

from

string

required

The sender phone number.

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

Get Started

Core Features

Resources

API Reference

Advanced