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

# Conversation settings

> Read and set the org-level default for Murph conversation sharing

Murph conversation settings are scoped to the org (account). They control the
default sharing behavior for new Murph conversations created within the account.

<Info>
  These endpoints require an admin or super-admin role. Non-admin callers receive
  `403 FORBIDDEN`. The endpoints are available only when Murph is enabled for the
  caller's account.
</Info>

## Get conversation settings

`GET /api/v2/murph/conversation-settings`

Returns the org's current conversation settings.

```bash curl theme={null}
curl https://api.interchange.io/api/v2/murph/conversation-settings \
  -H "Authorization: Bearer $SCOPE3_API_KEY"
```

### Response

```json theme={null}
{
  "defaultSharingEnabled": false
}
```

| Field                   | Type    | Notes                                                                                                                                                                              |
| ----------------------- | ------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `defaultSharingEnabled` | boolean | When `true`, new conversations created without an explicit `sharingEnabled` value start shared with teammates in the same account. When `false` (the default), they start private. |

## Set conversation settings

`PATCH /api/v2/murph/conversation-settings`

Sets the org-level default sharing behavior for new Murph conversations.

The setting applies only to new conversations. Existing conversations keep their
current sharing state.

```bash curl theme={null}
curl -X PATCH https://api.interchange.io/api/v2/murph/conversation-settings \
  -H "Authorization: Bearer $SCOPE3_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "defaultSharingEnabled": true
  }'
```

### Request body

| Field                   | Type    | Required | Notes                                                                                                 |
| ----------------------- | ------- | -------- | ----------------------------------------------------------------------------------------------------- |
| `defaultSharingEnabled` | boolean | Yes      | `true` to share new conversations with teammates by default; `false` to make them private by default. |

### Response

```json theme={null}
{
  "defaultSharingEnabled": true
}
```

The response returns the full settings object now in effect.

## How this connects to creating conversations

When you call `POST /api/v2/murph/conversations`, the `sharingEnabled` field
in the request body follows this precedence:

1. **Explicit value in the request** - if `sharingEnabled` is provided, that value is used.
2. **Org default** - if `sharingEnabled` is omitted, the org-level `defaultSharingEnabled` value is used.
3. **False** - if no org default has been set, new conversations start private.

Individual users can change sharing on any conversation they own at any time using
`PATCH /api/v2/murph/conversations/{conversationUid}/sharing`.

## Errors

* `400 VALIDATION_ERROR`: invalid request body.
* `401 UNAUTHORIZED`: missing or invalid bearer token.
* `403 FORBIDDEN`: caller does not have admin or super-admin role, or Murph is not enabled for the caller's account.

See [Errors](/v2/reference/errors) for the full error contract.

## Related

<CardGroup cols={2}>
  <Card title="Shared conversations" href="/v2/api/murph/shared-conversations" icon="messages">
    Share a Murph conversation with teammates in the same account.
  </Card>

  <Card title="Murph user preferences" href="/v2/api/murph/user-preferences" icon="languages">
    Read and set the authenticated user's Murph language and display preferences.
  </Card>
</CardGroup>