# Make a conversation Textmock is an editor for iMessage-style conversations. Write both sides, or text a fictional character on a device that can run replies. Save the conversation as an image or a video. ## Make your first image 1. Open [Textmock](https://textmock.com). 2. Tap a message and replace its words. 3. Type another message in the message bar. The sender switch lets you write either side. 4. Open the menu with the button at the top right. It shows **⋯** at first and looks like a video-call button once you’ve used it. Choose **Save Image**, or **Make Video** to save the conversation playing out. The image is drawn at the selected phone's full resolution. Conversations and their photos stay on your device. A share link carries a copy in its URL fragment, which the browser does not send to the server. ## Shape the conversation Tap the name, photo, clock or a message to edit it. Message options include tapbacks, replies, delivery state, edited and unsent messages, formatting, text effects and sending later. The **+** menu adds photos, videos, voice notes, links, files, locations, contacts, stickers and polls. Conversation settings cover groups, iMessage/SMS/RCS, typing indicators, backgrounds, screen effects, receipts, phone size and text size. Light and dark modes change the conversation's appearance. On supported devices, an on-device model can write replies for the other person; you can also write both sides yourself. ## Start with a character Check the [local-reply setup guide](https://textmock.com/local-ai-chat-setup) for Chrome availability, Apple Intelligence requirements and optional Gemma download controls on Mac. You can write both sides without a model. Where replies are available, **Start with a Character** offers six made-up people to text: a hype friend, a dry older brother, a grandmother new to texting, a game master who runs a short text adventure, a coach for planning your day or rehearsing a hard conversation, and a grumpy cat. It is under **Getting started** in a short conversation list and in the **⋯** menu. Picking one starts a new conversation with their name, a description of who they are and their first texts. A character is an ordinary conversation. Rewrite who they are in **Conversation Settings**, change their name or edit any message. Their replies are written by the on-device model, like any other conversation's; they are not real people, and the coach is not a therapist or an expert. A character counts as a conversation, so Textmock Pro's limit on more than one applies in the same way. ## Shape a character’s personality In the web editor and Mac app, open **Conversation Settings**, then **Shape Their Personality**. Describe who they are, your relationship and how they text. The style suggestions add words you can change. If you already have a description, **Add to Current Description** keeps it intact. Choose **Replace Current Description** to start a replacement. **Review Draft** shows the full description; edit it before choosing **Apply Personality**. Cancel leaves the saved description alone. The limit is 1,000 characters, and a draft that is too long stays available for you to shorten. The personality description is included in share links by default. Put private preferences or personal details in **What They Remember** instead. ## Choose what a character remembers In the web editor and Mac app, choose **Remember This** from a message’s options to keep its words as a note. The first note saves directly; **Edit** in the confirmation opens it in settings. A long message is shortened to fit and marked as shortened. When the conversation already has notes, Remember This shows the proposed note first. Choose **Add a New Note**, or **Replace This Note** beside the outdated note you want to replace. Cancel keeps your notes as they are. To write a note yourself, open **Conversation Settings**, then **What They Remember**. Choose **Add a Note** and write a detail you want available during the conversation. For example: “I drink tea now. Sam and I call the kettle Mission Control.” Tap outside the note to save it on this device. Edit or replace the note when the detail changes. If an old note says “I drink coffee,” replace that note with the tea preference, so both do not remain in the list. The remove button deletes one note; **Clear Notes** removes the whole list. Each conversation holds up to 16 notes of 240 characters each. At the limit, you can replace a note or remove one before adding another. The app does not add or replace notes automatically. The reply model uses relevant notes alongside recent messages and older passages. It can miss a detail, and removing a note does not erase the original messages. Notes stay out of share links, excerpts and the agent interface, and are not passed to other conversations. ## Look up a topic or read a link In the web editor and Mac app, **Look Something Up** is in the main menu. It is free and needs no account. Ordinary chat does not trigger lookups. 1. Choose **Search Wikipedia**, enter a topic such as “moon phases,” and submit. Search returns excerpts from English Wikipedia. Or choose **Read a Link**, enter a public HTTPS address and choose **Read Page**. 2. Select a result to use its excerpt. **Read this result** fills in the page address; choose **Read Page** to request the page itself. You can also start from **Read a Link** on a link message. 3. Under **Ask your character**, write a question such as “What surprised you?” Choose **Send and Discuss** to put the question and source link in your thread. The reply is written on your device using a short excerpt. 4. Open **Source** to read the original yourself. If the device cannot write replies, you can still open the sources. Only the submitted query or address goes to Textmock’s service and Wikipedia or the requested website. Your question, conversation, character description and notes are not included. The excerpt is used for that reply and is not saved as a memory. Lookups have usage and page-size limits; pages that need a login, scripts or unsupported formats may not provide useful text. A reply can misunderstand an excerpt, so use the source link to check it. See [Privacy](https://textmock.com/privacy) for data handling. ## Save and share Save an image or video, or share a link to an editable copy. Textmock Pro removes the badge from saved images and videos and allows more than one conversation. It is $5 a month on the website and in the Mac app, and $4.99 a month in the App Store, which shows the local price before purchase; a purchase is not needed to try the editor. The website works on desktop, tablet and phone screens. The iPhone and Mac apps use the same conversation renderer. Mac imports stay local and require you to choose the conversation; examples in these docs use original synthetic conversations. ## Shape a private character chat Use the [private character chat guide](https://textmock.com/private-ai-character-chat) to start a conversation in the web editor or Mac app. The practical guides walk through [correcting a memory](https://textmock.com/ai-character-memory), [crafting a texting personality](https://textmock.com/ai-character-personality), [where private chat data goes](https://textmock.com/private-ai-chat-privacy), and [discussing a public source](https://textmock.com/ai-character-web-lookup). The worked conversations are authored examples. Actual replies vary by model and context; a saved note does not guarantee recall. Private notes stay out of share links, while a character’s description is included by default. ## Write a story or reuse a fixture The [text-story workshop](https://textmock.com/write-a-text-story) works through an original eight-message scene, with the exact conversation ready to copy and edit. The [conversation UI fixture pack](https://textmock.com/conversation-ui-fixtures) offers four fictional JSON conversations for design samples and repeatable interface checks, free to reuse. The [local memory development study](https://textmock.com/local-ai-memory-evaluation) publishes exact synthetic prompts and outputs, including failures. It supports limited observations about explicit note correction, not general model accuracy or complete chat performance. ## Work with an agent Agents can make and edit conversations directly, under the same Pro rules as a person. They use `window.textmock` in the editor at [textmock.com](https://textmock.com/) or in a native app, after the API is ready. Marketing and documentation pages do not expose it. Textmock for Mac 1.0.14 and later also provide a `textmock` command. Either interface can create a conversation, send messages, add reactions, and render the image or video. Listing, importing and syncing Messages requires the Mac app and the person's permission. See [Use Textmock from an agent](/docs/agents) for readiness, platform and permission details, and the [conversation formats](/docs/conversation-format) for the document. Source: https://textmock.com/docs --- # Use a coding agent Claude Code, Codex, OpenCode and other agents can make and edit Textmock conversations directly. Browser agents use the `window.textmock` API on [textmock.com](https://textmock.com). Textmock for Mac 1.0.14 and later also include a `textmock` command. Both expose the same methods and return the same JSON, and both follow the same Textmock Pro rules as a person using the app. ## Make an editable text link For a fictional, text-only conversation, the [Textmock link helper](https://textmock.com/integrations/textmock-link.mjs) runs locally with Node.js 24 or later. Save the script as `textmock-link.mjs`, then run: ```sh node textmock-link.mjs - <<'JSON' {"name":"Mira","messages":[{"from":"them","text":"Did you bring the telescope?"},{"from":"me","text":"Yes. You bring the clear sky."}]} JSON ``` Open the printed link and choose **Make a Copy** to edit the conversation and save an image or video. Creating the link and viewing its preview change no saved conversation. Making a copy adds it if there is room; an untouched starter can be replaced, while an existing edited conversation is preserved when the free conversation limit is reached. The helper accepts `name`, `messages`, optional `dark` and optional `clock`. Each message has `from` (`me` or `them`) and `text`. It supports one-to-one conversations, up to 120 messages and 4,000 characters per message, within a 180 KB JSON document limit. Replies are off in the new copy. It refuses unknown fields, photos and private notes. Use the APIs below for the app's broader editing and rendering features. The helper encodes the conversation in the fragment after `#`, which browsers omit from navigation requests. Anyone with the full link can read it, so avoid putting private links in logs or public output. The helper and the coding-agent skill are MIT-licensed; the [integration bundle](https://textmock.com/integrations/textmock.json) contains their source and license. Textmock's application terms still apply. ## The `textmock` command (Mac) [Textmock for Mac](https://textmock.com/mac) includes the command from version 1.0.14. To put it on your PATH, open the app and choose **Textmock › Install Command-Line Tool…**. It links `/usr/local/bin/textmock`, or `~/.local/bin/textmock` when `/usr/local/bin` isn't writable, to the copy inside the app, so each update brings a new version of the command too. You can also run it in place at `/Applications/Textmock.app/Contents/Helpers/textmock`. ```sh textmock help # every method, the conversation format and the limits textmock status # Pro, how many conversations, which is open textmock create '{"name": "Robin", "messages": [{"text": "you up?"}, {"text": "always"}]}' textmock send '{"text": "omw"}' # `from` alternates when left out textmock react -1 ❤️ # a tapback on the latest message textmock render --out robin.png # the image, as Save Image makes it textmock render '{"format": "mp4"}' --out robin.mp4 ``` Each command runs one method in the app and prints its result as JSON: pretty in a terminal, one line when piped. If the app isn't running, the command starts it in the background. Changes show up in the app's window right away. Changes to the open conversation can be undone with ⌘Z; creating, deleting, and changing a conversation that isn't open can't. - **Arguments:** an argument that parses as JSON is used as JSON (a number, an object, or a `"quoted string"`). Anything else is passed as a plain string. `-` reads one JSON value from stdin. After `--`, nothing is read as a flag. - **Sent once:** the command sends a request again only while the app isn't ready to run it. If the connection drops after the app has it, the command fails rather than risk running it twice; `textmock list` shows where things stand. - **render:** writes the file to `--out` and prints its path, size, and whether it carries the badge. A file given to `--out` is replaced if it exists. A folder, or a path ending in `/`, which is created if needed, gets the name the app suggests, numbered (`Robin 2.png`) rather than replacing a file. Without `--out`, the same goes for the current folder. - **Errors:** an error prints `{"code", "message", "details"}` to stderr and exits with a status for its code: | Exit | Code | Meaning | | --- | --- | --- | | 2 | `invalid` | The arguments or document don't validate. `details` lists each problem, for example `Message 2: replyTo must name an earlier message`. | | 3 | `not_found` | No conversation or message has that id or index. | | 4 | `pro_required` | Only Textmock Pro allows more than one conversation. | | 5 | `full` | The library is at its limit. | | 6 | `unavailable` or `denied` | The app isn't installed or Pro isn't on sale (`unavailable`), or the person declined, or Textmock lacks Full Disk Access (`denied`). | | 1 | anything else | Any other failure. | The command connects to the app through a socket that only your user account can open, at `~/Library/Application Support/Textmock/agent.sock`. Each request is one line of JSON, `{"method": "send", "params": [...]}`, and each answer is one line, `{"ok": true, "result": ...}` or `{"ok": false, "error": {...}}`. An agent that prefers to can speak this protocol to the socket directly. ### Importing from Messages ```sh textmock chats '{"search": "Robin"}' # conversations in Messages textmock import # a new conversation that follows that chat textmock sync # pick up what's new since then ``` Messages is protected by Full Disk Access, which belongs to Textmock and not to the terminal. So the first time in each launch that an agent lists, imports or syncs, Textmock asks the person whether to allow it. If they decline, or Textmock doesn't have Full Disk Access, the command fails with `denied`. Imports run one at a time, and importing a chat that's already imported syncs it instead. Imported conversations stay on the Mac. ## In a browser: `window.textmock` Open the editor at [textmock.com](https://textmock.com/), or the editor bundled into the iPhone or Mac app. Marketing pages and `/docs` explain the product; they do not define `window.textmock`. The editor defines the API once it loads and knows what Textmock Pro allows, waiting at most five seconds for the account check. It then fires `textmock:ready` on `window`. Check for an API that is already ready before listening for the event. This example runs in the editor's page context and stops with an error if that page does not become ready within ten seconds: ```js await new Promise((resolve, reject) => { if (window.textmock) return resolve(); const ready = () => { clearTimeout(timeout); resolve(); }; const timeout = setTimeout(() => { window.removeEventListener("textmock:ready", ready); reject(new Error("Open the Textmock editor and wait for it to load.")); }, 10_000); window.addEventListener("textmock:ready", ready, { once: true }); }); const { id } = await textmock.create({ name: "Robin", messages: [{ text: "you up?" }, { text: "always" }] }); await textmock.send(id, { from: "me", text: "omw" }); const png = await textmock.render(id, { format: "png" }); // { mime, base64, width, height, badge } ``` Calls that change conversations, and `render`, run one at a time in the order they're made, so calls started together behave as if each waited for the one before. The methods throw an `Error` with `code`, `message` and `details`. `textmock.call(method, params)` never throws: it returns `{ ok, result }` or `{ ok: false, error }`, the same shape the socket uses. `chats`, `import` and `sync` require the Mac app's Messages bridge and the person's permission; on the website and in the iPhone app they fail with `unavailable`. Check `textmock.status().platform` before choosing a platform-specific workflow. ## Reusable inputs The [conversation UI fixture pack](https://textmock.com/conversation-ui-fixtures) provides four complete fictional conversation documents, exact preview links and suggested layout checks. Use one individual JSON document or a pack entry’s `doc` field with the broader editing API; the outer pack is an index, and the text-only link helper above accepts neither the pack nor these full documents. No private notes or imported messages are included. ## Methods `textmock help` (or `textmock.help()`) is the full reference. It is generated from the code, so it always matches the version you have. | Method | What it does | | --- | --- | | `status()` | The platform, whether Pro is active, the conversation count, whether there's room for another, and which conversation is open. | | `list()`, `get(id?)` | Summaries, or one conversation's document with private memory notes omitted. Without an id, `get` returns the open conversation. | | `create(doc?, {open})`, `set(id, doc)`, `update(id, fields)` | Make a conversation, replace one, or change its top-level fields. A partial document is filled in. | | `send(id, messages)`, `insert(id, at, messages)` | Add messages at the end or at a position. | | `edit(id, ref, fields)`, `remove(id, ref)` | Change or remove one message. `ref` is its id or its index; `-1` is the latest. | | `react(id, ref, emoji \| null, from?)` | Add a tapback, or remove one with `null`. | | `open(id)`, `delete(id)` | Show a conversation, or delete it. | | `render(id?, {format, scale, dark, video})` | The PNG or MP4 that Save Image or Make Video would produce. `dark` overrides the conversation's appearance. The suggested file name is the conversation's name. | | `upgrade(reason?)` | Show the Textmock Pro offer to the person, for more conversations (`"conversations"`, the default) or for saving without the badge (`"badge"`). Fails with `unavailable` when Pro isn't on sale. | | `chats()`, `import(chat)`, `sync(id)` | Bring in conversations from Messages (Mac only). | Messages accept names: a `from` of `"Robin"` resolves to the contact or group member with that name. Photos accept `data:` URLs. A document that doesn't validate is refused whole, and the error lists every problem. The [conversation format](/docs/conversation-format) describes the document. Notes the owner creates under **What They Remember** stay in the local editor. They are omitted from agent reads, share links and excerpts. `create`, `set` and `update` reject a supplied `memories` field. Ordinary edits, including replacing a conversation with `set`, preserve the owner’s current notes. ## Textmock Pro Agents follow the same rules as people: - **Without Pro:** there is one conversation. Images and videos carry the "textmock.com" badge. - `create` and `import` fail with `pro_required`. The error's details include the price. - An untouched starter (the conversation Textmock made, never edited) doesn't count: `create` and `import` replace it. - `render` still works and reports `badge: true` with a note. - **Upgrading:** `upgrade()` shows the offer in the app. Only the person can subscribe, from that sheet. An agent can't subscribe for them. - **Signing in:** in the Mac app, the command uses the account the person signed in with. There's nothing for the agent to sign in to. Source: https://textmock.com/docs/agents --- # Conversation and share formats A Textmock conversation is one JSON document. The `textmock` command and `window.textmock` expose the same agent-editable document shape. Each validates changes before saving, so a malformed document is refused rather than replacing a saved conversation. ## Conversation document `textmock help` (or `window.textmock.help().doc`) describes the fields agents can edit, with their types. The main ones: | Field | What it holds | | --- | --- | | `name` | The contact's name in the header, up to 60 characters. | | `messages` | Up to 120 messages, oldest first. | | `group` | Two to eight other people, each `{ id, name }`; messages then come from those ids. | | `dark` | `true` for dark mode. | | `transport` | `"sms"` or `"rcs"` for green bubbles; leave it out for blue. | | `clock` | The status-bar time, such as `"9:41"`. | | `typing` | `true` to show the typing indicator after the last message. | | `read` | `false` to show Delivered instead of Read. | | `persona` | Who the other person is, for replies written on the device (up to 1,000 characters). | | `lang` | The phone's language: `en es fr de it pt ja ko zh-Hans zh-Hant`. | Each message has `from` (`"me"`, `"them"`, or a group member's id or name) and usually `text` (up to 4,000 characters). It can also carry: - `photos`: up to 30 pictures as `data:` image URLs. - `card`: one attachment, such as `{ "kind": "link", "url", "title" }`, `{ "kind": "voice", "duration" }`, `{ "kind": "poll", "question", "options" }`, a location, contact, file or sticker. - `reaction` or `reactions`: tapbacks (❤️ 👍 👎 HAHA ‼️ ❓ or any emoji). - `replyTo`: the id of an earlier message, for an inline reply. - `status`: `"delivered"`, `"read"`, `"failed"` and so on; `edited` and `unsent`. - `date`: a time label above the message, such as `"Today 9:41 AM"`. - `format`: bold, italic, underline, strikethrough, or a text effect. You can pass a partial document: the agent interface fills in the defaults and assigns message ids. See [Use Textmock from an agent](/docs/agents). Notes the owner creates under **What They Remember** are local editor fields. The agent APIs omit them from returned documents, and `create`, `set` and `update` refuse a supplied `memories` field. Replacing a conversation with `set` preserves its current private notes. Share links and excerpts leave these notes out. ## Share links A share link holds an editable copy of the conversation after `/s#1.` in the address. The copy is compressed and base64url-encoded. Because it sits in the URL fragment, the browser reads it locally and never sends it to the server. Photos in a share link are reduced to fit. A conversation imported from Messages on a Mac loses its import details when shared. ## Rendering and export **Save Image** draws the conversation as a PNG at the selected phone's full resolution. **Make Video** saves an MP4 of the conversation playing out: 1080 × 1920 for stories or 1080 × 1080 square, at 30 frames a second. Agents get the same files from `render`, as base64. Without Textmock Pro, saved images and videos carry a small “textmock.com” badge. ## Privacy Conversations and photos stay on the device. Subscription requests contain account and payment information, never conversation content. A location card fetches map tiles from OpenFreeMap, and on the website a sent link asks Textmock's preview service for that page's title and picture. The [privacy page](https://textmock.com/privacy) has the details. Source: https://textmock.com/docs/conversation-format