> For clean Markdown of any page, append .md to the page URL. > For a complete documentation index, see https://docs.runtype.com/llms.txt. > For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.runtype.com/_mcp/server. # Setting up an iMessage surface Connect your Product to a Sendblue phone number so people can interact with it over iMessage. Sendblue sends your replies as iMessages and falls back to SMS for recipients who can't receive iMessage. > **Note** > > iMessage surfaces are in preview. In the production dashboard, **iMessage Channel** shows a **Coming Soon** badge in the **Add Surface** dialog, so you can't select it yet. ## Before you begin Complete these prerequisites: * Create a Product. * Create a Capability that routes to the Flow or Agent you want to run. For details, see [Adding capabilities to a Product](/user-guide/products-surfaces/adding-capabilities-to-a-product). * Create a Sendblue account and provision a phone number. * Get your API keys from the [Sendblue dashboard](https://sendblue.co/dashboard). ## Create the iMessage surface To create an iMessage surface, follow these steps: 1. In the dashboard, open the Product that you want to connect to iMessage. 2. On the Product page, go to **Surfaces** and click **Add Surface**. 3. In **Messaging Channels**, click **iMessage Channel**. 4. In the surface panel, click the **Inbound** tab. 5. Enter the Sendblue **API Key ID**. 6. Enter the Sendblue **API Secret Key**. 7. Enter the Sendblue **Phone Number** in E.164 format, for example `+18005550100`. 8. Click the **General** tab. 9. In **Capability**, select the Capability that handles incoming messages. 10. In **Status**, select **Active**. A surface in any other status ignores incoming messages. 11. Click **Save Changes**. When you save, Runtype checks the API Key ID and API Secret Key with Sendblue. If they're invalid, the save fails with **Invalid Sendblue credentials**. ## Connect the Sendblue webhook You don't paste a URL into Sendblue. When you save the surface, Runtype registers the surface's **Webhook URL** with Sendblue for you, together with a signing secret. After that, the surface accepts only deliveries that carry the matching secret. If your Sendblue account already has a webhook for this URL, Runtype doesn't replace it, so that webhook doesn't send the signing secret and the surface rejects its deliveries. To fix this, delete that webhook in the Sendblue dashboard. Then, on the **Inbound** tab, enter the **API Secret Key** again and click **Save Changes**. The **Save Changes** button appears only after you change a field. ## Choose when the surface answers in groups The **Channel response mode** setting on the **Inbound** tab decides when the surface answers in a group conversation. Through the API, set `inbound.channelResponseMode`. * **Mention only** (`mention`): the default. The surface answers a group message that includes its phone number or the word `bot`, or that replies to one of its messages. * **Every message** (`always`): the surface answers every group message, with no mention or reply required. * **Judged** (`judge`, API only, in preview): the surface answers a mention or a reply to one of its messages. For any other group message, a judgment model decides whether to reply, using the optional `responseRules`, `eagerness`, and `onUncertain` settings described in [Judge mode](/user-guide/products-surfaces/setting-up-a-slack-surface#judge-mode). If the judgment fails, the surface waits for a mention. To test the judgment without changing behavior, set `inbound.responseGateShadow` to `true`. The surface records the judged decision for each group message that doesn't address it and answers as its mode says. If the surface has two or more enabled Capabilities and no entry point, a judgment model also chooses which Capability answers. See [Surfaces with several Capabilities](/user-guide/products-surfaces/setting-up-a-slack-surface#surfaces-with-several-capabilities). ## Include earlier group messages as context When the surface answers in a group conversation, it also receives recent group messages that aren't yet in the conversation, for example the messages sent before the conversation started. The surface receives these messages as context only and doesn't reply to them. The `inbound.contextBackfill` setting controls this behavior: * **`mode`**: `window` (the default) includes the recent messages. `judged` includes only the messages that a judgment model finds necessary to understand the answered message. `none` includes no earlier messages. * **`maxMessages`**: the maximum number of messages. The default and maximum is 20. * **`maxAgeMinutes`**: the maximum message age in minutes. The default is 360 and the maximum is 1440. In `judged` mode, the surface always keeps messages from the person who activated it, messages that mention it, and its own messages. A marker shows where messages were left out. If the judgment fails, `judged` mode includes the messages that `window` mode includes. ## Use tool approval iMessage has no approval buttons. To use **Tool approval** with an attached Runtype Agent, enable **Agent loop** and set **Max turns** to 2 or higher. A Managed external Agent already supports multi-turn tool approval and doesn't need an authored **Agent loop** or **Max turns** setting. Reply to the approval request to approve or deny the tool call. Runtype accepts a reply as an approval decision only from a delivery that carries the surface's Sendblue signing secret. If the secret is missing or doesn't match, the tool doesn't run. For reply syntax and approval limits, see [Approvals on messaging surfaces](/user-guide/products-surfaces/approvals-on-messaging-surfaces). ## Test the connection To test the connection, follow these steps: 1. Send an iMessage from your phone to the Sendblue phone number. 2. Confirm that a response arrives in the same conversation. If you receive a response, the iMessage surface is ready to use. ## Troubleshoot common issues Use these checks when the surface doesn't respond: * **The save fails with Invalid Sendblue credentials**: Copy the API Key ID and API Secret Key again from the Sendblue dashboard, and then save. * **The surface doesn't receive messages**: Confirm that **Status** is **Active**, and that the **Phone Number** matches your Sendblue number. In the Sendblue dashboard, confirm that the surface **Webhook URL** is listed. If it isn't, enter the **API Secret Key** again and click **Save Changes** to register it. * **The surface panel shows Inbound events are being rejected**: Sendblue deliveries don't carry the surface's signing secret. Read the reason in the banner. Confirm that the Sendblue webhook points directly at the surface **Webhook URL**. If Sendblue has an older webhook for this URL, delete it, and then register the webhook again as described in [Connect the Sendblue webhook](#connect-the-sendblue-webhook). * **The surface receives messages but sends no response**: Confirm that the selected Capability routes to the intended Flow or Agent. * **A group conversation gets no response**: Check the **Channel response mode**. In **Mention only** mode, the message must address the surface. ## Next steps Continue with these guides: * [Approvals on messaging surfaces](/user-guide/products-surfaces/approvals-on-messaging-surfaces): approve or deny tool calls by reply. * [Setting up a Slack surface](/user-guide/products-surfaces/setting-up-a-slack-surface): configure judge mode and multi-Capability routing. * [Setting up an SMS surface](/user-guide/products-surfaces/setting-up-an-sms-surface): connect a Twilio number for text messages. * [What are Surfaces?](/user-guide/products-surfaces/what-are-surfaces): compare the available surface types. * [Surface orchestration modes](/user-guide/products-surfaces/surface-orchestration-modes): route input when a surface exposes multiple Capabilities.