Skip to content
iMessage on Mac
On this page

INTEGRATIONS · IMESSAGE

Connect iMessage on your Mac

Connect selected conversations from Messages on your Mac. Assign the connection to a persona before asking it to read or send text.

Before you start

You do not enter your Apple password in PersonaStack. Setup does not need Terminal, Homebrew, or copied conversation IDs. iMessage is independent of Desktop Control. You do not need to turn on screen control.

Connect this Mac

  1. Open Integrations → iMessage in the workspace where you want the connection. Choose Connect.
  2. Choose Download for Mac if you need the app. Open the downloaded DMG. Open Install PersonaStack.pkg inside it and finish installation.
  3. Return to setup and choose Open PersonaStack. Accept the browser's open prompt. If you started on another device, choose Copy setup link and open that link on the Mac.
  4. Sign in inside PersonaStack when asked. Check the workspace shown in setup. Use Switch workspace or Switch account if it is wrong.
  5. Follow the app's next permission action. Grant PersonaStack Full Disk Access and Messages Automation access when requested. Return to PersonaStack after System Settings. Setup checks again automatically. Use Check again if needed. Use Restart and continue when offered.
  6. Choose Enable background connection when offered. Follow Open Login Items if macOS needs background approval.
  7. Choose Choose conversations. Approve Choose Conversations in the Mac confirmation to show conversation names and participants. This picker step does not read message text.
  8. Select the existing conversations you want to share. Use Search conversations or More conversations to find them. You can select up to 32 conversations.
  9. Choose Review selection. Use Choose personas if you want to prepare assignments now. You can leave this for later. Automatic replies start off.
  10. Choose Connect. In the native confirmation, check the workspace, Mac, Messages account, and conversations. Choose Read messages and Send messages deliberately. Keep at least one enabled. Selected messages can go to assigned personas and their AI providers. Sends use this Mac's Messages account. Approve Connect iMessage.

Wait for iMessage connected. Complete any prepared persona assignments with Assign. Closing setup preserves your progress. Reopen the same setup after sign-in or relaunch. If it has expired, use Start new setup. Use Retry when offered after a connection component failure.

If the Mac app shows Update PersonaStack, choose Update PersonaStack to download the update. Open the DMG and run Install PersonaStack.pkg. After installing, reopen the same setup page or link in the same account and workspace.

Assign a persona and enable incoming work

Choose Assign personas on the saved connection. Select the intended personas and choose Assign. You can also open Persona Settings and choose Integrations → Add integration. Search for the saved iMessage connection and click it. Wait for save feedback. Configuration and Wake on incoming events controls stay below the assigned connection.

A persona can use one iMessage connection. In Persona Settings, choose Remove on the current connection before adding a different one. This detaches only this persona. It does not delete the workspace connection.

If an assignment from Assign personas fails, rows marked Saved stay saved. That picker keeps your remaining persona and Wake on incoming events choices. Resolve any reported conflict and choose Assign to retry the failed rows. Check again reads the current state without retrying.

Automatic replies start off. Enable Wake on incoming events for a selected persona only when incoming messages should start work. The Mac must also finish the connection's initial receive check. A saved connection or a connected Mac alone does not prove that incoming messages are starting a persona.

Give the persona clear instructions about when to reply. Start with one selected conversation. Check its run result before relying on ongoing replies.

Manage a saved connection

The saved panel shows the Mac, Messages account, selected conversations, Read and Send access, and incoming status. It also shows how many accepted messages are waiting for personas and the age of the oldest one. Choose Refresh status to check again.

Choose Edit connection to remove conversations or turn off access. Choose Save changes to apply browser edits. Adding conversations or turning access back on requires review in the Mac app. Use Choose conversations in PersonaStack or the panel's Open PersonaStack action. Check the account and workspace before continuing.

In the Mac app, Test connection checks readiness without sending a message. It verifies incoming readiness only when reading and persona wake are active. Test send opens a message composer. Choose a selected conversation, enter text, and choose Review Message. Check the destination and exact text before Send iMessage. This sends a real message.

Use Pause in the Mac app to stop new local iMessage work immediately. Sync pending means the cloud has not acknowledged the pause. Already accepted messages may still start work before that acknowledgement. A pause does not undo a started persona run or send. Use Resume to review the connection. Resume pending means it is not ready yet.

If Message gap appears, some messages may have been missed. Choose Resume from now in the Mac app. Review the affected conversations and confirm only the ones you want to restart from now. Other selected conversations and already accepted messages keep their progress. Cancelling keeps the gap visible.

If the Messages account or message source changed, Resume from now stops for review. Choose Repair connection to start a separate repair of the same saved connection. Select conversations again and give fresh native consent. A repair does not silently reuse the previous account's selection.

If repair's result is uncertain, choose Check connection to read its current state. Use Back to connection to return to the saved panel if recovery cannot continue. Keep the connection while you follow its permission or account action. Reopen it in the correct account and workspace after sign-in or relaunch.

Disconnect removes the connection from assigned personas. Review the confirmation before continuing. It does not delete conversations from Messages.

What the connection supports

Personas can read a bounded recent message window and send text in the conversations you selected. They cannot browse unselected conversations or start a conversation with a new recipient. Selecting an existing group does not grant group-management tools.

Attachment details may identify an image, audio clip, video, or file. Attachment files are not downloaded or sent. SMS, RCS, account-wide message search, reactions, and new-recipient or group creation are unsupported.

Keep the Mac available

Closing the PersonaStack window keeps an enabled background connection running. Choosing Quit PersonaStack stops it. Reopen the app to reconnect. An enabled connection can reconnect after login or wake without creating another connection.

The Mac app's Messages menu shows connection status. Use Review Connection…, Pause Messages, or Resume Messages there. Keep PersonaStack's login item allowed in macOS for background startup.

Actual system sleep, shutdown, logout, and an offline Mac stop the relay. A dark display is different from system sleep. Do not rely on closing the lid to keep the Mac awake. Closed-lid behavior depends on the Mac's power and display setup.

After reconnection, PersonaStack can catch up from messages still available in Messages. Messages already accepted by PersonaStack can continue processing while the Mac is offline. This does not promise recovery of messages that are no longer available at the source.

Check a send before repeating it

A send requires the Mac to be available at that moment. Offline sends fail immediately. They are not queued for later delivery. Reconnecting does not send them.

Sent from Mac means Messages recorded the outgoing message. It does not prove that the recipient received or read it.

If a send's outcome is unknown, use Check status for the recent test send and inspect Messages before taking another action. Do not resend just because a response was interrupted. A fresh send can create a duplicate. After a definite offline failure, decide whether you still want a new send once the Mac reconnects.

Understand the selected data

Only the selected conversations are available through this connection. A selected group's participants can change. Review access when its membership changes. Assigned personas can pass selected message content to their configured AI providers. PersonaStack keeps encrypted incoming delivery data while it processes accepted messages. Normal persona run history is separate. Read the current Privacy Policy for data-handling terms.

When setup or replies stop

If the problem continues, use Get help. Include the visible error, failure time and timezone, connection name, and available run link. Leave message text and participant details out of a public report.

Need a hand? Contact the PersonaStack team.

Search documentation

Type a word or phrase to find a guide.

Documentation