> ## Documentation Index
> Fetch the complete documentation index at: https://wiki.petto.sbs/llms.txt
> Use this file to discover all available pages before exploring further.

# Pagination

> One message with several pages of embeds and buttons to turn them.

## Overview

A paginated message is a single message from Petto that holds up to **25 pages**, with buttons underneath to move between them. Use it for rules split into sections, a guide, a list of roles or anything too long for one embed.

`!pagination` (also `!pn` and `!pages`) is a prefix command. It needs **Manage Messages** in the channel of the message, and `reset` needs **Administrator**.

> [!WARNING]
>
> Only messages that Petto sent can have pages: a bot can't edit the messages of other bots or members. Post a new one with `!pagination create`, or take one sent with `!embed send`.

Where a command asks for `<message>`, give any of these:

* The message link (right click or long press on the message, then **Copy Message Link**).
* `#channel` followed by the message ID.
* The message ID alone, when the message is in the channel you are typing in.
* Nothing, when you **reply** to the message with the command.

## Setup

**1. Start the message**

Post a new message with its first page, here or in another channel:

```javascript Syntax theme={null}
!pagination create [#channel] <embed or code> [--private]
```

Or turn a message Petto already sent into page 1, exactly as it is now:

```javascript Syntax theme={null}
!pagination set <message> [--private]
```

```javascript Example theme={null}
!pagination create #rules rules_general
!pagination set https://discord.com/channels/123/456/789
```

![liam runs !pagination create in the rules channel with rules\_general and Petto answers that it posted the message, with the add command to use next](https://mintcdn.com/wikipetto/jIyurMB5tJ_ItdvE/images/discord/resources/pagination-step-1-create.webp?fit=max\&auto=format\&n=jIyurMB5tJ_ItdvE\&q=85\&s=2a5d68cbd057cccffd8be88688ec5c87)

In Discord: !pagination create posts page 1 and says how to add the next one.

![liam runs !pagination set with the link of a message and Petto confirms it is now page 1 of a pagination](https://mintcdn.com/wikipetto/jIyurMB5tJ_ItdvE/images/discord/resources/pagination-step-1-set.webp?fit=max\&auto=format\&n=jIyurMB5tJ_ItdvE\&q=85\&s=7f470d828f6b6c65e8b19935a7912757)

In Discord: !pagination set makes a message Petto sent page 1.

**2. Add the next pages**

Each page goes at the end. Repeat it for every page you want, up to 25.

```javascript Syntax theme={null}
!pagination add <message> <embed or code>
```

```javascript Example theme={null}
!pagination add https://discord.com/channels/123/456/789 rules_voice
!pagination add https://discord.com/channels/123/456/789 {embed}$v{title: Staff}$v{description: Ask any of us for help}
```

![liam adds page 2 from a saved embed and page 3 from a code, and Petto confirms each one](https://mintcdn.com/wikipetto/jIyurMB5tJ_ItdvE/images/discord/resources/pagination-step-2-add.webp?fit=max\&auto=format\&n=jIyurMB5tJ_ItdvE\&q=85\&s=99b732f6727469b8b9fa08a09a92a7c5)

In Discord: !pagination add with a saved embed, then with an embed code.

**3. Change a page**

Put another embed or code in a page by its number. `edit` works as well as `update`.

```javascript Syntax theme={null}
!pagination update <message> <page> <embed or code>
```

```javascript Example theme={null}
!pagination update https://discord.com/channels/123/456/789 2 rules_voice_v2
```

![liam changes page 2 and Petto answers Page 2 changed](https://mintcdn.com/wikipetto/jIyurMB5tJ_ItdvE/images/discord/resources/pagination-step-3-update.webp?fit=max\&auto=format\&n=jIyurMB5tJ_ItdvE\&q=85\&s=0c25a12942c904a3f9aab6d4bad74f29)

In Discord: !pagination update puts another embed in page 2.

**4. Remove a page**

Takes a page out by its number. The only page left can't be removed: use `delete` to stop the pagination instead.

```javascript Syntax theme={null}
!pagination remove <message> <page>
```

```javascript Example theme={null}
!pagination remove https://discord.com/channels/123/456/789 3
```

![liam removes page 3 and Petto says 2 pages are left](https://mintcdn.com/wikipetto/jIyurMB5tJ_ItdvE/images/discord/resources/pagination-step-4-remove.webp?fit=max\&auto=format\&n=jIyurMB5tJ_ItdvE\&q=85\&s=0935570a559a836c3c552cfc0f49c0f3)

In Discord: !pagination remove takes page 3 out and says how many are left.

![kira tries to remove the only page and Petto answers in red with the delete command to use instead](https://mintcdn.com/wikipetto/jIyurMB5tJ_ItdvE/images/discord/resources/pagination-step-4-last-page.webp?fit=max\&auto=format\&n=jIyurMB5tJ_ItdvE\&q=85\&s=eac80f978523e21f5354e8848c031629)

In Discord: the only page cannot be removed: Petto points to delete.

After any change the message goes back to page 1, with the new number of pages.

## Related commands

> [accordion] Stop a pagination or delete its message
>
> The buttons come off and the message stays with the page it is showing. Add `--message` to delete the message too. `del` works as well as `delete`.
>
> ```javascript Syntax theme={null}
> !pagination delete <message> [--message]
> ```
>
> ![liam stops a pagination and Petto says the message is no longer paginated and keeps the page it showed](https://mintcdn.com/wikipetto/jIyurMB5tJ_ItdvE/images/discord/resources/pagination-delete.webp?fit=max\&auto=format\&n=jIyurMB5tJ_ItdvE\&q=85\&s=2c758e7f4e827abf60ded53377c8afbc)
>
> In Discord: !pagination delete takes the buttons off; the message keeps its page.
>
> ![liam runs !pagination delete with --message and Petto confirms the message was deleted](https://mintcdn.com/wikipetto/jIyurMB5tJ_ItdvE/images/discord/resources/pagination-delete-message.webp?fit=max\&auto=format\&n=jIyurMB5tJ_ItdvE\&q=85\&s=397636dc7e83240f9465ab61a046a12e)
>
> In Discord: with --message the message is deleted too.

> [accordion] Stop every pagination of the server
>
> Administrator only. Petto asks first with a **Stop them all** button; the messages keep the page they show.
>
> ```javascript Syntax theme={null}
> !pagination reset
> ```
>
> ![liam runs !pagination reset and Petto asks in red whether to stop the 2 paginated messages, with Stop them all and Cancel](https://mintcdn.com/wikipetto/jIyurMB5tJ_ItdvE/images/discord/resources/pagination-reset.webp?fit=max\&auto=format\&n=jIyurMB5tJ_ItdvE\&q=85\&s=a9fd75c819a23a56ecbe19d6426a8203)
>
> In Discord: !pagination reset asks first, with a Stop them all button.
>
> ![The question changes to Done: 2 paginated messages stopped](https://mintcdn.com/wikipetto/jIyurMB5tJ_ItdvE/images/discord/resources/pagination-reset-done.webp?fit=max\&auto=format\&n=jIyurMB5tJ_ItdvE\&q=85\&s=3ee997c1b4fbad916eaf01862340d3da)
>
> In Discord: after the click: every pagination is stopped.

> [accordion] List the paginated messages
>
> Every paginated message of the server with its channel, number of pages, whether it is private and a link to it, 10 per page.
>
> ```javascript Syntax theme={null}
> !pagination list
> ```
>
> ![Petto lists two paginated messages: rules with 3 pages and server-guide with 7 private pages](https://mintcdn.com/wikipetto/jIyurMB5tJ_ItdvE/images/discord/resources/pagination-list.webp?fit=max\&auto=format\&n=jIyurMB5tJ_ItdvE\&q=85\&s=01f76982889087664f6ca14e8a1279b0)
>
> In Discord: !pagination list: each message with its channel, pages, private or not, and a link.

> [accordion] See the pages of a message
>
> The pages in order (the saved embed of each one, or that it is a code), their kind and whether it is shared or private. `show` and `info` work as well as `view`.
>
> ```javascript Syntax theme={null}
> !pagination view <message>
> ```
>
> ![Petto shows the 4 pages of a message: three saved embeds and one code, shared](https://mintcdn.com/wikipetto/jIyurMB5tJ_ItdvE/images/discord/resources/pagination-view.webp?fit=max\&auto=format\&n=jIyurMB5tJ_ItdvE\&q=85\&s=58c348d0e8bab5e3dd629638786584bd)
>
> In Discord: !pagination view: the pages in order and their kind.

> [accordion] Move a page
>
> ```javascript Syntax theme={null}
> !pagination move <message> <from> <to>
> ```
>
> ```javascript Example theme={null}
> !pagination move https://discord.com/channels/123/456/789 5 2
> ```
>
> ![liam moves page 5 to place 2 and Petto confirms](https://mintcdn.com/wikipetto/jIyurMB5tJ_ItdvE/images/discord/resources/pagination-move.webp?fit=max\&auto=format\&n=jIyurMB5tJ_ItdvE\&q=85\&s=48518a17e84891f7a8dd7159de9ccc8c)
>
> In Discord: !pagination move: page 5 becomes page 2.

> [accordion] Shared or private pages
>
> See [Shared or private](#shared-or-private).
>
> ```javascript Syntax theme={null}
> !pagination mode <message> shared|private
> ```
>
> ![liam sets a pagination to private and Petto explains what that does](https://mintcdn.com/wikipetto/jIyurMB5tJ_ItdvE/images/discord/resources/pagination-mode.webp?fit=max\&auto=format\&n=jIyurMB5tJ_ItdvE\&q=85\&s=59ca77961a690a7dc5d8bd84b46ec8da)
>
> In Discord: !pagination mode private: each click shows the page only to who clicked.

> [accordion] Put the buttons back
>
> Shows page 1 again with its buttons, for when they were taken off or the message was changed with something else (like `!editembed`). `restorereactions` and `rr` work as well as `restore`.
>
> ```javascript Syntax theme={null}
> !pagination restore <message>
> ```
>
> ![liam restores a pagination and Petto says the buttons are back, showing page 1](https://mintcdn.com/wikipetto/jIyurMB5tJ_ItdvE/images/discord/resources/pagination-restore.webp?fit=max\&auto=format\&n=jIyurMB5tJ_ItdvE\&q=85\&s=095cf7f1cc2388687fef6c37aad6af62)
>
> In Discord: !pagination restore puts the buttons back on page 1.

## How the buttons work

Petto uses buttons, not reactions, so it doesn't need **Add Reactions**, the current page is always visible, and the buttons keep working after Petto restarts.

| Pages | What is under the message |
| - | - |
| 1 | No buttons (they appear when you add a second page) |
| 2 to 5 | ◀ · **Page X/Y** · ▶ |
| 6 or more | ⏮ ◀ **Page X/Y** ▶ ⏭, and a **Jump to a page…** menu on a second row |

> [accordion] 2 to 5 pages
>
> ![The first rules page by Petto with the buttons back, Page 1/3 and next under it](https://mintcdn.com/wikipetto/jIyurMB5tJ_ItdvE/images/discord/resources/pagination-buttons-few.webp?fit=max\&auto=format\&n=jIyurMB5tJ_ItdvE\&q=85\&s=359340127e2d01ae750131f64ec03645)
>
> In Discord: three pages: ◀ Page 1/3 ▶.

> [accordion] After a click on ▶
>
> ![The same message now shows the voice channels page and Page 2/3](https://mintcdn.com/wikipetto/jIyurMB5tJ_ItdvE/images/discord/resources/pagination-buttons-next.webp?fit=max\&auto=format\&n=jIyurMB5tJ_ItdvE\&q=85\&s=52fa3acf76c64696a62195503178f18b)
>
> In Discord: a click on ▶ turns the message to page 2 for everyone.

> [accordion] 6 or more pages
>
> ![A guide of 7 pages with the buttons first, back, Page 1/7, next and last, and the jump menu open with its 7 pages](https://mintcdn.com/wikipetto/jIyurMB5tJ_ItdvE/images/discord/resources/pagination-buttons-many.webp?fit=max\&auto=format\&n=jIyurMB5tJ_ItdvE\&q=85\&s=f802cd5d85ff793ddc56f116f47a9e85)
>
> In Discord: seven pages: first and last buttons, and the Jump to a page menu.

The **Page X/Y** button only shows where you are and can't be clicked. Anyone who can see the message can turn its pages.

## Shared or private

* **Shared** (the default): a click turns the message itself, for everyone. The variables of a shared page are filled for the member who made the pagination, so the message doesn't change with each person who clicks. Good for a message a moderator presents.
* **Private** (`--private` on `create` or `set`, or `!pagination mode <message> private`): a click shows the page only to the member who clicked, as a message only they can see, with its variables filled for them. Its own buttons keep turning that copy, and the message in the channel stays on page 1. Good for rules or a guide that many people read at the same time.

![The guide in the channel stays on page 1 while Mia gets page 2 as a message only she can see](https://mintcdn.com/wikipetto/jIyurMB5tJ_ItdvE/images/discord/resources/pagination-private-click.webp?fit=max\&auto=format\&n=jIyurMB5tJ_ItdvE\&q=85\&s=d63cba036daff1890c4a20eeadf604a0)

In Discord: on a private message a click answers with a copy only that member sees.

## What a page can be

Wherever a command asks for `<embed or code>`:

* **The name of a saved embed**, like `rules_general` (one word, see [Embeds](https://wiki.petto.sbs/resources/scripting/embeds.md)). It is drawn each time the page is shown, so its [variables](https://wiki.petto.sbs/resources/scripting/variables.md) are filled then and an edit of the saved embed shows up on the page right away.
* **An embed code**, like `{embed}$v{title: ...}$v{description: ...}`, read the same way as in `!embed create` and `!editembed`. Anything that can't be used is reported.
* **A `p2.` code**, a [Components V2](https://wiki.petto.sbs/resources/scripting/embeds.md#embeds-v2) design copied from the dashboard or the Embed Builder.

With `!pagination set`, page 1 is whatever the message already shows.

> [!NOTE]
>
> **One kind per message.** Discord can't turn a classic message (text and embeds) into a Components V2 one or the other way round, so all the pages of one message are classic embeds or all are V2 designs, decided by the first page. Petto refuses a page of the other kind. If a saved embed used by a page is later changed into the other kind, that page shows an error until you change it with `update`.

![liam adds rules\_v2 to a message of embeds and Petto answers in red that one message cannot mix both kinds](https://mintcdn.com/wikipetto/jIyurMB5tJ_ItdvE/images/discord/resources/pagination-kind-refused.webp?fit=max\&auto=format\&n=jIyurMB5tJ_ItdvE\&q=85\&s=3a72f9731189abd0519487ea44425c33)

In Discord: a V2 design refused on a message of classic embeds.

A classic page keeps at most **3 rows** of its own link buttons, because the page buttons and the jump menu take the other two.

## Limits

| | Free | Premium |
| - | - | - |
| Pages per message | 25 | 25 |
| Paginated messages per server | 25 | 50 |

When a server reaches its number, `create` and `set` say so; stop one with `delete` to make room. See [Premium](https://wiki.petto.sbs/overview/premium.md#limits-per-server).

![liam tries to create one more and Petto says the server has its 25 paginated messages, and Premium gives 50](https://mintcdn.com/wikipetto/jIyurMB5tJ_ItdvE/images/discord/resources/pagination-limit.webp?fit=max\&auto=format\&n=jIyurMB5tJ_ItdvE\&q=85\&s=9a402a7a327cde4df9ecc7c5bc222e6c)

In Discord: a free server with its 25 paginated messages.

## Dashboard

On the dashboard, the **Embeds** page has a **Paginated messages** section under the editor.

* **The list** shows each paginated message with its channel, its pages in order, a **Private** or **V2** tag and **Open in Discord**. Each one has **Put the buttons back**, **Stop** (takes the buttons off, the message stays) and **Delete message** (deletes it from Discord).
* **New paginated message** builds one from saved embeds: pick a **Channel**, choose the saved embed of each page under **Pages, in order** (with **Add a page**, move up, move down and remove), tick **Private pages** if you want, and press **Post**.

![Three paginated messages: rules with 4 pages, server-guide with 7 private pages and a V2 one in announcements, each with Put the buttons back, Stop and Delete message](https://mintcdn.com/wikipetto/NNb0rgWpeffY0EDH/images/dashboard/resources/pagination-dashboard-list.webp?fit=max\&auto=format\&n=NNb0rgWpeffY0EDH\&q=85\&s=cadef0ffecc404d2e832c0663cd69bee)

Dashboard → Design → Embeds → Paginated messages: each message with its channel, pages and tags, and its three buttons.

![The builder with the channel server-guide, three pages in order with move and remove buttons, the Private pages box and the Post button](https://mintcdn.com/wikipetto/NNb0rgWpeffY0EDH/images/dashboard/resources/pagination-dashboard-new.webp?fit=max\&auto=format\&n=NNb0rgWpeffY0EDH\&q=85\&s=fe910b4ab05d16e13f018f8ab3a533fa)

Dashboard → Design → Embeds → New paginated message: the channel, the saved embed of each page, Private pages and Post.

The dashboard needs the same **Manage Messages** as the command. Embed codes, `p2.` codes and changing one page at a time are done with the command.

## Common issues

> [accordion] I can only add pages to messages that I sent
>
> The message was sent by a member, a webhook or another bot. Send it again with `!embed send`, then use `!pagination set`, or start with `!pagination create`.
>
> ![kira runs !pagination set on her own message and Petto answers in red that it can only add pages to its own messages](https://mintcdn.com/wikipetto/jIyurMB5tJ_ItdvE/images/discord/resources/pagination-not-mine.webp?fit=max\&auto=format\&n=jIyurMB5tJ_ItdvE\&q=85\&s=6c1dc907f938f8d458fc59eeb54e9892)
>
> In Discord: a message of a member cannot get pages.

> [accordion] I need these permissions in that channel
>
> Petto needs **View Channel** and **Read Message History** in the channel of the message, and to post a new one with `create` also **Send Messages** and **Embed Links**. The reply names the ones missing. You need **Manage Messages** in that channel yourself.
>
> ![Petto answers in red that it needs Read Message History in that channel](https://mintcdn.com/wikipetto/jIyurMB5tJ_ItdvE/images/discord/resources/pagination-bot-permissions.webp?fit=max\&auto=format\&n=jIyurMB5tJ_ItdvE\&q=85\&s=3039a6a0ec5586999a80fa2e919f67f5)
>
> In Discord: the reply names the permission Petto is missing.

> [accordion] The message or its channel no longer exists
>
> Deleting a paginated message, or its channel, removes its pages from Petto too, so it stops counting toward the limit. A command that points at it says the pages were removed.
>
> ![Petto answers that the message no longer exists, so its pages were removed](https://mintcdn.com/wikipetto/jIyurMB5tJ_ItdvE/images/discord/resources/pagination-gone.webp?fit=max\&auto=format\&n=jIyurMB5tJ_ItdvE\&q=85\&s=73c528203c391d55eb5a1d1b3429852a)
>
> In Discord: a deleted message: its pages were removed too.

> [accordion] The buttons disappeared
>
> Someone edited the message with something else. Use `!pagination restore <message>`, or **Put the buttons back** on the dashboard. If the pagination was stopped with `delete`, its pages are gone: start again with `!pagination set` and add them back.

> [accordion] A page shows an error
>
> Its saved embed was deleted, or changed into the other kind (classic or V2). Give the page another embed with `!pagination update`.
>
> ![Under the rules message Petto tells Mia, only for her, that the saved embed of that page was deleted and how to change the page](https://mintcdn.com/wikipetto/jIyurMB5tJ_ItdvE/images/discord/resources/pagination-page-error.webp?fit=max\&auto=format\&n=jIyurMB5tJ_ItdvE\&q=85\&s=71e353f45d3f5b9cbbc8ee7b5afbc792)
>
> In Discord: the saved embed of page 2 was deleted: the click answers with the error.


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