> ## 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 to your users with fallback support, using Contiguity.

<Tabs>
  <Tab title="JavaScript" icon="js">
    ## Installing the SDK

    <Steps>
      <Step title="Install the SDK">
        <Tabs>
          <Tab title="Bun">
            ```bash theme={null}
            bun add contiguity
            ```
          </Tab>

          <Tab title="pnpm">
            ```bash theme={null}
            pnpm add contiguity
            ```
          </Tab>

          <Tab title="npm">
            ```bash theme={null}
            npm install contiguity
            ```
          </Tab>

          <Tab title="Yarn">
            ```bash theme={null}
            yarn add contiguity
            ```
          </Tab>
        </Tabs>
      </Step>

      <Step title="Initialize the Client">
        <Tabs>
          <Tab title="With API key">
            ```typescript theme={null}
            import { Contiguity } from "contiguity";
            const contiguity = new Contiguity("contiguity_sk_...your_key...");
            ```
          </Tab>

          <Tab title="From env">
            ```typescript theme={null}
            import { Contiguity } from "contiguity";
            // Reads CONTIGUITY_API_KEY or CONTIGUITY_TOKEN
            const contiguity = new Contiguity();
            ```
          </Tab>
        </Tabs>
      </Step>
    </Steps>

    ## 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"]
    });
    ```

    ### 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>

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

    ## Check iMessage availability

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

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

    ### Response

    <ResponseField name="status" type="string">
      Current status of the typing indicator action (e.g., "started", "stopped").
    </ResponseField>

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

    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>

    ### imessage.availability(params)

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

    ### 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>
  </Tab>

  <Tab title="Python" icon="python">
    ## Installing the SDK

    <Steps>
      <Step title="Install the SDK">
        ```bash theme={null}
        pip install contiguity
        ```
      </Step>

      <Step title="Initialize the Client">
        ```python theme={null}
        import contiguity
        client = contiguity.login("your_token_here")
        ```

        You can also initialize it with the optional 'debug' flag:

        ```python theme={null}
        client = contiguity.login("your_token_here", True)
        ```
      </Step>
    </Steps>

    ## Sending an iMessage

    ```python theme={null}
    # Python SDK examples coming soon
    ```

    ## Typing Indicators

    ```python theme={null}
    # Python SDK examples coming soon
    ```

    ## Parameters

    Python SDK documentation coming soon.
  </Tab>
</Tabs>

<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);
}}
/>