Skip to navigation
Products & Surfaces

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.

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

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.

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.
  • 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: