Developers

Zinn® Chat abilities reference

Zinn® Chat registers its actions with the WordPress Abilities API. The same abilities are MCP tools on the site's own server and REST routes under /wp-json/wp-abilities/v1. This page is generated from the plugin's own registry.

User guide: connect an AI app

Zinn®, our Viking, cheering as an AI assistant connects to the platform's tools.

Endpoints

MCP over HTTP (streamable)

https://example.com/wp-json/zinn-chat/v1/mcp

MCP over WP-CLI (standard input and output)

wp mcp-adapter serve --server=zinn-chat --user=<login>

REST: list the abilities

/wp-json/wp-abilities/v1/abilities?category=zinn-chat

REST: run an ability

/wp-json/wp-abilities/v1/abilities/<name>/run

Authentication and permissions

HTTP requests authenticate with a WordPress application password (HTTP Basic). Connecting to the MCP server needs the capability shown below; every ability then checks its own permission, per object. Read-only abilities run with GET and their input in the query string; the others with POST and a JSON body {"input": {…}}.

Examples

# REST: run an ability
curl -u your-username:your-application-password \
  "https://example.com/wp-json/wp-abilities/v1/abilities/zinn-chat/get-overview/run"
# MCP (JSON-RPC over HTTP, after "initialize")
{"jsonrpc":"2.0","id":2,"method":"tools/call","params":{"name":"zinn-chat-get-overview","arguments":{}}}

All abilities

Generated from the plugin's abilities.json, which is itself generated from a running site; a test fails when the two disagree.

AbilityWhat it doesEditionRESTPermissionParameters
zinn-chat/answer-ticket
zinn-chat-answer-ticket
Answer a ticket
Replies to the customer by email (text), or adds an internal note (note: true); status optionally changes the ticket's status.
Free editionPOST …/abilities/zinn-chat/answer-ticket/runthe REST route's own per-item permission checkid: string (required)
zinn-chat/ask-assistant
zinn-chat-ask-assistant
Ask the assistant
Asks the site's AI assistant a question and returns its answer with every source it found.
Free editionPOST …/abilities/zinn-chat/ask-assistant/runthe REST route's own per-item permission checkquestion: string (required), language: string
zinn-chat/bulk-update-tickets
zinn-chat-bulk-update-tickets
Change many tickets at once (Pro)
Changes the status, priority or assignee of up to 100 tickets (ids). Each ticket goes through the same checks as changing it on its own; the result lists each one.
Pro editionPOST …/abilities/zinn-chat/bulk-update-tickets/runzinn_chat_answerids: array (required), status: open|pending|solved|closed, priority: low|normal|high|urgent, assignee_id: integer
zinn-chat/chat-to-ticket
zinn-chat-chat-to-ticket
Turn a chat into a ticket
Opens a ticket from a chat so it can be answered by email (needs the visitor's email address).
Free editionPOST …/abilities/zinn-chat/chat-to-ticket/runthe REST route's own per-item permission checkid: string (required)
zinn-chat/close-chat
zinn-chat-close-chat
Close a chat
Ends a chat; the visitor can still ask for the transcript.
Free editionPOST …/abilities/zinn-chat/close-chat/runthe REST route's own per-item permission checkid: string (required)
zinn-chat/create-ticket
zinn-chat-create-ticket
Open a ticket
Opens a ticket on a customer's behalf (their email, a subject and the first message).
Free editionPOST …/abilities/zinn-chat/create-ticket/runthe REST route's own per-item permission checkemail: string (required), subject: string (required), body: string (required), name: string
zinn-chat/delete-canned-reply
zinn-chat-delete-canned-reply
Delete a saved reply (Pro)
Deletes a saved reply.
Pro editionPOST …/abilities/zinn-chat/delete-canned-reply/runthe REST route's own per-item permission checkid: string (required)
zinn-chat/delete-ticket
zinn-chat-delete-ticket
Delete a ticket
Deletes a ticket and its conversation for good (managers only).
Free editionPOST …/abilities/zinn-chat/delete-ticket/runthe REST route's own per-item permission checkid: string (required)
zinn-chat/draft-kb-article
zinn-chat-draft-kb-article
Draft a help article from a ticket (Pro)
Writes a draft knowledge-base article from a solved ticket; it stays a draft until a person publishes it.
Pro editionPOST …/abilities/zinn-chat/draft-kb-article/runedit_posts (the REST route's own check)ticket: integer (required)
zinn-chat/draft-kb-from-gaps
zinn-chat-draft-kb-from-gaps
Draft help articles for unanswered questions (Pro)
Writes draft knowledge-base articles answering the chosen questions (ids); they stay drafts.
Pro editionPOST …/abilities/zinn-chat/draft-kb-from-gaps/runedit_posts (the REST route's own check)ids: array (required)
zinn-chat/fill-canned-reply
zinn-chat-fill-canned-reply
Fill in a saved reply (Pro)
Returns a saved reply's text with its placeholders filled for one chat or ticket.
Pro editionPOST …/abilities/zinn-chat/fill-canned-reply/runthe REST route's own per-item permission checkid: string (required)
zinn-chat/get-chat
zinn-chat-get-chat
Read a chat
Returns one chat's messages and visitor details (after: only messages newer than this id).
Free editionGET …/abilities/zinn-chat/get-chat/runthe REST route's own per-item permission checkid: string (required)
zinn-chat/get-overview
zinn-chat-get-overview
Read the support overview
Returns how many tickets are in each status and how many chats are waiting for a person (and their unread messages), and whether the chat, the assistant and tickets are switched on.
Free editionGET …/abilities/zinn-chat/get-overview/runzinn_chat_answernone
zinn-chat/get-settings
zinn-chat-get-settings
Read the chat settings
Returns every chat setting: the widget, the assistant, people and opening hours, tickets and email, the site index, privacy and spam.
Free editionGET …/abilities/zinn-chat/get-settings/runzinn_chat_managenone
zinn-chat/get-stats
zinn-chat-get-stats
Read support statistics (Pro)
Returns chat and ticket numbers, response times and ratings for the last N days (days).
Pro editionGET …/abilities/zinn-chat/get-stats/runthe REST route's own per-item permission checkdays: integer
zinn-chat/get-ticket
zinn-chat-get-ticket
Read a ticket
Returns one ticket with its whole conversation, status, priority and assignee.
Free editionGET …/abilities/zinn-chat/get-ticket/runthe REST route's own per-item permission checkid: string (required)
zinn-chat/hand-chat-to-assistant
zinn-chat-hand-chat-to-assistant
Hand a chat back to the assistant
Returns a chat to the AI assistant, which answers the visitor from the site's content.
Free editionPOST …/abilities/zinn-chat/hand-chat-to-assistant/runthe REST route's own per-item permission checkid: string (required)
zinn-chat/list-canned-replies
zinn-chat-list-canned-replies
List saved replies (Pro)
Lists the saved replies agents can insert, with their shortcuts.
Pro editionGET …/abilities/zinn-chat/list-canned-replies/runthe REST route's own per-item permission checknone
zinn-chat/list-chats
zinn-chat-list-chats
List live chats
Lists the chats waiting, in progress and recently closed, with who is handling each.
Free editionGET …/abilities/zinn-chat/list-chats/runthe REST route's own per-item permission checkview: active|bot|closed|all
zinn-chat/list-indexed-content
zinn-chat-list-indexed-content
List what the assistant knows
Lists the content the assistant answers from, with its index status, a page at a time.
Free editionGET …/abilities/zinn-chat/list-indexed-content/runthe REST route's own per-item permission checksearch: string, status: indexed|pending|error, page: integer
zinn-chat/list-kb-gaps
zinn-chat-list-kb-gaps
List unanswered questions (Pro)
Lists the questions visitors asked that the knowledge base could not answer.
Pro editionGET …/abilities/zinn-chat/list-kb-gaps/runthe REST route's own per-item permission checkstatus: open|drafted|answered|ignored|all, page: integer
zinn-chat/list-tickets
zinn-chat-list-tickets
List tickets
Lists support tickets, filtered by status or a search, a page at a time.
Free editionGET …/abilities/zinn-chat/list-tickets/runthe REST route's own per-item permission checkstatus: active|open|pending|solved|closed|all, search: string, page: integer
zinn-chat/reembed-content
zinn-chat-reembed-content
Rebuild the assistant's search index
Rebuilds the search vectors for one item (item_id) or everything (all: true) (managers only).
Free editionPOST …/abilities/zinn-chat/reembed-content/runthe REST route's own per-item permission checkall: boolean, item_id: integer
zinn-chat/reindex-content
zinn-chat-reindex-content
Re-read content into the assistant
Re-reads one item (item_id) or everything (all: true) into the assistant's index (managers only).
Free editionPOST …/abilities/zinn-chat/reindex-content/runthe REST route's own per-item permission checkall: boolean, item_id: integer
zinn-chat/reply-chat
zinn-chat-reply-chat
Reply in a chat
Sends a message to the visitor (text), or adds an internal note only agents see (note: true).
Free editionPOST …/abilities/zinn-chat/reply-chat/runthe REST route's own per-item permission checkid: string (required)
zinn-chat/save-canned-reply
zinn-chat-save-canned-reply
Save a saved reply (Pro)
Creates or changes a saved reply (title, shortcut, body, department; id to change one).
Pro editionPOST …/abilities/zinn-chat/save-canned-reply/runthe REST route's own per-item permission checkid: integer, title: string (required), body: string (required), shortcut: string, department: string
zinn-chat/save-kb-article
zinn-chat-save-kb-article
Write a help article (Pro)
Creates a knowledge-base article, or changes one (id): title, content, excerpt, categories and status (draft, or publish when you may publish).
Pro editionPOST …/abilities/zinn-chat/save-kb-article/runedit_postsid: integer, title: string, content: string, excerpt: string, categories: array, status: draft|publish
zinn-chat/search-kb
zinn-chat-search-kb
Search the knowledge base (Pro)
Finds help articles to link in a reply (q: the search).
Pro editionGET …/abilities/zinn-chat/search-kb/runthe REST route's own per-item permission checkq: string (required)
zinn-chat/set-conversation-details
zinn-chat-set-conversation-details
Set a conversation's department and tags (Pro)
Sets the department and tags of a chat or ticket (kind: chat or ticket; id).
Pro editionPOST …/abilities/zinn-chat/set-conversation-details/runthe REST route's own per-item permission checkkind: ticket|chat, id: integer (required), department: string, tags: array
zinn-chat/set-kb-gap-status
zinn-chat-set-kb-gap-status
Mark unanswered questions (Pro)
Marks unanswered questions as open, planned or dismissed (ids, status).
Pro editionPOST …/abilities/zinn-chat/set-kb-gap-status/runthe REST route's own per-item permission checkids: array (required), status: open|drafted|answered|ignored (required)
zinn-chat/set-presence
zinn-chat-set-presence
Set your availability
Marks the signed-in agent available or away for new chats (away: true or false).
Free editionPOST …/abilities/zinn-chat/set-presence/runthe REST route's own per-item permission checkaway: boolean
zinn-chat/suggest-reply
zinn-chat-suggest-reply
Draft a reply with AI (Pro)
Drafts a reply to a chat or ticket from the site's content; nothing is sent.
Pro editionPOST …/abilities/zinn-chat/suggest-reply/runthe REST route's own per-item permission checkkind: ticket|chat, id: integer (required)
zinn-chat/summarise-conversation
zinn-chat-summarise-conversation
Summarise a conversation with AI (Pro)
Summarises a chat or ticket in a few lines.
Pro editionPOST …/abilities/zinn-chat/summarise-conversation/runthe REST route's own per-item permission checkkind: ticket|chat, id: integer (required)
zinn-chat/take-chat
zinn-chat-take-chat
Take a chat
Assigns a waiting chat to the signed-in agent, so the visitor talks to a person.
Free editionPOST …/abilities/zinn-chat/take-chat/runthe REST route's own per-item permission checkid: string (required)
zinn-chat/update-settings
zinn-chat-update-settings
Change the chat settings
Changes the settings you send (settings: key to value) and keeps the rest. Each value is checked exactly as on the settings screen; get-settings lists the keys.
Free editionPOST …/abilities/zinn-chat/update-settings/runzinn_chat_managesettings: object (required)
zinn-chat/update-ticket
zinn-chat-update-ticket
Change a ticket
Changes a ticket's status, priority or assignee.
Free editionPOST …/abilities/zinn-chat/update-ticket/runthe REST route's own per-item permission checkid: string (required)

Actions and filters

Every hook the plugin offers, with the description from its source code. Filters change a value; actions let you run code at a moment; entry points are actions you fire to ask the plugin to do something.

HookKindWhat it doesParametersEdition
zinn_chat_admin_pagesFilterFilters the Zinn® Chat admin screens (Pro adds its own).noneFree edition
zinn_chat_agent_chatFilterFilters the chat payload for the agent console (Pro adds visitor details, notes, KB suggestions).noneFree edition
zinn_chat_agent_pagesFilterFilters the Zinn® Chat screens a Support agent account may open.nonePro edition
zinn_chat_agent_script_srcFilterFilters the URL the standalone AI chat agent is loaded from.string $srcFree edition
zinn_chat_agent_ticketFilterFilters the ticket payload for wp-admin (Pro adds canned replies, SLA, KB suggestions).noneFree edition
zinn_chat_answerFilterFilters an assistant answer before it is shown (Pro adds its extras here).string $questionFree edition
zinn_chat_assistant_answeredActionThe assistant answered a visitor.int $id, string $textFree edition
zinn_chat_challengeFilterFilters the human check shown to visitors (script URL, site key, and the global object the script defines with a `render( element, { sitekey, callback } )` method).noneFree edition
zinn_chat_challenge_okFilterFilters whether the visitor passed the human check. A check that cannot be verified must return false (fail closed): a form that lets everything through whenever the service is unreachable is a form a bot can make succeed by timing.bool $ok, string $ip, string $whereFree edition
zinn_chat_client_ipFilterFilters the visitor IP address used for rate limits and records.string $ipFree edition
zinn_chat_console_configFilterFilters the extra configuration handed to the operator console's script. Zinn® Chat Pro adds its features here.noneFree edition
zinn_chat_conversation_startedActionA visitor started a chat.int $idFree edition
zinn_chat_conversation_statusActionA conversation changed status.int $id, string $status, string $oldFree edition
zinn_chat_customer_ticket_urlFilterFilters the link a customer is sent for their ticket.string $urlFree edition
zinn_chat_elementsFilterFilters the front-end elements offered as blocks and builder modules.noneFree edition
zinn_chat_emailFilterFilters an email before it is sent. Return an empty `to` to stop it.noneFree edition
zinn_chat_fs_loadedActionFires once the licensing SDK has loaded (in the main file, before any Zinn® Chat code). Hook here to talk to `zinn_chat_fs()`.noneFree edition
zinn_chat_index_extractFilterFilters an extracted object (or supplies one for a custom object type).string $type, int $idFree edition
zinn_chat_index_languageFilterFilters the language (locale) of an indexed post.string $language, \WP_Post $postFree edition
zinn_chat_index_objectEntry point (you fire it)Hooks.noneFree edition
zinn_chat_index_post_typesFilterFilters the post types the assistant reads.noneFree edition
zinn_chat_indexableFilterFilters whether a post is indexed.bool $indexable, \WP_Post $postFree edition
zinn_chat_indexedActionAn object was (re)indexed.string $type, int $idFree edition
zinn_chat_is_proFilterFilters whether the Pro features run (a bought licence or a trial, from Freemius). The Pro code ships only in the premium package, so this cannot add what the free one lacks.bool $proFree edition
zinn_chat_loadedActionZinn® Chat has loaded (the extension point for add-ons).noneFree edition
zinn_chat_message_addedActionA message was added to a conversation.int $id, int $conversation_id, string $roleFree edition
zinn_chat_order_trackingFilterFilters the tracking information given to the assistant for an order.\WC_Order $orderFree edition
zinn_chat_pro_alertActionAn alert-worthy event happened (push notifications listen here).string $alert, int $id, string $text, string $linkPro edition
zinn_chat_pro_assignedActionA ticket was assigned to an agent automatically.int $id, int $agentPro edition
zinn_chat_pro_loadedActionThe Pro layer has loaded.nonePro edition
zinn_chat_pro_priority_changedActionA ticket's priority changed (SLA targets follow it).int $idPro edition
zinn_chat_pro_sla_breachActionAn SLA target was missed.int $ticket_id, string $whichPro edition
zinn_chat_pro_ticket_ratedActionA customer rated a solved ticket (1-5).int $id, int $scorePro edition
zinn_chat_ratedActionFires after a visitor rates a conversation.int $conversation_id, int $ratingFree edition
zinn_chat_role_capabilitiesFilterFilters which roles receive which Zinn® Chat capabilities.noneFree edition
zinn_chat_save_settingsFilterFilters settings before they are stored (Pro adds its own keys here).noneFree edition
zinn_chat_script_srcFilterFilters the URL the hosted chat widget is loaded from (connected mode).string $srcFree edition
zinn_chat_settings_beforeActionOutput above a settings tab's form.string $tabFree edition
zinn_chat_settings_fieldsFilterFilters the fields of a settings tab (Pro adds its own).string $tabFree edition
zinn_chat_settings_tabsFilterFilters the settings tabs.noneFree edition
zinn_chat_setup_afterActionOutput under the setup checklist (the free edition shows the Pro card here).noneFree edition
zinn_chat_should_renderFilterFilters whether the chat renders on this request (Pro's page targeting hooks here).bool $renderFree edition
zinn_chat_site_factsFilterFilters the facts about the site given to the assistant with every question. Each is `title`, `url` (on this site) and `text` (plain text, at most 3,000 characters); at most four are used.string $languageFree edition
zinn_chat_site_stringsFilterFilters the owner texts offered for translation (Pro adds its proactive messages).noneFree edition
zinn_chat_system_promptFilterFilters the assistant's system prompt (Pro: persona and hand-off rules).string $rulesFree edition
zinn_chat_team_onlineFilterFilters whether a person can answer now (Pro adds business hours here).bool $onlineFree edition
zinn_chat_ticket_assignedActionAn agent assigned a ticket to an agent (2.14.0: the notification centre tells them).int $id, int $assignee, int $byFree edition
zinn_chat_ticket_createdActionA ticket was opened. Mailer sends the confirmation and the team alert from here.int $id, string $tokenFree edition
zinn_chat_ticket_form_extraFilterFilters extra markup at the end of a guest ticket form (Pro's human check goes here).string $htmlFree edition
zinn_chat_ticket_form_fieldsFilterFilters extra fields shown above the message on every ticket form (Pro: a department choice). Name them `zinn_chat_extra[<key>]`; they reach `zinn_chat_ticket_created` as `$fields['extra']`, unsanitised, for whoever added them to validate.string $htmlFree edition
zinn_chat_ticket_replyActionA reply was added to a ticket. Mailer emails the other side from here.int $id, int $ticket_id, string $authorFree edition
zinn_chat_ticket_statusActionA ticket changed status.int $id, string $status, string $oldFree edition
zinn_chat_uninstallActionZinn® Chat is being uninstalled (Pro removes its own data here).noneFree edition
zinn_chat_widget_configFilterFilters the launcher configuration printed on the page.noneFree edition
zinn_chat_widget_statusFilterFilters what the opened chat receives (Pro adds its own switches and words).noneFree edition