Skip to content

chats.md

Latest commit

 

History

History
112 lines (77 loc) · 5.85 KB

chats.md

File metadata and controls

112 lines (77 loc) · 5.85 KB
Raw
title Chats
description List recent conversations and inspect a single chat's identifiers, participants, and routing hints.

imsg chats lists conversations sorted by most recent activity. imsg group zooms in on one chat. Both work for direct chats and group threads.

List recent chats

imsg chats --limit 20
imsg chats --limit 20 --json | jq -s

Columns (text mode): id, name, service, last_message_at.

Text output prefers a resolved contact name for direct chats, then the Messages display name or raw chat identifier.

Empty and missing Messages display names fall back to the raw chat identifier, including when Contacts is unavailable over SSH. JSON exposes a resolved Contacts match separately as contact_name in both chats and RPC chats.list. Contacts over SSH can resolve these names with Full Disk Access even when Contacts.framework has no grant. The presentation fallback belongs to name: an empty stored title remains empty in JSON display_name and chat-detail metadata.

Inspect one chat

imsg group --chat-id 42
imsg group --chat-id 42 --json

Use this before scripting a send. It returns identifier, GUID, service, participants, group/direct flag, and account routing hints in one shot.

imsg group works for direct chats too, despite the name. Treat it as "chat detail," not "groups only."

Chat list object

Objects returned by imsg chats --json and JSON-RPC chats.list include:

Field Type Notes
id int chat.ROWID. Stable within one Messages database. Preferred routing handle.
name string Messages display name or raw chat identifier fallback.
display_name string Chat title metadata. An empty stored title remains empty.
contact_name string Resolved name from Contacts.framework or the readable AddressBook store over SSH.
identifier string chat.chat_identifier — Messages' portable handle.
guid string chat.guid — Messages' portable GUID.
service string iMessage, SMS, etc.
last_message_at ISO8601 Newest activity in the chat.
is_group bool True when identifier or guid contains ;+;. See Groups.
participants array External handles only. The local user is implicit; see below.
account_id string Routing diagnostic. Read-only.
account_login string Routing diagnostic. Read-only.
last_addressed_handle string Routing diagnostic. Read-only.
unread_count int Count of unread inbound messages in the chat. Omitted on older database schemas without read state.

Routing identifiers — which one to use

Three handles can identify a chat. Pick by use case:

  • chat_id (rowid): preferred. Fastest, most stable within one database. Use this whenever both reader and sender are on the same machine.
  • chat_identifier: portable across DBs/installs. Use when you store handles externally and need to tolerate a Messages reset.
  • chat_guid: also portable. Same use cases as chat_identifier.

For sends, imsg send --chat-id is preferred. --chat-identifier and --chat-guid are fallbacks for callers that only have the portable handle.

Participants vs. local identity

participants lists external handles only. The local user is intentionally absent because Messages stores it implicitly per-message rather than on the chat row.

To distinguish your own messages from others':

  • Use is_from_me on each message.
  • For multi-number Apple IDs, check destination_caller_id on outgoing messages — it tells you which of your numbers Messages routed through.

account_id, account_login, and last_addressed_handle are diagnostic reads from Messages. AppleScript's send does not let imsg force a specific outbound number when several phone numbers share one Apple ID. The fields are there so you can audit what Messages picked, not steer it.

Filtering tips

imsg chats takes one filter flag, --unread-only, which returns only chats with unread inbound messages:

imsg chats --unread-only --json

On an older Messages database without a read-state column, --unread-only fails clearly instead of reporting an empty inbox.

For anything else, pipe through jq or grep for ad-hoc filtering:

imsg chats --json | jq -s 'map(select(.is_group == true))'
imsg chats --json | jq -s 'map(select(.service == "SMS"))'

For more targeted history queries with date and participant filters, use imsg history.

Create an iMessage chat

chat-create requires the injected bridge on a SIP-disabled Mac with an active iMessage account:

imsg chat-create --addresses '+15551111111,+15552222222' --json
imsg chat-create --addresses 'friend@example.com' --json

Replace the examples with real recipients. Previously uncontacted numbers and email addresses work without adding a contact or entering them in Messages.app's New Message → To: field first. The bridge reuses registered iMessage handles, creates missing ones through the active account, and checks their canonical addresses with IDS.

Every address must resolve and have confirmed iMessage availability. If IDS reports a recipient is not reachable, the command names that address and stops before creating, naming, or sending to a chat. An unresolved IDS result produces a separate error asking you to check the account and connection, then retry. A failed recipient is never silently dropped from a group. chat-create does not fall back to SMS; use imsg send --service sms for an intentional SMS send.

--name sets the chat display name; --text sends an initial message. Omit both when checking creation without sending a message or group-name update. The result includes chatGuid and the requested participants; an empty chat may not appear in the recent-chats list until it has activity.