> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs-parschat.parstechai.com/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs-parschat.parstechai.com/_mcp/server.

# Changelog

> Every change to the v1 contract, dated, including the day it went live.

> **Info**
>
> `v1` is live and follows [Versioning & stability](/documentation/reference/versioning-stability).
> Every change to the contract is recorded here, so you can see exactly what moved and decide
> whether it affects your integration.

## 2026-11-03: API keys and webhook are self-serve in the panel

You create your API key and set your webhook yourself, in the panel, under **Profile** →
**Access keys & webhook**. **Not breaking**: the API itself does not change. See
[Get your API key](/documentation/get-started/authentication#get-your-api-key).

* **New in the panel:** create your key, choosing 1, 3, 6 or 12 months of validity. The key is shown
  once. An account holds one key: revoke it to rotate.
* **New in the panel:** set your webhook address, pause deliveries, add custom headers, and
  generate a new signing secret. The secret is shown once.
* **Access:** creating a key needs a plan that includes API access, or an active free trial. During a
  free trial the key works for the robot, usage and webhook endpoints; Instagram endpoints need an
  Instagram API plan. When a trial ends without such a plan, the key answers `403`.
* **Unchanged:** the return URL is still configured by us.

## 2026-10-26: offline and busy messages

A robot now has three messages for a customer waiting for a person, each sent at most once per
conversation. See [What the customer is told while waiting for a person](/documentation/guides/robot-settings#what-the-customer-is-told-while-waiting-for-a-person).

* **New:** `settings.conversations.offline` (`message`, `send_message`): sent to a customer waiting while the
  robot is outside its working hours. Off by default.
* **New:** `settings.conversations.busy` (`message`, `send_message`, `after_seconds`): sent when nobody has
  replied within `after_seconds` (30 to 3600, default 300) during working hours. Off by default.
* **Changed:** `operator_handover` is sent whenever the AI hands a conversation to a person, including when
  the AI cannot answer. `send_message: true` with an empty `message` is now refused with
  `422 validation_failed`. New robots start with it on, with ParsChat's default Persian text.
* **Deprecated:** `offline_message`, now the same text as `offline.message`; and `ai_failure_message`, which is
  accepted but ignored and always `null` in a response. Both will be removed in a later version, announced
  here first.

## 2026-10-24: robot settings over the API

Read and change a robot's settings, the same ones your customer sees in the panel. **Not breaking**:
one operation and some response fields are added; nothing existing changes meaning.

* **New:** `PATCH /robots/{robot_id}` changes any subset of `name`, `external_id`, `description`,
  `is_active` and `settings`: auto-close (15 minutes to 15 days; off still closes after 15 days),
  operator handover message, offline message, what the customer is told when the AI cannot answer
  (`ai_failure_message`), working hours, the AI and the AI operator. See
  [Robot settings](/documentation/guides/robot-settings).
* **Added to every robot:** `description`, `is_active` and `settings`. `external_id` is now always
  present, `null` until you set one.
* **`POST /robots`** accepts `description` and `settings`.
* **New error code:** `403 ai_not_in_plan`, for AI settings on an account without an AI messages
  package.
* **Not in the API:** the robot's custom prompt, which changes only through the panel's prompt
  assistant, and the AI operator's avatar.

## 2026-10-20: the customer's name and picture on `message`

`data.sender` on the [`message` event](/documentation/reference/webhook-event-reference#message) now carries
the end customer's display `name` and profile picture (`avatar_url`) beside `id` and `username`,
and `schema_version` is `1.1.0`. **Not breaking**: both fields are additive and either may be `null`.

`avatar_url` is a link on this API (`/v1/files/avatars/…`) that needs no key, does not expire and always shows the current picture. See [Who sent it](/documentation/reference/webhook-event-reference#who-sent-it).

## 2026-10-14: `v1` is live

Every route in the reference is now callable at `https://api-chat.parstechai.com/v1`, and the
pre-release banners are removed from every page. The shape settled on 2026-09-14 is unchanged.

The one exception is `breakdown=source` on [Usage reports](/documentation/guides/usage#instagram-breakdown-by-entry-point):
it keeps its pre-release banner, and passing it returns the standard payload until it ships.

## 2026-09-14: `v1` published

First public version of the contract. Everything below is the initial commitment.

**Endpoints**: robots, channels, automation rules, media, usage, and a read-only webhook
configuration endpoint.

**Webhook events**: `message`, `message.generating`, `chat`, `reaction`, `is_typing`.

**Decisions worth calling out**, because each one changes what you build:

| Decision                                | Why                                                                 |
| --------------------------------------- | ------------------------------------------------------------------- |
| No writable webhook endpoint            | A stolen key must not be able to redirect your event stream         |
| Webhook auth token is **yours** to set  | It only gates your own endpoint, so waiting on us would be friction |
| Rate limit **queues**, never drops      | A dropped automated reply is a lost customer conversation           |
| `context_reset` is not deletion         | Treating it as deletion discards a transcript we still hold         |
| `follows_business: null` fails **open** | `null` is "Meta did not confirm", not "does not follow"             |
| `404`, not `403`, for others' resources | A `403` would confirm the id exists                                 |

## How changes are announced

| Change                           | You hear about it via                                                              |
| -------------------------------- | ---------------------------------------------------------------------------------- |
| A new field, event, or endpoint  | This page. **Not breaking**, so ignore what you do not recognise                   |
| A removed or renamed field       | Your account manager, in advance                                                   |
| A pre-release feature going live | The pre-release banner disappears from its section, and this page records the date |

See [Versioning & stability](/documentation/reference/versioning-stability) for the full rules on what counts as breaking.