# Timed messages API

> KickBot API and MCP reference for timed messages: list, create, update and delete the messages KickBot posts in Kick chat on an interval.

Source: https://kickbot.com/docs/api/reference/timers

Use these actions to manage timed messages (timers), the messages KickBot posts in chat every few minutes.

Each action is a REST endpoint under `https://kickbot.com/api/v1` and an MCP tool with the same name. The MCP area name is `timers`. Use it to load only this area: `https://kickbot.com/api/v1/mcp?areas=timers`.

A team member needs the **Timed messages** permission in Manage Team. Owners and admins have every permission. Write actions also need a read and write key or connection. See [Permissions and security](https://kickbot.com/docs/api/start/permissions-and-security).

How the feature works in the dashboard: [Timed messages](https://kickbot.com/docs/chat-bot/timed-messages).

## Actions

| Tool | REST | Access |
|---|---|---|
| [`list_timers`](#list_timers) | `GET /timers` | Read |
| [`get_timer`](#get_timer) | `GET /timers/{id}` | Read |
| [`create_timer`](#create_timer) | `POST /timers` | Write |
| [`update_timer`](#update_timer) | `PATCH /timers/{id}` | Write |
| [`delete_timer`](#delete_timer) | `DELETE /timers/{id}` | Write |

## list_timers

**List timed messages.** List the timed messages KickBot posts in chat on an interval. `limit` is how many may be on at a time (null on Premium).

```http
GET /api/v1/timers
```

No input fields.

## get_timer

**Get a timed message.** Get one timed message by id.

```http
GET /api/v1/timers/{id}
```

| Field | Type | Required | Description |
|---|---|---|---|
| `id` (in the path) | integer | Yes | The item id. |

## create_timer

**Create a timed message.** Create a timed message. Call list_timers first: timers have no name, so calling this again for the same text makes a second timer. To change an existing timer, use update_timer. Needs the Kick channel connected to KickBot. Free plans can have 3 timed messages on at a time; over that limit the new one is created off and the response has a `note`.

```http
POST /api/v1/timers
```

Needs a read and write key or connection.

| Field | Type | Required | Description |
|---|---|---|---|
| `text` | string | Yes | The message KickBot posts in chat, up to 500 characters (the same limit as the dashboard). |
| `interval` | integer | No | Minutes between posts. The dashboard offers 5 to 180. Default 30. |
| `spacing` | integer | No | How many chat messages must be sent by viewers between two posts, so the bot does not post into an empty chat. The dashboard offers 1 to 30. Default 3. |
| `enabled` | boolean | No | On (true) or off (false). KickBot posts only timers that are on. Free plans can have 3 timers on at a time: turning one on over the limit fails with limit_reached, and a new timer over the limit is created off. Default true for a new timer. |

## update_timer

**Update a timed message.** Change some fields of a timed message, or turn it on or off. Only the fields you send change.

```http
PATCH /api/v1/timers/{id}
```

Needs a read and write key or connection.

| Field | Type | Required | Description |
|---|---|---|---|
| `text` | string | No | The message KickBot posts in chat, up to 500 characters (the same limit as the dashboard). |
| `interval` | integer | No | Minutes between posts. The dashboard offers 5 to 180. Default 30. |
| `spacing` | integer | No | How many chat messages must be sent by viewers between two posts, so the bot does not post into an empty chat. The dashboard offers 1 to 30. Default 3. |
| `enabled` | boolean | No | On (true) or off (false). KickBot posts only timers that are on. Free plans can have 3 timers on at a time: turning one on over the limit fails with limit_reached, and a new timer over the limit is created off. Default true for a new timer. |
| `id` (in the path) | integer | Yes | The item id. |

## delete_timer

**Delete a timed message.** Delete a timed message.

```http
DELETE /api/v1/timers/{id}
```

Needs a read and write key or connection. This can delete or replace data, and you may not be able to undo it.

| Field | Type | Required | Description |
|---|---|---|---|
| `id` (in the path) | integer | Yes | The item id. |