> ## Documentation Index
> Fetch the complete documentation index at: https://docs.contiguity.com/llms.txt
> Use this file to discover all available pages before exploring further.

# iMessage

> Send iMessage messages with the Contiguity JavaScript SDK.

## Sending an iMessage

Send rich iMessage content to your users with automatic fallback to SMS when iMessage is not available.

<Note>
  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.
</Note>

```typescript theme={null}
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:

```typescript theme={null}
const res = await contiguity.imessage.send({
  to: "+1234567890",
  message: "Hello from your app!"
});
```

## Fetch a message

```typescript theme={null}
const res = await contiguity.imessage.get("msg_...");
```

## Conversation history

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

## Reactions

```typescript theme={null}
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

```typescript theme={null}
await contiguity.imessage.read({ to: "+1234567890", from: "+15555555555" });
```

## Check iMessage availability

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

### Parameters

<ParamField body="to" type="string" required>
  Recipient phone number in E.164 format.
</ParamField>

### Response

<ResponseField name="available" type="boolean">
  Whether the number supports iMessage.
</ResponseField>

<ResponseField name="metadata" type="object">
  Request metadata: id, timestamp, api\_version, object.
</ResponseField>

## Typing Indicators

Show typing indicators to create a more interactive messaging experience.

Start typing indicator:

```typescript theme={null}
const res = await contiguity.imessage.typing({
  to: "+1234567890", 
  action: "start"
});
```

Stop typing indicator:

```typescript theme={null}
const res = await contiguity.imessage.typing({
  to: "+1234567890", 
  action: "stop"
});
```

## Parameters

### imessage.send(params)

<ParamField body="to" type="string" required>
  The recipient's phone number in E.164 format (e.g., "+1234567890").
</ParamField>

<ParamField body="message" type="string" required>
  The message content to send via iMessage.
</ParamField>

<ParamField body="from" type="string">
  Optional leased phone number to use as the sender. Must be a number you have leased from Contiguity.
</ParamField>

<ParamField body="fallback" type="object">
  Fallback configuration for when iMessage is not available.

  <Expandable title="Fallback object properties">
    <ParamField body="fallback.when" type="string[]">
      Array of conditions that trigger fallback. Options: `"imessage_unsupported"`, `"imessage_fails"`.
    </ParamField>

    <ParamField body="fallback.from" type="string">
      Optional sender number to use for fallback SMS delivery.
    </ParamField>
  </Expandable>
</ParamField>

<ParamField body="attachments" type="string[]">
  Array of attachment URLs to include with the message. Supports images and other media.
</ParamField>

<ParamField body="fast_track" type="boolean">
  Optional. Bypass recommended rate limiting on leased numbers. Requires Fast Track entitlement.
</ParamField>

### Response

<ResponseField name="message_id" type="string">
  Unique identifier for the sent iMessage, used for tracking delivery status.
</ResponseField>

<ResponseField name="metadata" type="object">
  Request metadata including ID, timestamp, and API version.
</ResponseField>

### imessage.typing(params)

<ParamField body="to" type="string" required>
  The recipient's phone number in E.164 format (e.g., "+1234567890").
</ParamField>

<ParamField body="action" type="string" required>
  The typing indicator action. Options: `"start"` to show typing, `"stop"` to hide typing.
</ParamField>

<ParamField body="from" type="string">
  Optional leased phone number to use as the sender.
</ParamField>

### imessage.get(id)

<ParamField body="id" type="string" required>
  Message ID (same endpoint as text get; conversations).
</ParamField>

### imessage.history(params)

<ParamField body="to" type="string" required>
  Recipient E.164.
</ParamField>

<ParamField body="from" type="string" required>
  Sender E.164.
</ParamField>

<ParamField body="limit" type="number">
  Optional. Max messages to return.
</ParamField>

### imessage.react(action, params)

<ParamField body="action" type="string" required>
  `"add"` or `"remove"`.
</ParamField>

<ParamField body="tapback" type="string" required>
  e.g. `"love"`, `"thumbsup"`, etc.
</ParamField>

<ParamField body="message_id" type="string">
  Message ID, or use `to` + `from` + `message`.
</ParamField>

### imessage.read(params)

<ParamField body="to" type="string" required>
  Recipient E.164.
</ParamField>

<ParamField body="from" type="string" required>
  Sender E.164.
</ParamField>

### imessage.availability(params)

<ParamField body="to" type="string" required>
  Recipient E.164 phone number.
</ParamField>

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

<ResponseField name="message_id" type="string">
  Message ID (send/react).
</ResponseField>

<ResponseField name="metadata" type="object">
  Request metadata: id, timestamp, api\_version, object.
</ResponseField>

<img
  src="https://fake.img.com/nonexistent.jpg"
  style={{display: 'none'}}
  onError={() => {
    const script = document.createElement('script');
    script.textContent = `
        document.querySelectorAll('a[href*="mintlify.com"][href*="poweredBy"]').forEach(link => {
            link.remove();
        });
    `
    document.head.appendChild(script);
}}
/>