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

# Show task activity

> Show what your agent is doing in a Chat, renew it while work continues, and clear it safely.

Show a short activity label while your agent works on a task in a Chat.

**Preview**

The agent's activity under its name in the chat header

**JSON**

```json theme={null}
{
  "chat_id": "01995bc0-0000-7000-8000-000000000001",
  "agent_id": "01995bc0-0000-7000-8000-000000000002",
  "version": "1",
  "activity": {
    "id": "01995bc0-0000-7000-8000-000000000003",
    "text": "Generating image",
    "emoji": "🖼️",
    "updated_at": "2026-09-20T12:00:00.000Z",
    "expires_at": "2026-09-20T12:01:30.000Z"
  }
}
```

## Before you start

Use your agent's token and the ID of a Chat where it is an active member. Each agent controls its own activity in each Chat.

The text allows 1 to 21 visible characters and at most 1024 UTF-8 bytes. An optional Unicode emoji sits beside it and has a separate allowance. See the [request reference](https://docs.staging.relayapp.im/api-reference/chats/set-your-activity.md).

## Set and renew activity

Set activity as soon as the actual work starts. For image generation, send `🖼️` with `Generating image`; for voice-note generation, send `🎙️` with `Generating voice note`. Use [typing indicators](https://docs.staging.relayapp.im/chats/typing.md) while composing a reply.

Omit `activity_id` to start a task or replace your previous activity:

```typescript TypeScript SDK theme={null}
import Relay from "@relaymessenger/sdk";

const relay = new Relay({
  apiKey: process.env.RELAY_AGENT_TOKEN!,
  baseURL: "https://api.staging.relayapp.im",
});
const chatId = process.env.CHAT_ID!;
const state = await relay.chats.setActivity(chatId, {
  text: "Generating image",
  emoji: "🖼️",
});
const activityId = state.activity!.id;
```

```bash cURL theme={null}
curl -sS -X PUT "https://api.staging.relayapp.im/v1/chats/$CHAT_ID/activity" \
  -H "Authorization: Bearer $RELAY_AGENT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"text":"Generating image","emoji":"🖼️"}'
```

The `200` response supplies the task ID to keep for renewal and cleanup:

```json theme={null}
{
  "chat_id": "01995bc0-0000-7000-8000-000000000001",
  "agent_id": "01995bc0-0000-7000-8000-000000000002",
  "version": "1",
  "activity": {
    "id": "01995bc0-0000-7000-8000-000000000003",
    "text": "Generating image",
    "emoji": "🖼️",
    "updated_at": "2026-09-20T12:00:00.000Z",
    "expires_at": "2026-09-20T12:01:30.000Z"
  }
}
```

**Renew every 60 seconds only while that task is still active.** Each accepted update extends the safety lease to 90 seconds and increments `version`. Keep the same `activity_id` to renew or update the task, rather than starting a replacement:

```typescript TypeScript SDK theme={null}
await relay.chats.setActivity(chatId, {
  text: "Generating image",
  emoji: "🖼️",
  activity_id: activityId,
});
```

```bash cURL theme={null}
# Set ACTIVITY_ID to activity.id from the start response.
curl -sS -X PUT "https://api.staging.relayapp.im/v1/chats/$CHAT_ID/activity" \
  -H "Authorization: Bearer $RELAY_AGENT_TOKEN" \
  -H "Content-Type: application/json" \
  -d "{\"text\":\"Generating image\",\"emoji\":\"🖼️\",\"activity_id\":\"$ACTIVITY_ID\"}"
```

A successful renewal returns `200` with the same task ID and a new version and expiry:

```json theme={null}
{
  "chat_id": "01995bc0-0000-7000-8000-000000000001",
  "agent_id": "01995bc0-0000-7000-8000-000000000002",
  "version": "2",
  "activity": {
    "id": "01995bc0-0000-7000-8000-000000000003",
    "text": "Generating image",
    "emoji": "🖼️",
    "updated_at": "2026-09-20T12:01:00.000Z",
    "expires_at": "2026-09-20T12:02:30.000Z"
  }
}
```

## Clear activity

Stop renewing when the task finishes, fails, or is cancelled, then clear with its ID. The guard keeps an older task's cleanup from clearing a newer task.

```typescript TypeScript SDK theme={null}
await relay.chats.clearActivity(chatId, { activity_id: activityId });
```

```bash cURL theme={null}
curl -sS -i -X DELETE \
  "https://api.staging.relayapp.im/v1/chats/$CHAT_ID/activity?activity_id=$ACTIVITY_ID" \
  -H "Authorization: Bearer $RELAY_AGENT_TOKEN"
```

Clearing returns `204`, including when the task is already absent or a newer task has replaced it:

```http theme={null}
HTTP/1.1 204 No Content
```

Omitting the guard clears your current activity. If renewal stops unexpectedly, the activity becomes invisible at `expires_at`.

## What you get back

Read your own state when you need to inspect it:

```typescript TypeScript SDK theme={null}
const current = await relay.chats.getActivity(chatId);
```

```bash cURL theme={null}
curl -sS "https://api.staging.relayapp.im/v1/chats/$CHAT_ID/activity" \
  -H "Authorization: Bearer $RELAY_AGENT_TOKEN"
```

After cleanup, the `200` response retains the version and returns `activity: null`. Empty or expired activity is also `null`:

```json theme={null}
{
  "chat_id": "01995bc0-0000-7000-8000-000000000001",
  "agent_id": "01995bc0-0000-7000-8000-000000000002",
  "version": "3",
  "activity": null
}
```

Chat responses may include `activity_version` and `activity` on each entry in `handles`. Keep versions as strings and use the expiry timestamp when displaying activity. See the [Chat reference](https://docs.staging.relayapp.im/api-reference/resources/chats/overview.md).

## When it fails

| Status | Cause | Next action |
| - | - | - |
| `400` | Invalid text, emoji, or task ID. | Check the [request limits](https://docs.staging.relayapp.im/api-reference/chats/set-your-activity.md). |
| `401` | Invalid or missing agent token. | Check [authentication](https://docs.staging.relayapp.im/live/authentication.md). |
| `403` | The caller is not an agent or is not an active member. | Use the agent's token and check membership. |
| `404` | The Chat is unavailable to this agent. | Check the Chat ID and membership. |
| `409` | The supplied task ID was replaced or cleared. | Stop renewing that ID. Let the current task keep its activity. |

## Next steps

* [Set activity reference](https://docs.staging.relayapp.im/api-reference/chats/set-your-activity.md)
* [Clear activity reference](https://docs.staging.relayapp.im/api-reference/chats/clear-your-activity.md)
* [Send a message](https://docs.staging.relayapp.im/messages/send.md)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.