# Agent Settings

> Read and change a Mojeeb agent's name, description, Main Instructions, time zone, AI handoff and comment auto-hide from your own systems through the Public API, and see which agent fields a key can't change.

An agent's settings decide how its AI behaves: the Main Instructions it follows on every reply, the time zone it reasons in, and whether a reply from your team pauses it. With the Public API you can read and change them from your own systems, for example to keep the instructions in sync with the place your team writes them. Both calls use `/v1/agents/{agentId}`.

## How do I read an agent's settings?

`GET` the agent. Besides the basic details the agent list returns, the response carries its settings: the Main Instructions as `instructions`, the AI handoff as `ai_handoff_enabled` and `ai_handoff_window_minutes`, and comment auto-hide as `comment_auto_hide_enabled`.

```bash
curl https://api.mojeeb.app/v1/agents/YOUR_AGENT_ID \
  -H "Authorization: Bearer mk_live_YOUR_KEY_HERE"
```

`GET /v1/agents` keeps only the basic details, so get the one agent when you need its settings. The instructions come back exactly as stored, which is what the AI reads: plain text, or HTML when someone last saved them in the dashboard's editor. Every field is in the [Get an agent reference](../api-reference/get-agent).

## How do I change the Main Instructions?

`PATCH` the agent with `instructions`. The text replaces the whole of the Main Instructions, and the AI follows it on its next replies, usually within a minute. Mojeeb rebuilds the AI's context in the background only when the text actually changed, so sending the same text again changes nothing.

```bash
curl -X PATCH https://api.mojeeb.app/v1/agents/YOUR_AGENT_ID \
  -H "Authorization: Bearer mk_live_YOUR_KEY_HERE" \
  -H "Content-Type: application/json" \
  -d '{ "instructions": "You are the front desk of Acme Clinics.\n\nAnswer in the language the customer writes in.\n\nNever quote prices; offer a call back instead." }'
```

Send plain text, one rule per line, with a blank line between rules. The dashboard shows lines that have no blank line between them as one paragraph, and saves them that way when someone edits the instructions there. Empty or blank instructions are refused, so a faulty sync can't wipe the agent's standing orders. See [Main Instructions](/docs/features/main-instructions) for what to write, and the [Update an agent's settings reference](../api-reference/update-agent) for the length limit.

## How do I change the AI handoff?

`PATCH` `ai_handoff_enabled`, `ai_handoff_window_minutes`, or both. With the handoff on, a reply from your team in a conversation pauses the AI there, so it doesn't talk over you. The pause lasts the window, counted from your team's last message and extended by each further reply. With it off, the AI keeps answering even right after a person replies.

```bash
curl -X PATCH https://api.mojeeb.app/v1/agents/YOUR_AGENT_ID \
  -H "Authorization: Bearer mk_live_YOUR_KEY_HERE" \
  -H "Content-Type: application/json" \
  -d '{ "ai_handoff_enabled": true, "ai_handoff_window_minutes": 30 }'
```

The window is kept while the handoff is off, so switching it back on restores the same pause. A change applies from your team's next reply: a pause already running ends at its own time, and switching the AI on in that conversation in the dashboard ends it at once. In the dashboard these are the **AI handoff** switch and the **Pause duration** under **AI Handoff Window**; see [AI Conversations](/docs/features/ai-conversations). The allowed window is in the [Update an agent's settings reference](../api-reference/update-agent).

## How do I switch comment auto-hide on or off?

`PATCH` `comment_auto_hide_enabled`. It's on by default: the AI hides abusive, spam and similar comments on the agent's Facebook and Instagram accounts. It doesn't change how the AI replies. See [Comments and Auto-Hide](./comments) for the comments themselves and for hiding or showing one.

## How do I change the time zone?

`PATCH` `time_zone` with an IANA time zone in Region/City form, such as `Asia/Riyadh` or `Africa/Cairo`. It is the clock the agent answers from: opening hours, today and tomorrow, and booking times. An empty string returns the agent to the platform default.

```bash
curl -X PATCH https://api.mojeeb.app/v1/agents/YOUR_AGENT_ID \
  -H "Authorization: Bearer mk_live_YOUR_KEY_HERE" \
  -H "Content-Type: application/json" \
  -d '{ "time_zone": "Asia/Riyadh" }'
```

A name that isn't an IANA zone, such as `Cairo` or `Egypt Standard Time`, returns `422 unknown_timezone` and nothing changes. The response's `time_zone` is the zone the agent uses now, including the platform default when you sent an empty string.

## How do I rename an agent or change its description?

`PATCH` `name`, `description`, or both. Each is stored without surrounding spaces, and neither may contain angle brackets. The name can't be blank, and an empty description clears it.

```bash
curl -X PATCH https://api.mojeeb.app/v1/agents/YOUR_AGENT_ID \
  -H "Authorization: Bearer mk_live_YOUR_KEY_HERE" \
  -H "Content-Type: application/json" \
  -d '{ "name": "Sales assistant", "description": "Answers product questions and books demos." }'
```

Your team sees the new name in the dashboard, and the AI sees it in each conversation.

## What can't a key change?

An agent's `status`, so a key can't delete an agent; its AI model (`ai_model` and `model_provider`); its picture (`avatar_url`); and its `language` code. Sending any of them with a value returns `422 field_not_writable` with `param` naming the field, and nothing changes. A field sent as `null` counts as not sent.

```json
{
  "error": {
    "type":           "validation_error",
    "code":           "field_not_writable",
    "message":        "An API key can't change an agent's status or delete it; delete agents in the dashboard.",
    "param":          "status",
    "correlation_id": "req_01KQ..."
  }
}
```

Send only the settings you change. A body copied from `GET` includes `language`, so sending it back whole is refused. Fields the endpoint doesn't take, such as `id` or `created_at`, are ignored. Creating and deleting agents stay in the dashboard. Channel switches and follow-ups have their own endpoints; see [Channels and Follow-ups](./channels-and-follow-ups). So does the prompt that decides when the AI saves a lead; see [Contacts, Notes and Leads](./contacts-and-leads).

## Common questions

### Does `language` change the language the agent replies in?

No. It is a code saved on the agent, `en` for nearly every agent, and nothing reads it: the agent replies to each customer in their own language, as its Main Instructions say. That is why a key can't change it. To set the language or dialect, write it into the Main Instructions.

### Why do my instructions show as one paragraph in the dashboard?

The dashboard joins lines that have no blank line between them into one paragraph, and saves them that way the next time someone edits the instructions there. Put a blank line between rules when you write them through the API.

### Why do instructions come back as HTML?

The API returns them exactly as stored. Instructions last saved in the dashboard's editor are stored as its HTML: paragraph, list, bold and italic tags. To decide whether to send, compare your source with what you last sent (for example a hash you keep), not with the returned text.

### Does sending the same instructions again rebuild the AI?

No. Mojeeb compares the text with what is stored and rebuilds the AI's context only when it changed, so a sync job can send the instructions on every run. The comparison is exact: a change in spacing or letter case counts as a change.

### Is there a length limit on the instructions?

Yes, through the API; see the [Update an agent's settings reference](../api-reference/update-agent). The dashboard sets none, so instructions written there can be longer: the API returns them in full, and to write them back through the API, shorten them first.

### What does `422 no_settings` mean?

The request sent no setting with a value: an empty JSON object, only `null` values, or only fields the endpoint doesn't take. Send at least one setting.

### What if someone edits the agent in the dashboard at the same time?

The last save wins, as between two dashboard tabs. Get the agent again afterwards if you need to be sure of what is stored.

### Can a key create or delete an agent?

No. Creating and deleting agents stay in the dashboard. Sending `status` returns `422 field_not_writable`, so a key can never delete an agent by accident.

### Who can change these settings with a key?

A key acts with the access of an agent admin on its agents, the access the dashboard asks for to change an agent's settings. A key limited to some agents can change only those; another agent of your organization returns `403 agent_not_authorized`. Changing settings needs the `agents:write` scope, and reading them `agents:read`; every key holds both today.