Connect your Signal account as a secondary device and one of your agents will reply to DMs and group messages. The integration uses the presage Rust library to speak the Signal protocol directly: Signal has no official bot API.

Bot use is not supported by Signal

Signal does not offer an official bot API. This integration links your account as a secondary device. Excessive automated use may result in your account being banned. You are responsible for any actions taken against your account.

Registering a new phone number (instead of linking) is not supported in this version. Use the linking flow only.

What you need

• A working Signal account on your phone (Signal requires a real phone number)
• Your phone within reach to scan a QR code

No public URL is required.

Connecting the channel

1. In Frona, open Settings → Channels and click Add channel.
2. Pick Signal from the provider list. The create dialog opens.
3. Fill in the dialog:
   • Space. Defaults to Signal. This is the space the conversation will live in. Keep the default to create a new space with that name, type any other name to create a different one, or pick an existing space from the dropdown. A space can host only one channel, so spaces already bound to another channel are hidden.
   • Agent. The agent that reads every incoming message and sends the reply.
   • When a message arrives. How inbound messages are handled:
     • Treat as a message from you (default). The agent runs full inference and replies.
     • Hand off to a waiting agent. The message goes to whichever task is currently waiting on a signal (e.g., a 2FA code). The agent does not reply on this channel. See Signals.
4. Click Create.

You land on the channel detail page with a QR code displayed. The Signal adapter has no config fields, so the QR linking finishes the setup.

5. On your phone, open Signal → Settings → Linked devices → Link new device and scan the QR code.
6. The connection completes automatically once the scan succeeds. If the QR expires before you scan, click Refresh on the channel page for a new one.

The channel transitions to Connected, but it won't reply yet. Pair your number next.

Pair your phone

By default the channel doesn't trust any sender, so even your own messages are ignored. Pair the channel so the agent treats a specific number as a self-source:

1. On the channel detail page, click Pair. A short code appears (e.g. XYZ-123).
2. From the phone you want to pair, send the code as a Signal message to the linked account.
3. The channel records that number as a paired address and the conversation goes live.

To pair another number, click Re-pair and repeat. To allow other contacts through, add a policy.

Configuration fields

The Signal adapter takes no configuration. The QR linking flow handles authentication.

How messages flow

• DMs to your Signal number run full inference and the agent replies in the same conversation.
• Group messages are delivered when your number is a member of the group.
• Replies are sent back to the same Signal conversation. Markdown is converted into Signal's BodyRange formatting (bold, italic, strikethrough, monospace, spoiler). Headings and tables flatten to plain text.

Signal as a fallback channel

The Signal adapter supports a fallback mode that lets other channels reuse this Signal connection for outbound delivery when their own provider is down. This is useful if you want a hardened "always reachable" path for critical agent replies. Mark a sender's dispatch mode as signal_fallback (in the per-sender authorization UI) and outbound for that sender will route over Signal instead of the original channel.

Allowlisting senders

By default only your own Signal account passes receive_message. To allow other contacts:

permit(
  principal == Policy::Agent::"assistant",
  action == Policy::Action::"receive_message",
  resource in Policy::Channel::"signal"
) when { resource.sender.address == "+15551234567" };

The address is the contact's phone number in E.164 format. See Policies for channel-wide allows and group rules.

Tips

• Treat Signal like a personal channel, not a bot platform. It works well for a single user (you) talking to your own agent. Putting it in front of customers will get the account banned.
• Keep your phone active. As a linked device, Frona depends on your primary device staying registered. If you re-install Signal on your phone, you'll need to re-link the channel.
• Markdown is limited. Signal supports only a few inline styles via BodyRange. Don't rely on tables or headings.
• Use Signal mode for 2FA capture. Switch the channel's dispatch mode to Signal and the agent won't reply, but every message will feed the signal matcher. Handy for catching codes sent to your Signal number.

Troubleshooting

Symptom	Likely cause
QR keeps expiring	Scan it faster: Signal rotates the QR after a short window. Use Refresh for a new one.
Channel Disconnected out of nowhere	The linked device was removed from your phone (Settings → Linked devices), or Signal invalidated the session. Re-link via the QR flow.
Outbound replies don't arrive	Make sure your primary Signal device (your phone) is online. Linked devices depend on the primary being reachable.
Channel Failed at startup	The stored session is corrupted or expired. Delete the channel and re-create it with a fresh QR link.

Next steps

• Channels. How channels work in general.
• Signals. Use Signal mode to capture verification codes.
• Policies. Allow specific contacts or groups.