# Clear a user's external activity

`POST /user.activity.clear`

## Description

End an activity previously created with [`user.activity.set`](/docs/api/user-activity-set).
The row is keyed by this integration plus `userId` and `externalId` —
you cannot clear another app's activity.

Clearing a missing, already-cleared, or already-expired `externalId`
still returns **204**. Integrations retry "session ended" webhooks, and
the row may have expired in the meantime.

See [External activity](/docs/guides/user-activity) for TTL, DND
stacking, and what happens on the map when the last activity clears.

**Access:** Organization and Personal. Organization tokens may target
any user in the workspace. Personal tokens (OAuth or PAT) may target
only the token owner.

**Required scope:** `user:write.activity`. Personal Access Tokens skip
this check; personal-mode OAuth installs must still request 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 | Target user. Bare or tagged UUID. Personal tokens may only pass their own user.  |
| `externalId` | string | Yes | The `externalId` previously passed to `user.activity.set`. |

### Example Request

```json
{
  "userId": "0cc74785-e31e-4403-aa5e-0cc7c1897e66",
  "externalId": "justcall:call:CA123"
}
```

## Responses

### 204 - Activity cleared, or there was nothing to clear. No response body.


### 400 - Bad request. Common causes:
- Missing `userId` or `externalId`


### 401 - Presented invalid authentication credentials.

### 403 - Forbidden. Common causes:
- Missing `user:write.activity` (OAuth / API key)
- Personal token targeting a user other than the owner (`access_denied`)


### 404 - User not found, or not in this workspace (`user_not_found`).

### 405 - An unsupported method was requested.

### 500 - An internal error occurred.

---

*Machine-readable API documentation.*
*Full documentation: https://developer.ro.am/docs/api/user-activity-clear*