Collections

A collection is a named set of testimonials, and it is what a widget or a wall shows. You can pick the testimonials yourself and put them in order, or write a few rules and let the collection keep itself current as testimonials arrive and change.

Open Testimonials in the site's sidebar, then the Collections tab. The page is at /sites/<site id>/testimonials/collections.

Manual and smart#

A collection is one of two kinds. You choose the kind when you create it, and it never changes afterward.

Nothing is copied into a smart collection. Change a rating, a tag or a status, and the testimonial joins or leaves by itself.

A collection can hold testimonials that are pending or rejected. Widgets and walls show only the approved ones, and the collection's page says so when some are not approved.

The Collections page#

A member who may only read sees the list and each collection, without the buttons and menus that change anything.

Creating a collection#

A new smart collection starts with one condition, "Status is Approved". Remove it if yours should hold other statuses too.

Served in this order takes one of these:

A manual collection starts empty. Add testimonials from the inbox: select some and press C, or use a row's menu. New ones join at the bottom.

A collection's page#

The header has Edit (the E key does the same) and Use in a widget, which opens a new widget fed by this collection.

The card under it shows, for a smart collection, its rules as one sentence, "Kept current by its rules." and the order it is served in. For every collection it shows the counts ("86 testimonials, 80 approved") and what it feeds.

Below that are its testimonials, in the order they are served. The switch at the top right of the list draws them as rows or as cards. Each row has the inbox's own menu, and ticking rows opens the inbox's bulk bar. In a manual collection the bar offers Remove from collection. In a smart one it offers Add to collection, for putting the selection in a manual collection.

Manual order#

The order of a manual collection is the order every widget and wall it feeds will show. In the rows layout each row carries its position number, a drag handle and an order menu.

The order menu works with a keyboard, on a phone and with JavaScript turned off. On a narrow screen the drag handle is not shown, so the menu is the way to reorder. The cards layout is for reading and has no order controls.

Adding and removing can be undone for 7 days. A toast with Undo appears after each one, and the change is in the undo list. An undo of a removal puts the testimonial back at the position it had. Reordering has no undo: move the row back.

A smart collection cannot be added to or reordered by hand.

The rule builder#

A smart collection's rules are rows of a field, an operator and a value. Above the rows you choose whether a testimonial must match all of the conditions or any of them. Each field offers only the operators that fit it. A fixed set of values is a menu or a checklist, and a checklist of more than 8 values has a box that narrows it.

Under the rows the builder shows the rules as one sentence, how many testimonials match right now, and up to five examples. A row that is not finished shows its error on the row.

Nothing is saved until you press Save. With JavaScript off, each of these three buttons draws the form again with what you typed.

Rule fields#

These are the fields a smart collection can test, in the order the builder lists them. The second column is the name the API and MCP use in field, and the third lists the values of operator.

What the operators mean:

• With Words, contain needs every phrase, contain_any_of needs one of them, and do_not_contain needs none of them. Words are matched through the search index, which stems them in the eleven languages Mentions lists, so in English "ship" also finds "shipping".
• With Tag, has_any_of needs one of the tags, has_all_of needs every one, has_none_of needs none of them, and has_no_tags matches a testimonial with no tag at all.
• With Consent, is_on_record means the person gave consent, and is_source_only means only the source of the testimonial is on record. includes needs consent on record with every permission you tick.
• Dates are days on the site's own clock.
• A negative operator also matches where the value is missing. "Rating is not 5" includes testimonials with no rating.
• One condition takes up to 100 values. A checklist in the form offers up to 200 tags, forms, platforms or languages.

Custom properties offer operators by their type:

An archived property is not offered. A smart collection cannot test whether a testimonial is in another collection.

Moving a collection to the trash#

Move to trash is in the row menu of the list and at the foot of the edit page. The collection stays in the trash for 30 days and can be restored exactly as it was. Its testimonials are not touched.

If the collection feeds a widget or a wall, the confirmation names each one. They show nothing from it until it is restored.

Smart collections on Free and Pro#

Smart collections are part of the Business plan. Manual collections are on every plan. On Free and Pro:

A smart collection made on Business is kept after a downgrade, and it is locked:

• Its page says "This smart collection is locked" with the date, and the line "Kept current by its rules." is gone. The API returns it with locked: true.
• It still reads its rules, but only over testimonials received on or before the day the plan changed. Nothing received later joins. A testimonial from before that day still joins or leaves when it starts or stops matching, for example when it is rejected.
• Widgets and walls that show it keep showing its approved testimonials.
• Its rules and its served order cannot be changed. testimonial_collections_update with conditions, match or sort responds with 402 plan_limit, and with only name or description it saves. The edit page shows the rules in words with a lock and sends none, so renaming it or changing its description there saves.
• It can be moved to the trash and restored.
• It is up to date again as soon as the plan includes smart collections. Nothing has to be rebuilt.

API and MCP#

Every action on these pages is an API operation and an MCP tool. Add .json to the address of a page, or call the tool. Inputs and response fields are in the generated reference at /docs/api and /docs/mcp.

Rules are sent as match (all or any) and conditions, a list of rows with field, operator and value:

{
  "tool": "testimonial_collections_create",
  "arguments": {
    "site_id": "pa_4K7QW2MX9A",
    "name": "Five star video",
    "kind": "smart",
    "sort": "rating_desc",
    "conditions": [
      { "field": "status", "operator": "is", "value": "approved" },
      { "field": "rating", "operator": "is", "value": 5 },
      { "field": "has_video", "operator": "is_yes" }
    ]
  }
}

• To read a collection's testimonials, call testimonials_list with collection_id.
• testimonial_collections_create takes up to 100 testimonial_ids to start a manual collection filled, in that order.
• testimonial_collections_add_items and _remove_items take up to 100 ids. Adding puts new ones at the bottom, or at the top with position: top. One that is already in the collection stays where it is. When something changed, the response has meta.undo_id, which testimonials_bulk_undo takes for 7 days.
• testimonial_collections_reorder takes exactly one of position (counted from 1), before_id and after_id.
• testimonial_collections_preview with use: tag checks the rows as an auto-tag rule, which tests a shorter list of fields. With explain: true a row that does not read is listed in problems instead of being an error.
• A row that does not read is a 422 whose sentence names the row ("Row 2: Choose a field and an operator."). An id that is not a testimonial of the site has the code unknown_ids, and more than 100 ids the code too_many.
• An AI assistant cannot delete anything or move anything to the trash. The MCP tool testimonial_collections_destroy runs nothing: it responds with human_only and the address of the collection's page, and the assistant hands you that link. The API call runs as usual. Taking testimonials out of a manual collection deletes nothing, so testimonial_collections_remove_items runs over MCP.

Ask your assistant:

• "Make a collection of our approved five-star video testimonials, best rated first."
• "Put the three newest approved testimonials about delivery at the top of Homepage picks."
• "Move the Daniel Okonkwo quote to second place in the Sales deck collection."

Good to know#

• The counts of a smart collection are kept for up to 10 minutes. A change to a testimonial, a tag or a collection of the site refreshes them at once. Rules that read the clock, such as "Received in the last 30 days", can lag by up to those 10 minutes.
• A smart collection whose rule names a tag in the trash matches nothing until the tag is restored or the rule is changed.
• A testimonial in the trash is in no collection. Restoring it puts it back in the manual collections it was in, at its place.
• Reordering a manual collection leaves no undo record.
• A collection in the trash feeds nothing. Its widgets and walls show nothing from it until it is restored.