> ## Documentation Index
> Fetch the complete documentation index at: https://docs.tryhamsa.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Drafts and versions: how changes reach callers

> Every member edits a private draft that saves on its own. Publishing makes it a numbered version. See who can publish, and how to view and restore versions.

Your edits to an agent save to your own draft, which only you see. Callers never hear a draft. Publishing turns a draft into a numbered version (v1, v2, v3), and "a version never changes after that". This page covers your draft, publishing, and working with old versions.

## Before you start

What you can do depends on your role. These are the defaults; an owner can change them per member in [Roles and permissions](https://docs.tryhamsa.com/overview/projects/roles-and-permissions.md).

| Action | Owner | Admin | Member |
| - | - | - | - |
| Edit your own draft, test it, request a merge | Yes | Yes | Yes |
| Publish a version (deployments on) | Yes | Yes | No |
| **Publish live** (deployments off) | Yes | Yes | No |
| Rename a version | Yes | Yes | No |
| **Copy to draft** from an old version | Yes | Yes | Yes |
| Review other members' merge requests | Yes | Yes | No |

A member can't publish. When a member's draft is ready, they request a merge and an owner or admin publishes it. See [Merge requests](https://docs.tryhamsa.com/agents/release/merge-requests.md).

## Two ways to release an agent

Each agent uses one of two release modes. You see which one in **Releases**.

| Mode | What publishing does | Use it when |
| - | - | - |
| **Versioning** (the default) | **Publish live** makes a new version and puts it live. "Callers hear it from the next call." | You want one live agent and quick changes |
| **Deployments** | **Publish version** makes a new version in dev. You promote it to staging and prod; "callers hear nothing new until it reaches prod." | You want to test in dev and staging first, run A/B tests, or give each environment its own values and number |

Turning on deployments can't be undone. See [Environments and releases](https://docs.tryhamsa.com/agents/release/environments.md).

## Your draft

Every member, owners and admins included, edits a private draft. "Your own draft. Only you see it until you request a merge." Owners and admins see "…until you publish it or request a merge."

* **It saves on its own.** The header shows "Saving…" and "Saved". If a save doesn't go through, the header says why (see [When a save doesn't go through](#when-a-save-doesnt-go-through)). Your changes are kept on the device until they save.
* **One tab at a time.** If the agent is open for editing in another tab, the editor says "This agent is open for editing in another tab." Click **Use here** to edit in this one.
* **Unsaved work survives a reload.** After a reload the editor shows "Unsaved changes restored". Click **Keep** to save them or **Discard** to drop them.
* **It expires after 7 days without an edit.** The editor warns you: "Your draft expires \{when}. Any edit keeps it." A draft in a merge request doesn't expire.
* **It follows the newest version until you edit it.** If someone publishes a version while your draft has no changes, your draft moves onto that version on its own.

### When a save doesn't go through

The save status sits in the editor header, beside the version chip. Hover it for the details.

| The header shows | What it means | What to do |
| - | - | - |
| "Offline, will retry" | "Your changes are kept on this device and save as soon as the connection is back." | Nothing. It saves when you are back online. |
| "Not saved, will retry" | "The server had a problem. Trying again shortly." | Nothing. It tries again on its own. |
| "Not saved: \{reason}" | The server refused the change, and says why. "Your changes are kept on this device. Fix what the message says, or try again." | Fix what the message says, or click **Retry**. |
| "Not saved: the draft moved on" | Your draft was saved somewhere else while this tab stayed open for a long time, and this tab can't save onto it any more. "Your changes are kept on this device. Reload to continue from the latest draft." | Click **Reload**. |
| "Not saved yet" | You restored unsaved changes and haven't kept or discarded them: "Keep or discard the restored changes to save again." | Click **Keep** or **Discard**. |
| **Unresolved conflict** · **Review** | Two saves of your draft collided: "Your changes are not saved yet. Review the conflict to save them." | Click **Review**. See [When two saves of your draft collide](#when-two-saves-of-your-draft-collide). |

![The editor header with the save status Not saved, will retry, and its tooltip: The server had a problem. Trying again shortly.](https://mintcdn.com/hamsa-452fa79a/2654KIaxnTY04VOj/images/agents/release/autosave-will-retry-light.webp?fit=max\&auto=format\&n=2654KIaxnTY04VOj\&q=85\&s=30a784a3804ba4d1e2799f40029c0834)

![The editor header with the save status Not saved: the draft moved on, the Reload button beside it, and the tooltip saying your changes are kept on this device](https://mintcdn.com/hamsa-452fa79a/2654KIaxnTY04VOj/images/agents/release/autosave-draft-moved-on-light.webp?fit=max\&auto=format\&n=2654KIaxnTY04VOj\&q=85\&s=5eaacd9dcf891ad0d2377da13c1072b5)

### When two saves of your draft collide

Your draft has one writer, you, but you can save it from more than one place: another tab or window, or the API with your key. If your draft was saved from somewhere else while you were editing here, and both changed the same thing, autosave stops and the editor asks you what to keep. Changes that don't clash are combined on their own.

The review opens by itself when you ask for a save (for example when you publish). When autosave meets the conflict, the header shows **Unresolved conflict** · **Review** instead, so nothing opens while you type. You can't publish until it is settled: "Resolve the conflict first: your changes are not saved yet."

![The flow editor header showing Unresolved conflict and Review beside the version chip](https://mintcdn.com/hamsa-452fa79a/2654KIaxnTY04VOj/images/agents/release/draft-conflict-header-light.webp?fit=max\&auto=format\&n=2654KIaxnTY04VOj\&q=85\&s=77bc6b14f6198f3bbfa31005322776f5)

**1. Open the review**

Click **Review** in the header. The title says where the other save came from, for example "You saved from another tab while editing here". "Your changes were not saved yet. Nothing is lost: your version is kept on this device."

![The conflict review titled You saved from another tab while editing here, with two decisions: a prompt both tabs edited, shown as Before, Your other tab and You with Keep your version, Keep your other tab's version and Combine, and a step the other tab deleted that you edited](https://mintcdn.com/hamsa-452fa79a/2654KIaxnTY04VOj/images/agents/release/draft-conflict-review-light.webp?fit=max\&auto=format\&n=2654KIaxnTY04VOj\&q=85\&s=90eb1ce65665ae5c2c85c31b68ce3aa6)

**2. Read each decision**

Decisions are grouped by area (**Steps**, **Tools**, **Variables** and so on). Each one says what kind of clash it is, such as **Both edited** or **Deleted vs edited**, shows the value before and each side's version, and says what each choice also changes. **Show in editor** takes you to that place in the editor.

Switch to **JSON** to see the same decisions as the agent's settings, side by side.

![The conflict review in the JSON view: the clashing prompt as Before, Your other tab and You, and the deleted step shown as Not in this version on one side](https://mintcdn.com/hamsa-452fa79a/2654KIaxnTY04VOj/images/agents/release/draft-conflict-json-light.webp?fit=max\&auto=format\&n=2654KIaxnTY04VOj\&q=85\&s=32852ed6a80f7ce7a1100fd908bc4f8c)

**3. Choose what to keep**

Pick an option on every decision, for example **Keep your version**, **Keep your other tab's version**, or **Combine** ("Write one from both"). The review counts them: "\{done} of \{total} decided".

**4. Resolve**

Click **Resolve \{count} decisions**. "Conflict resolved. Your decisions are saved." If the result would break something, for example a transition left with no destination, the review lists it and the button reads **Resolve anyway**.

To come back to it later, click **Decide later** or **Open in editor**. The conflict stays, your work stays on this device, and the header keeps offering **Review**. If the other place saves again meanwhile, the review shows its latest changes: "\{name} saved again. The review now shows their latest changes."

Deciding needs permission to edit the agent. Someone without it sees the review read-only: "Only members who can edit this agent resolve conflicts. Your edits are kept on this device, and nothing is lost."

### Discard your draft

Open the **⋯** menu in the editor header and click **Discard my draft**. "Draft discarded. You can bring it back for 30 days." Click **Bring back** to restore it. After 30 days it is deleted.

![The editor header menu open, with Discard my draft among Live call logs, Calls, Publish page, Export and Copy agent ID](https://mintcdn.com/hamsa-452fa79a/2654KIaxnTY04VOj/images/agents/release/editor-more-menu-light.webp?fit=max\&auto=format\&n=2654KIaxnTY04VOj\&q=85\&s=cc0c9ff616be7dfb3a52726c71b0c8b9)

## Publish a version

Owners and admins publish from the editor header. The button you see depends on the mode:

| Mode | Main button | In the menu beside it |
| - | - | - |
| Versioning | **Publish live** | **Request merge**, so another owner or admin reviews it first |
| Deployments | **Request merge** | **Publish version**: "Skips the review: makes a version from your draft now." |

**1. Click Publish live or Publish version**

![The editor header for an owner with deployments off: Publish live, and the menu beside it open showing Request merge](https://mintcdn.com/hamsa-452fa79a/IyoYQ-nNrFRmlJOT/images/agents/release/publish-live-menu-light.webp?fit=max\&auto=format\&n=IyoYQ-nNrFRmlJOT\&q=85\&s=6ae4766ab2cde3ab39e25cc0d441bc8c)

**2. Say what changed**

Fill in **Change summary**: "Say what changed: it is what your team reads later." It is required, up to 500 characters.

![The Publish live dialog with a change summary filled in, an empty New version label, and the note that v10 goes live from the next call](https://mintcdn.com/hamsa-452fa79a/IyoYQ-nNrFRmlJOT/images/agents/release/publish-live-dialog-light.webp?fit=max\&auto=format\&n=IyoYQ-nNrFRmlJOT\&q=85\&s=15941b5b550a28c1b2741772d6e34376)

**3. Add a label, if you want one**

**New version label** is optional, up to 100 characters, for example "Feature X launch".

**4. Add your test values, if you used any**

If you tested with [test values](https://docs.tryhamsa.com/agents/release/test-your-agent.md#use-test-values), you can add them to dev (deployments on) or prod (deployments off) as part of publishing.

**5. Publish**

With deployments off: "v\{version} goes live: callers hear it from the next call." With deployments on: "v\{version} lands in dev. Promote it to staging and prod from Releases; callers hear nothing new until it reaches prod."

Publishing is refused in two cases:

* The agent has errors: "Fix the errors in this agent before publishing it."
* Nothing changed: "Nothing new to publish: the draft matches \{version}."

Publishing live needs the Deploy permission. Without it you see "Going live needs the Deploy permission. Your edits are saved in the draft."

## What a version holds

A version is a snapshot of the agent: its prompt or flow, greeting, model, call settings and variables, and which voice, tools, knowledge base items and dictionaries it uses.

Some of those belong to the whole project, so a version stores which one it uses, not its content. An old version shows today's content for:

* [Knowledge base](https://docs.tryhamsa.com/agents/knowledge-base/overview.md) items
* The voice itself, and the entries in its [pronunciation dictionaries](https://docs.tryhamsa.com/agents/voices/dictionaries.md)

Some things are not in a version at all:

* Phone numbers. Moving a number never needs a publish.
* [Policies & guardrails](https://docs.tryhamsa.com/agents/safety/policies-and-guardrails.md) and [Functions & macros](https://docs.tryhamsa.com/agents/safety/functions-and-macros.md). Turning one on or off for an agent, or editing it in the library, changes live calls right away, whichever version they run.

## Find and view versions

Version history lives in **Releases**. Click the version chip in the editor header to open it. On a narrow screen, open **⋯** > **Deployments**.

### Read the version chip

The version chip in the editor header says what is on your screen and whether callers hear it. A green dot means callers hear what you see; an amber dot means your draft has changes that aren't in any version yet.

| The chip reads | What it means |
| - | - |
| **Draft** (deployments off) | Your draft has unpublished changes. It is not live: screen readers and the label read "Draft, Not live". |
| **Draft · v3** (deployments on) | Your draft, built on v3 ("from v3"), with unpublished changes. A draft runs in no environment: "Not deployed". |
| **v9** **Live** (deployments off) | Your draft matches v9, and callers hear it. A version callers don't hear reads **Not live**. |
| **v1** **prod · Live** (deployments on) | Your screen matches v1, and prod runs it, so callers hear it. Other environments that run it show as their own tags (**staging**, **dev**). |
| **prod · 10%** | During an [A/B test](https://docs.tryhamsa.com/agents/release/ab-tests.md), the share of prod's calls this version takes. |
| **Not deployed** | The version on screen runs in no environment. |
| **· Callers hear v7** | With deployments on, added when what's on screen isn't what callers hear (your draft, or a version prod doesn't run), so you know which version is live. During an A/B test it names the split. |
| **No versions yet** | Nothing has been published. |

Hover the chip for the whole picture: what callers hear, what dev and staging run (for example "dev v9 · staging v8"), and your draft. On a narrow header, the chip shows fewer tags; the tooltip still has them all.

When you open a version to view it, a banner replaces the draft's view:

| The banner shows | What it means |
| - | - |
| **Viewing v8** | The version on screen, read-only ("Viewing v\{version} · read-only"). |
| "Published \{date} by \{name}" | When the version was published and who published it, with its label or change summary. |
| Environment tags | Where this version runs now, as on the chip. |
| **Exit version view** | Goes back to your draft. |
| **Copy to draft** | Replaces your draft with this version. Not offered for the version that takes every live call, since your draft already starts from it. |

Select a version to see:

| Section | What it shows |
| - | - |
| **Where it runs** | Which environments run this version now |
| **Environment variables it reads** | Each key, and whether each environment has a value for it |
| **What changed** | "The edits this version was published with." |
| **Activity** | "Every publish, promote and roll back that involved this version." |

![Version history in Releases with v8 selected: where it runs in dev, staging and prod, and View in editor and Copy to draft](https://mintcdn.com/hamsa-452fa79a/IyoYQ-nNrFRmlJOT/images/agents/release/version-history-light.webp?fit=max\&auto=format\&n=IyoYQ-nNrFRmlJOT\&q=85\&s=4422535aeb3a6e47411ccaceaf993dd7)

Click **View in editor** to open the version read-only. The banner reads "Viewing v\{version} · read-only". The link is shareable. Click **Exit version view** to go back to your draft.

### Compare a version with live

To see how a version differs from the one callers hear now:

**1. Select the version**

In **Releases**, select any version other than the live one.

**2. Open the comparison**

Under **Compared with live**, click **Compare with live (v7)** (the live version's number). The comparison takes the whole of Releases, titled "v9 compared with live (v7)".

**3. Read the differences**

"Every difference between this version and the one callers hear now, older version first. Read only." The prompt shows as a word-by-word change, followed by every setting that differs. The older version is always **Before** and the newer one **After**, whichever of them is live, so an old version reads as what changed since, and a newer one as what it would bring.

**4. Go back**

Click **Back to v9**, or press Esc, to return to the version.

![v9 compared with live (v7) in Releases: the system prompt with Before (v7, live) and After (v9) labels and the lines v9 added highlighted, and Back to v9 at the top](https://mintcdn.com/hamsa-452fa79a/2654KIaxnTY04VOj/images/agents/release/compare-with-live-light.webp?fit=max\&auto=format\&n=2654KIaxnTY04VOj\&q=85\&s=287a08ae4c4355522a038db559e468f8)

The live version itself has no **Compare with live** button. Nothing in the comparison can be edited; to keep a version's content, use **Copy to draft**.

## Copy an old version to your draft

To start again from an older version, open it and click **Copy to draft**. This "replaces the draft"; "Nothing callers hear changes. Publish to make it a new version."

Every member can copy a version to their own draft.

## Rename a version

Owners and admins can change a version's label and summary (**Rename v\{version}**). "Only the label and summary change. What this version contains stays exactly as it was published."

## Good to know

* If someone publishes while you edit, your draft is still based on the version you started from. A merge request shows how many versions behind it is, and reviewers see your changes merged onto the newest version.
* When you publish a draft that is behind the newest version, the editor first brings your draft onto that version, then publishes. Where your edits and the newer version changed the same thing, you choose what to keep in **Update your draft to \{version}**: "Choose what to keep for each decision. Nothing changes in your draft until you finish." If your draft can't be brought onto it then, for example because you closed that review, publishing stops with "\{version} came out meanwhile. Publish again to bring your draft onto it."
* If deployments are switched on or off while you work, the app asks you to reload: "Deployments were switched on or off meanwhile. Reload and try again."

![The Publish live dialog with a change summary filled in, and a message at the bottom right: v10 came out meanwhile. Publish again to bring your draft onto it.](https://mintcdn.com/hamsa-452fa79a/IyoYQ-nNrFRmlJOT/images/agents/release/publish-newer-version-meanwhile-light.webp?fit=max\&auto=format\&n=IyoYQ-nNrFRmlJOT\&q=85\&s=cd9ee413ced8b4284af9317f230b5546)

## Related

> [card] [Merge requests](https://docs.tryhamsa.com/agents/release/merge-requests.md)
>
> Ask an owner or admin to merge your draft.

> [card] [Environments and releases](https://docs.tryhamsa.com/agents/release/environments.md)
>
> Promote versions through dev, staging and prod.

> [card] [Test your agent](https://docs.tryhamsa.com/agents/release/test-your-agent.md)
>
> Try your draft before you publish it.

> [card] [Roles and permissions](https://docs.tryhamsa.com/overview/projects/roles-and-permissions.md)
>
> What owners, admins and members can do.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.