# move_queued_message

Source: https://modulify.ai/docs/api/chat/move-queued-message

Moves a message that is still waiting in one chat's queue to the end of another chat's queue.

- Title: Move a queued message to another chat
- Scope: `chat:write`
- Access: Makes changes
- Endpoint: `POST /v1/move_queued_message`

Name the message by the `Id` that `list_queued_messages` reported, and the chat to move it to by `toChatId`: `main` for the chat every site comes with, or the `chatKey` of another open chat from `list_chats`. The message joins the end of that chat's queue for everyone, and keeps its text, mode, files and author. Its `QueueVersion` changes, so read the queue again before editing it.

When that chat is idle and its queue is not paused, the message starts there right away, exactly as a new message sent to that chat would. Otherwise it waits at the end of that chat's queue. Moving changes neither queue limit, because both count across all of a site's chats.

It is refused with `That message already left the queue and is running!` once the message has started, with a `400` when `toChatId` names the chat it is already queued in, with a `404` when that chat is closed or does not exist, and with a `403` when the site is locked.

Anyone in the workspace can move any queued message, not only their own, so the tool tells the client to confirm with you before moving a message somebody else queued. See [The row menu](https://modulify.ai/docs/build/message-queue#the-row-menu).

It acts on the chat whose queue holds the message, and the response carries the chat it moved to as `chatId`, the chat it came from as `fromChatId` and the moved entry as `item`.

## Request

Call it with a `POST` to `https://api.modulify.ai/v1/move_queued_message`, sending the inputs below as a JSON object. The token needs the `chat:write` scope.

It makes changes, so send an [Idempotency-Key](https://modulify.ai/docs/api/idempotency) header whenever you might retry it. A retry with the same key gets the first answer back instead of running again.

```bash
curl -X POST https://api.modulify.ai/v1/move_queued_message \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"projectId":"PROJECT_ID","itemId":"ITEM_ID","toChatId":"TO_CHAT_ID"}'
```

Over MCP, the same method is the [move_queued_message tool](https://modulify.ai/docs/mcp/chat/move-queued-message).

## Inputs

| Input | Type | Required | Description |
| --- | --- | --- | --- |
| `projectId` | string | Yes | The site id, from `list_sites` or `get_site`. |
| `itemId` | string | Yes | The `Id` of the queued message to move, exactly as `list_queued_messages` reported it. |
| `toChatId` | string | Yes | The chat to move it to: `main` for the chat every site comes with, or the `chatKey` of another open chat from `list_chats`. It has to be a different chat from the one whose queue holds the message. |
| `chatId` | string | No | The chat whose queue holds the message: `main` for the chat every site comes with, or the `chatKey` of another chat from `list_chats`. Leave it out to act on the chat whose queue holds the message, since message ids are unique across the site. When you pass it, the message has to be queued in that chat. |

## Response

Every call answers with the [JSON envelope](https://modulify.ai/docs/api/requests-and-responses#the-response) of `success`, `message`, `data`, `code` and `version`. `data` holds the result described above, and on a method that returns a total, `count` carries it. The [response headers](https://modulify.ai/docs/api/requests-and-responses#headers-on-every-method-call) carry the call's `X-Request-Id` and what is left of your per-minute budget in `X-RateLimit-Limit`, `X-RateLimit-Remaining` and `X-RateLimit-Reset`. [Errors](https://modulify.ai/docs/api/errors) explains every status code a call can answer with.