Products & Surfaces

Setting up an iMessage surface

Connect your Product to a Sendblue phone number so people can interact with it over iMessage. Sendblue delivers blue-bubble iMessage messages and falls back to SMS for recipients who cannot receive iMessage.

Before you create the surface, complete these prerequisites:

  • Create a Product.
  • Choose the Capability that handles incoming messages.
  • Create a Sendblue account and provision a phone number.
  • Get your API keys from the Sendblue dashboard.

iMessage surfaces are in development preview. Create them in the development environment. In production, the dashboard labels them Coming Soon, and the API rejects them.

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 iMessage configuration panel, enter the Sendblue API Key ID.
  5. Enter the Sendblue API Secret Key.
  6. Enter the Sendblue Phone Number in E.164 format, for example +18005550100.
  7. Click Save changes. The surface saves, and Runtype attempts to register the webhook with Sendblue.

Configure the Sendblue webhook

After you save the surface, Runtype attempts to register the surface’s Webhook URL with Sendblue. You do not paste a URL into Sendblue for the standard setup. When registration succeeds, Runtype stores a signing secret and checks the sb-signing-secret header on inbound deliveries. It rejects deliveries with a missing or invalid header. If the URL is already registered or registration fails, Runtype does not store a new secret. Reply-based approval remains unavailable until the surface has a matching secret.

Attach a Capability

Attach the Capability that handles incoming messages. The Capability routes messages to the Flow or Agent that you want to run. If you have not attached a Capability, see Adding capabilities to a Product.

For group conversations, include the surface phone number or the word bot to address the surface. The surface also responds to a reply to one of its messages.

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 executes through an effective Runtime Agent Loop and does not need an authored Agent Loop or Max turns setting. Reply to the approval request to approve or deny the tool call. Runtype interprets your reply as an approval or denial.

Runtype accepts a reply as an approval decision only after it verifies the Sendblue signing secret. If verification fails, the approval flow fails closed and the tool does not run. No additional iMessage setting is required. 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 the message reaches your Product.
  3. Confirm that the response returns to the conversation.

If you receive a response, the iMessage surface is ready to use.

Troubleshoot common issues

Use these checks when the surface does not respond:

  • The surface does not receive messages: Verify that the Phone Number matches your Sendblue number. If the surface has a signing secret, Sendblue must send the matching sb-signing-secret header.
  • The surface receives messages but sends no response: Attach a Capability and confirm that it routes to the intended Flow or Agent.
  • A group conversation gets no response: Include the surface phone number or bot, or reply to a message from the surface.

Next steps

Continue with these guides: