Heyzine Flipbooks

View saved version →

---
name: bookshelf-collections
description: Organize existing Heyzine flipbooks in bookshelf collections. Use when users ask to list shelves, inspect contents, add, remove, or position flipbooks, update a social preview, or ask about bookshelf creation and ordering limits.
---

# Heyzine bookshelf collections

A bookshelf references existing flipbooks. Adding or removing membership does
not copy or delete the flipbook.

## Inputs and boundaries

- Identify a bookshelf and flipbook by id, public URL, short id, or an
  unambiguous title returned by the list tools.
- In membership tools, `id` is the bookshelf and `flipbook_id` is the
  flipbook. Never transpose them.
- There is no tool to create, delete, or reorder an existing bookshelf. Explain
  that those actions require the Heyzine bookshelf editor.
- If bookshelves are unavailable for the account, report the server's plan
  error. Do not invent a substitute collection.

## Resolve names

1. Call `heyzine_list_bookshelves` to resolve a shelf title.
2. Call `heyzine_list_flipbooks` to resolve a flipbook title.
3. Proceed on one clear match. If several entries plausibly match, show their
   titles, ids, and URLs and ask the user to choose. If none match, report that
   and stop.

Do not rely on a remembered list when the user asks about current membership.

## Inspect a bookshelf

Call `heyzine_list_bookshelf_flipbooks` with the bookshelf `id`. Preserve the
returned display order and positions when answering what visitors see.

## Add flipbooks

Call `heyzine_add_to_bookshelf` once for each flipbook with `id` and
`flipbook_id`. Pass optional `position` only when the user specifies placement;
it is zero-based. A flipbook may belong to several shelves.

For a batch request, list and resolve the matching flipbooks first. Add only
clear matches, then report the added count and any skipped or failed items.

## Remove flipbooks

Call `heyzine_remove_from_bookshelf` with the shelf `id` and `flipbook_id`. This
removes only the membership. If "remove" or "delete" could mean deleting the
flipbook itself, clarify before acting. Never call `heyzine_delete_flipbook`
for an unqualified shelf change.

## Update the social preview

`heyzine_set_bookshelf_social` controls how the shelf's link renders when
shared. Pass `id` plus only the requested `title`, `description`, and
`thumbnail` fields. `thumbnail` must be a public image URL. Do not invent
missing metadata.

## Report the result

After membership changes, list the shelf once to verify the current contents.
Return the bookshelf URL, the resulting count, and any failures. For a batch,
summarize counts instead of narrating every tool call.

Referenced files: 1

View saved version →

---
name: flipbook-access-control
description: Configure access to Heyzine flipbooks and bookshelves. Use when users ask to enable or disable protection, set a shared password, grant individual access, revoke credentials, or audit available access data.
---

# Access control for flipbooks and bookshelves

Protection has a publication mode and, for individual access, credential
entries.

## Inputs and boundaries

- Resolve the target from an id, public URL, short id, or an unambiguous title
  returned by `heyzine_list_flipbooks` or `heyzine_list_bookshelves`.
- Set `type` to `bookshelf` for a bookshelf and `flipbook` for a flipbook.
- If a title is ambiguous, show the candidates and ask which one. Never guess
  the target, protection mode, password, email address, or current access list.
- No MCP tool lists current access entries. If asked who has access, explain
  that the current list must be checked in the Heyzine access settings.

## Set the protection mode

Call `heyzine_access_setup` with `id`, `type`, and one of:

| Mode | Behavior |
| --- | --- |
| `everyone` | One shared password; requires `password` |
| `users` | Only entries added to the access list can open it |
| `disabled` | Removes the access gate and makes the publication public |

Optional `text_user` and `text_password` relabel the fields on the login
screen. Send them only when the user supplies the labels.

Use `everyone` for one password shared by all visitors. Use `users` when access
must be managed per person or credential. Before switching to `disabled`,
state the exact title and explain that the publication will become public,
then obtain confirmation unless the user already confirmed that exact change.

Never invent a password. If one is required, ask for it or offer to generate
one; generate it only after the user accepts.

## Grant individual access

Call `heyzine_access_add` with `id`, `type`, `access_type`, and the required
credential:

| `access_type` | Required input | Visitor flow |
| --- | --- | --- |
| `user_pass` | `user` and `password` | Username and password |
| `google` | `user` email | Google sign-in |
| `pass_only` | `password` | Password without a username |
| `otp` | `password` | Predefined one-time password |
| `email_link` | `user` email | Sign-in link by email |
| `send_code` | `user` email | Generated code sent by email |
| `email_code` | `user` email | Code delivered by email |

`email_link`, `send_code`, and `email_code` require a plan with password email
support. If the server rejects the plan, report its message and stop. Do not
silently switch to another access type.

For `users` mode, configure the mode before adding entries. For a batch, add
one entry per call and report each failure without changing the requested
credential type.

## Revoke individual access

Call `heyzine_access_remove` with `id`, `type`, and either `user` or `password`
to identify the entry. Confirm the exact publication and entry when either is
ambiguous. Do not disable the entire protection mode as a substitute for a
failed removal.

## Handle credentials

Do not write passwords into files or artifacts unless the user explicitly asks
for a credential document. Repeat a supplied or generated shared password only
when the user needs it for distribution. Never claim that an earlier
conversation entry reflects the current server-side access list.

## Report the result

State the publication, resulting mode, and the entry added or removed. For a
shared password, explain what visitors must enter without exposing unrelated
credentials.

Referenced files: 1

View saved version →

---
name: flipbook-embedding
description: Embed Heyzine flipbooks and manage social sharing metadata. Use when users ask for embed HTML, website or CMS placement, or link preview titles, descriptions, and thumbnails.
---

# Embedding and sharing flipbooks

Keep embedding and social previews as separate workflows. Do not change
publication design or access settings unless the user asks.

## Resolve the target

- Accept a public flipbook URL directly.
- If the user gives an id, short id, or title, use
  `heyzine_flipbook_details` and `heyzine_list_flipbooks` as needed to get the
  canonical URL.
- If a title is ambiguous, list the candidates and ask which one. Never
  assemble or guess a publication URL.

## Return embed HTML

1. Call `heyzine_oembed` with the canonical public URL. Pass `maxwidth` or
   `maxheight` only when the user supplied a size constraint.
2. Return the `html` field in a code block without changing its iframe
   attributes.
3. If oEmbed returns an error, report it and stop. Do not fabricate embed HTML.

Access protection remains active inside an embed. Do not disable protection to
make an embed unless the user explicitly requests that separate change.

For WordPress, first suggest pasting the canonical URL into an embed block; use
the returned HTML in a Custom HTML block if auto-embedding is unavailable. For
a CMS that strips iframes, return the public link instead. Ask which platform
only when its placement requirements affect the answer.

If the user asks for responsive behavior, wrap the unmodified iframe rather
than rewriting its attributes.

## Update a social preview

Choose the tool by publication type:

- `heyzine_set_flipbook_social` for a flipbook.
- `heyzine_set_bookshelf_social` for a bookshelf.

Resolve an ambiguous title with the matching list tool. Pass the publication
`id` and only the fields the user wants to change:

| Field | Requirement |
| --- | --- |
| `title` | Social card headline |
| `description` | Social card description |
| `thumbnail` | Publicly reachable image URL |

Do not invent missing copy or a thumbnail URL. If the user asks to repair a
complete card but provides only some fields, ask for the missing content. A
landscape image near 1200 by 630 pixels is a useful recommendation, not a
requirement.

Social networks cache previews. After a successful update, explain that an
already-shared URL may keep the old card until that network refreshes it.

## Report the result

For embedding, lead with the exact HTML and the canonical URL. For social
metadata, state which fields changed and return the publication URL when it is
available.

Referenced files: 1

View saved version →

---
name: flipbook-publishing
description: Publish and manage Heyzine flipbooks from attached documents or public URLs. Use when users ask to convert, list, inspect, brand, update, replace, or delete a flipbook.
---

# Publishing Heyzine flipbooks

Use this skill to turn supported documents into flipbooks and manage existing
flipbooks.

## Inputs and boundaries

- Accept an attached file object or a direct public document URL.
- Accept PDF, DOC, DOCX, PPT, PPTX, ODT, ODP, and RTF documents.
- Identify existing flipbooks by an id, public URL, short id, or an unambiguous
  title from `heyzine_list_flipbooks`.
- Never invent a file URL, attachment id, publication id, account plan, or
  conversion result.
- If the source is only a local path, ask the user to attach the file. If a
  title matches several flipbooks, show the candidates and ask which one.

## Convert a document

Choose the tool from the source:

- For a file attached or selected in the current conversation, call
  `heyzine_convert_attached_pdf`. Pass the current attachment object as `pdf`;
  it requires `download_url` and `file_id`, with `mime_type` and `file_name`
  when available. Do not reuse a signed URL from an earlier attachment. This
  call returns the finished flipbook and must not be polled.
- For a public URL, call `heyzine_convert_pdf_async`. While its state is
  `started`, call it again with the same URL at reasonable intervals. Stop when
  it returns `processed` or a tool error. Do not start another conversion with
  a changed URL as a polling workaround.
- Use blocking `heyzine_convert_pdf` only when the user needs one-call
  completion and the document is expected to finish within the client timeout.
  If it times out, check the same URL with `heyzine_convert_pdf_async`; do not
  assume the conversion failed.

Send only settings the user supplied or that the workflow resolved. When the
user asks to reuse branding, call `heyzine_list_flipbooks`, resolve the source
flipbook, and pass its id as `template`. Do not ask about a template when the
user did not request branding reuse.

Read [references/design-options.md](references/design-options.md) before setting
design or publication fields.

## Manage an existing flipbook

- Use `heyzine_list_flipbooks` with optional `offset` and `limit` to find
  candidates. Filter returned items only after retrieving them.
- Call `heyzine_flipbook_details` before an update when the current settings or
  URL matter.
- Call `heyzine_update_flipbook_design` with the target `id` and only the
  fields to change. Then call `heyzine_flipbook_details` to return the current
  URL and verify the result.
- Call `heyzine_replace_flipbook_pdf` only when the user explicitly asks to
  replace an existing source document. It requires a public document URL and
  is available only to eligible, support-enabled accounts. Preserve the target
  id; do not fall back to creating a separate flipbook without asking.
- `heyzine_delete_flipbook` is permanent. Before calling it, resolve and state
  the exact title and id, then obtain confirmation unless the user already
  confirmed that exact target. Never delete as an unrequested cleanup step.

Changing `url_path` or `url_domain` can break existing links. Confirm the exact
change before applying it when the flipbook may already be shared. If a paid
feature is rejected, report the server's plan message and stop; do not infer a
different subscription or silently remove the requested setting.

## Report the result

Lead with the live flipbook URL. Include the id and page count when returned,
plus any template or design choice applied. For a running async conversion,
report its id, URL, and current state without claiming it is finished.

Referenced files: 2