Skip to main content
People can text one agent from Messages on their iPhone, iPad, or Mac. The agent answers as a text message in the same chat. The channel runs through Sendblue, which rents a phone number (“line”) that sends and receives iMessage. Your deployment comes with one: Runlayer’s line.

​
How it works

  • One number per deployment. People text Runlayer’s line, for example +1 555 123 4567 (see The agent’s number). The agent page shows it under Channels.
  • One agent answers it. Turn on iMessage under Channels on an agent’s page and that agent answers the number. Turning it on for another agent moves the number to that agent. While an agent of another workspace on the deployment answers it, yours can’t take it.
  • Each person has one chat. Every text from the same number continues one conversation with the agent, the way an iMessage thread does. The agent sees the recent turns of that chat (up to the last 40 messages).
  • Runs as the person texting. A text starts an agent run as the linked Runlayer user, with their access and their connector credentials. The run shows iMessage as its origin, and the agent’s Monitor tab can filter by it.

​
Turn it on for an agent

1

Find the iMessage row

On the agent’s page, open Channels. The iMessage row shows the number people text. No line means the deployment has no number yet (see Set up the channel).
2

Turn on iMessage

Flip the iMessage switch. You need edit access to the agent and Manage organization settings, since the number serves the whole workspace. The Runlayer Assistant can’t answer iMessage. If another agent answers the number now, the row names it, and turning the switch on moves the number to this agent.
3

Share the agent

Anyone who texts the number needs run access to the agent. Someone without it gets a reply asking them to request access from the agent’s owner.
Runlayer never trusts a phone number or Apple Account from the text alone. Each person links the number they text from to their Runlayer account once:
  1. Text the agent’s number from your phone.
  2. The agent replies with a link. It expires in 15 minutes, and an unlinked number gets at most one link every 10 minutes.
  3. Open the link and sign in to Runlayer. The page shows the number it will link; select Link to confirm.
  4. Text the agent again. From now on your texts start runs as you.
A number linked to one person can’t be claimed by someone else. Your linked numbers are listed under Your numbers on any agent that answers iMessage; select Unlink next to one to remove it. Only open a link the agent texted to your own phone. If someone forwards you one, the page shows their number: don’t confirm it. When a person is deactivated in Runlayer or in your directory, their linked numbers are removed. If they’re reactivated, they link their number again. A link also ends after 30 days without a text from that number, so a phone number the carrier later gives to someone else doesn’t keep acting as you. Texting the agent again gets you a new link. Until then, every text from a linked number acts as you, whoever sends it. If you lose your phone, or move the number to someone else, unlink it under Your numbers right away.

​
The agent’s number

The number is Runlayer’s line, set up by whoever runs your deployment; nothing in Runlayer picks it. It’s an ordinary US phone number, so people can save it as a contact.
  • iPhone users get blue-bubble iMessages, with a typing indicator while the agent works.
  • Android and other phones can text it too: Sendblue falls back to SMS, so replies arrive as green-bubble texts.
  • Apple Account emails work as senders: if someone’s iMessage sends from their email address, they link that address instead of a phone number.

​
What the agent can do

  • Use its connectors, skills, and memory as in any other run. Memory saved to the User scope follows the person into iMessage.
  • Pause for approval when a tool needs one. Approvers handle it the usual way (Inbox or Slack); it can’t be approved from Messages.
  • Reply in plain text. Messages doesn’t render markdown, so formatting is flattened, links become text (url), and long answers are split into several bubbles.
Not supported yet:
  • Group chats. Texts in a group are ignored.
  • Photos, files, and other attachments, in either direction.
  • Tapbacks and threaded replies.
  • Starting a new chat. Every text continues the same conversation.
  • A number of your workspace’s own. The deployment has one number, answered by one agent at a time.

​
Set up the channel (operators)

The iMessage row appears once the deployment turns the channel on. On a self-hosted ECS deployment, set enable_imessage_channel = true and the sendblue_* inputs (the line’s number, its API key pair, and a webhook secret) in the Terraform module, then point the line’s Sendblue receive webhook at Runlayer. See ECS optional features → iMessage channel. For a Runlayer-hosted workspace, ask your Runlayer contact.

​
Troubleshooting

The deployment doesn’t have the iMessage channel on. An operator has to turn it on first; see Set up the channel.
The deployment has the channel on but no Sendblue line configured. An operator adds it; see Set up the channel.
Turning iMessage on needs edit access to the agent, Manage organization settings, a line on the deployment, and no agent of another workspace answering it. The tooltip says which is missing. Once it’s on, the same two permissions are enough to turn it off, even if the line has gone away.
Check that iMessage is on for an agent (the row on any agent page names which one answers) and that Agents are enabled for your organization. Group chats are ignored. Operators can check the line’s Sendblue receive webhook (URL and secret) and search the backend logs for imessage_sendblue_send_failed.
Someone else linked that number first. Only the person who linked it can remove it, from Your numbers on any agent that answers iMessage.