# 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.
