# Set a user's status bubble

`POST /user.statusBubble.set`

## Description

Replaces the shared UI/API thought bubble. Text is trimmed and limited to 1–20 Unicode code points. Omitted or null ttlSeconds defaults to 86400; integers from 300 through 86400 are accepted. Durations below 5 minutes or above 24 hours are rejected. Automatic map removal can take up to about a minute after expiration. Repeating set refreshes expiration. Sending expiresAt is rejected.

See [Status bubbles](/docs/guides/user-status-bubble).

**Access:** Organization and Personal. Organization credentials may target an active user in the workspace. Personal OAuth and PATs may target only their owner. The workspace comes from the token.

**Required scope:** `user:write.statusBubble`. PATs skip the scope check; personal OAuth requires the scope.

---

**OpenAPI Spec:** [chat-v1.json](https://developer.ro.am/chat-v1.json)

## Authentication

```
Authorization: Bearer YOUR_API_KEY
```

## Request Body

| Property | Type | Required | Description |
|----------|------|----------|-------------|
| `userId` | string | Yes | Bare UUID, tagged U-… ID, or ASCII email of the target user. |
| `text` | string | Yes | Text to trim and store. Must contain 1–20 Unicode code points after trimming. Blank text is rejected. |
| `ttlSeconds` | integer | No | Optional duration. Omit or pass null for 24 hours. Durations outside 300–86400 seconds are rejected. |

### Example Request

```json
{
  "userId": "ada@example.com",
  "text": "At lunch 🍎",
  "ttlSeconds": 3600
}
```

## Responses

### 200 - Current bubble and canonical user identifier.

| Property | Type | Required | Description |
|----------|------|----------|-------------|
| `userId` | string | Yes | Canonical UUID of the target user. |
| `statusBubble` | object | Yes | The live thought bubble, or null when none is set or it has expired. |

**statusBubble**:

| Property | Type | Required | Description |
|----------|------|----------|-------------|
| `text` | string | Yes | Trimmed text, limited to 20 Unicode code points. |
| `expiresAt` | string | Yes | Server-stamped expiration in RFC3339 format with millisecond precision. |

### 400 - Missing userId or text (missing_parameter), blank or overlong text or TTL outside 300–86400 (invalid_parameter), malformed JSON or wrong field types (invalid_json), or supplied expiresAt (invalid_arguments).

### 401 - Invalid authentication credentials.

### 403 - Missing scope or personal token targeting someone else.

### 404 - Unknown, archived, or cross-account user.

### 405 - Unsupported method.

### 500 - Internal error.

---

*Machine-readable API documentation.*
*Full documentation: https://developer.ro.am/docs/api/user-status-bubble-set*