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

# Shared conversations

> Share a Murph conversation with teammates in the same account

Shared Murph conversations let teammates in the same account open the
same conversation, read the full message history, see who else is present, and
send room messages alongside assistant-directed turns.

<Info>
  Shared conversations are available to all customers. If the capability is
  disabled for an account, these endpoints either omit shared-room fields or
  return `404 NOT_FOUND` for shared-room actions.
</Info>

<Info>
  When `sharingEnabled` is omitted from `POST /api/v2/murph/conversations`, the
  new conversation inherits the org-level default set via
  [conversation settings](/v2/api/murph/conversation-settings). If no org default
  is configured, conversations start private.
</Info>

## List conversations

`GET /api/v2/murph/conversations`

When shared conversations are enabled, the conversation list includes private
conversations owned by the caller and shared conversations in the same
account.

### Response fields

| Field                            | Type    | Notes                                                                                                      |
| -------------------------------- | ------- | ---------------------------------------------------------------------------------------------------------- |
| `conversations[].sharingEnabled` | boolean | `true` when teammates in the same account can open the room link.                                          |
| `presenceByConversationUid`      | object  | Map from `conversationUid` to currently active participants. Empty when shared conversations are disabled. |

```json theme={null}
{
  "conversations": [
    {
      "conversationUid": "550e8400-e29b-41d4-a716-446655440000",
      "title": "Campaign pacing",
      "sharingEnabled": true
    }
  ],
  "presenceByConversationUid": {
    "550e8400-e29b-41d4-a716-446655440000": [
      {
        "userId": 12,
        "name": "Inez",
        "email": "inez@example.com"
      }
    ]
  },
  "totalCount": 1,
  "hasMore": false
}
```

## Rename a conversation

`PATCH /api/v2/murph/conversations/{conversationUid}/title`

Overwrites the conversation title with a name you choose. The auto-generated
title is replaced immediately everywhere it appears. Only the conversation
owner can rename it.

```bash curl theme={null}
curl -X PATCH https://api.interchange.io/api/v2/murph/conversations/550e8400-e29b-41d4-a716-446655440000/title \
  -H "Authorization: Bearer $SCOPE3_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Demo: Add Creatives"
  }'
```

### Request body

| Field   | Type   | Required | Notes                                                         |
| ------- | ------ | -------- | ------------------------------------------------------------- |
| `title` | string | Yes      | 1–255 characters. Leading and trailing whitespace is trimmed. |

### Response

```json theme={null}
{
  "conversation": {
    "conversationUid": "550e8400-e29b-41d4-a716-446655440000",
    "title": "Demo: Add Creatives"
  }
}
```

## Enable or disable sharing

`PATCH /api/v2/murph/conversations/{conversationUid}/sharing`

Sets whether a conversation is shared with teammates in the same account.
The caller must be able to read the conversation. Cross-account access
is never allowed.

```bash curl theme={null}
curl -X PATCH https://api.interchange.io/api/v2/murph/conversations/550e8400-e29b-41d4-a716-446655440000/sharing \
  -H "Authorization: Bearer $SCOPE3_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "sharingEnabled": true
  }'
```

### Request body

| Field            | Type    | Required | Notes                                                                 |
| ---------------- | ------- | -------- | --------------------------------------------------------------------- |
| `sharingEnabled` | boolean | Yes      | `true` shares the room; `false` returns it to a private conversation. |

### Response

```json theme={null}
{
  "conversation": {
    "conversationUid": "550e8400-e29b-41d4-a716-446655440000",
    "sharingEnabled": true
  }
}
```

## Stream room events

`GET /api/v2/murph/conversations/{conversationUid}/events`

Opens a Server-Sent Events stream for a shared room. The stream emits new
persisted messages and presence changes. Pass `after` to resume after a known
message sequence.

```bash curl theme={null}
curl -N "https://api.interchange.io/api/v2/murph/conversations/550e8400-e29b-41d4-a716-446655440000/events?after=12" \
  -H "Authorization: Bearer $SCOPE3_API_KEY"
```

### Events

| Event              | Data                                | Notes                                                                                                                       |
| ------------------ | ----------------------------------- | --------------------------------------------------------------------------------------------------------------------------- |
| `ready`            | `{ conversationUid, after }`        | The stream is open. `after` is the sequence cursor the server will tail from.                                               |
| `message.created`  | `{ conversationUid, message }`      | A newly persisted Murph message. `message.audience` is `assistant` or `room`; user-authored messages include author fields. |
| `presence.changed` | `{ conversationUid, participants }` | Current room participants. Participants include `userId`, `name`, and `email` when available.                               |
| `error`            | `{ code, message, status }`         | Stream-level failure. Reconnect from the latest known sequence.                                                             |

## Send a room message

`POST /api/v2/murph/conversations/{conversationUid}/messages`

Send a message to the room without asking Murph to respond by setting
`audience: "room"`. To ask Murph, use the normal chat endpoint and direct the
turn to Murph.

```bash curl theme={null}
curl -X POST https://api.interchange.io/api/v2/murph/conversations/550e8400-e29b-41d4-a716-446655440000/messages \
  -H "Authorization: Bearer $SCOPE3_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "audience": "room",
    "content": "@inez can you check this pacing note?"
  }'
```

### Request body

| Field      | Type     | Required | Notes                                                              |
| ---------- | -------- | -------- | ------------------------------------------------------------------ |
| `audience` | `"room"` | Yes      | Room messages are visible to participants and do not prompt Murph. |
| `content`  | string   | Yes      | Message text.                                                      |

## Errors

* `400 VALIDATION_ERROR` — invalid UUID, query string, or request body.
* `401 UNAUTHORIZED` — missing or invalid bearer token.
* `404 NOT_FOUND` — conversation does not exist, belongs to another account,
  is private to another user, or shared conversations are disabled.

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

## Related

<CardGroup cols={2}>
  <Card title="Conversation scope" href="/v2/api/murph/conversation-scope" icon="sitemap">
    Bind a Murph conversation to an account or advertiser.
  </Card>

  <Card title="Chat response" href="/v2/api/murph/chat-response" icon="sparkles">
    Read the artifacts Murph can return from an assistant-directed turn.
  </Card>
</CardGroup>