Shared conversations

Shared Apostra 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.

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.

When sharingEnabled is omitted from POST /api/v2/murph/conversations, the new conversation inherits the org-level default set via conversation settings. If no org default is configured, conversations start private.

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.

{
  "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.

curl

curl -X PATCH https://api.apostra.com/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

{
  "conversation": {
    "conversationUid": "550e8400-e29b-41d4-a716-446655440000",
    "title": "Demo: Add Creatives"
  }
}

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.

curl

curl -X PATCH https://api.apostra.com/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

{
  "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.

curl

curl -N "https://api.apostra.com/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 Apostra 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 Apostra to respond by setting audience: "room". To ask Apostra, use the normal chat endpoint and direct the turn to Apostra.

curl

curl -X POST https://api.apostra.com/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 Apostra.
`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 for the full error contract.

Conversation scope

Set an Apostra conversation’s account or advertiser scope.

Chat response

Read the artifacts Apostra can return from an assistant-directed turn.

Start here

Buy media

Sell media

Help and updates

Shared conversations

List conversations

Response fields

Rename a conversation

Request body

Response

Request body

Response

Stream room events

Events

Send a room message

Request body

Errors

Conversation scope

Chat response

​List conversations

​Response fields

​Rename a conversation

​Request body

​Response

​Enable or disable sharing

​Request body

​Response

​Stream room events

​Events

​Send a room message

​Request body

​Errors

​Related

Conversation scope

Chat response

List conversations

Response fields

Rename a conversation

Request body

Response

Enable or disable sharing

Request body

Response

Stream room events

Events

Send a room message

Request body

Errors

Related