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.
Endpoints
MCP over HTTP (streamable)
https://example.com/wp-json/zinn-chat/v1/mcpMCP 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-chatREST: run an ability
/wp-json/wp-abilities/v1/abilities/<name>/runAuthentication 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.
| Ability | What it does | Edition | REST | Permission | Parameters |
|---|---|---|---|---|---|
zinn-chat/answer-ticketzinn-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 edition | POST …/abilities/zinn-chat/answer-ticket/run | the REST route's own per-item permission check | id: string (required) |
zinn-chat/ask-assistantzinn-chat-ask-assistant | Ask the assistant Asks the site's AI assistant a question and returns its answer with every source it found. | Free edition | POST …/abilities/zinn-chat/ask-assistant/run | the REST route's own per-item permission check | question: string (required), language: string |
zinn-chat/bulk-update-ticketszinn-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 edition | POST …/abilities/zinn-chat/bulk-update-tickets/run | zinn_chat_answer | ids: array (required), status: open|pending|solved|closed, priority: low|normal|high|urgent, assignee_id: integer |
zinn-chat/chat-to-ticketzinn-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 edition | POST …/abilities/zinn-chat/chat-to-ticket/run | the REST route's own per-item permission check | id: string (required) |
zinn-chat/close-chatzinn-chat-close-chat | Close a chat Ends a chat; the visitor can still ask for the transcript. | Free edition | POST …/abilities/zinn-chat/close-chat/run | the REST route's own per-item permission check | id: string (required) |
zinn-chat/create-ticketzinn-chat-create-ticket | Open a ticket Opens a ticket on a customer's behalf (their email, a subject and the first message). | Free edition | POST …/abilities/zinn-chat/create-ticket/run | the REST route's own per-item permission check | email: string (required), subject: string (required), body: string (required), name: string |
zinn-chat/delete-canned-replyzinn-chat-delete-canned-reply | Delete a saved reply (Pro) Deletes a saved reply. | Pro edition | POST …/abilities/zinn-chat/delete-canned-reply/run | the REST route's own per-item permission check | id: string (required) |
zinn-chat/delete-ticketzinn-chat-delete-ticket | Delete a ticket Deletes a ticket and its conversation for good (managers only). | Free edition | POST …/abilities/zinn-chat/delete-ticket/run | the REST route's own per-item permission check | id: string (required) |
zinn-chat/draft-kb-articlezinn-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 edition | POST …/abilities/zinn-chat/draft-kb-article/run | edit_posts (the REST route's own check) | ticket: integer (required) |
zinn-chat/draft-kb-from-gapszinn-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 edition | POST …/abilities/zinn-chat/draft-kb-from-gaps/run | edit_posts (the REST route's own check) | ids: array (required) |
zinn-chat/fill-canned-replyzinn-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 edition | POST …/abilities/zinn-chat/fill-canned-reply/run | the REST route's own per-item permission check | id: string (required) |
zinn-chat/get-chatzinn-chat-get-chat | Read a chat Returns one chat's messages and visitor details (after: only messages newer than this id). | Free edition | GET …/abilities/zinn-chat/get-chat/run | the REST route's own per-item permission check | id: string (required) |
zinn-chat/get-overviewzinn-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 edition | GET …/abilities/zinn-chat/get-overview/run | zinn_chat_answer | none |
zinn-chat/get-settingszinn-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 edition | GET …/abilities/zinn-chat/get-settings/run | zinn_chat_manage | none |
zinn-chat/get-statszinn-chat-get-stats | Read support statistics (Pro) Returns chat and ticket numbers, response times and ratings for the last N days (days). | Pro edition | GET …/abilities/zinn-chat/get-stats/run | the REST route's own per-item permission check | days: integer |
zinn-chat/get-ticketzinn-chat-get-ticket | Read a ticket Returns one ticket with its whole conversation, status, priority and assignee. | Free edition | GET …/abilities/zinn-chat/get-ticket/run | the REST route's own per-item permission check | id: string (required) |
zinn-chat/hand-chat-to-assistantzinn-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 edition | POST …/abilities/zinn-chat/hand-chat-to-assistant/run | the REST route's own per-item permission check | id: string (required) |
zinn-chat/list-canned-replieszinn-chat-list-canned-replies | List saved replies (Pro) Lists the saved replies agents can insert, with their shortcuts. | Pro edition | GET …/abilities/zinn-chat/list-canned-replies/run | the REST route's own per-item permission check | none |
zinn-chat/list-chatszinn-chat-list-chats | List live chats Lists the chats waiting, in progress and recently closed, with who is handling each. | Free edition | GET …/abilities/zinn-chat/list-chats/run | the REST route's own per-item permission check | view: active|bot|closed|all |
zinn-chat/list-indexed-contentzinn-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 edition | GET …/abilities/zinn-chat/list-indexed-content/run | the REST route's own per-item permission check | search: string, status: indexed|pending|error, page: integer |
zinn-chat/list-kb-gapszinn-chat-list-kb-gaps | List unanswered questions (Pro) Lists the questions visitors asked that the knowledge base could not answer. | Pro edition | GET …/abilities/zinn-chat/list-kb-gaps/run | the REST route's own per-item permission check | status: open|drafted|answered|ignored|all, page: integer |
zinn-chat/list-ticketszinn-chat-list-tickets | List tickets Lists support tickets, filtered by status or a search, a page at a time. | Free edition | GET …/abilities/zinn-chat/list-tickets/run | the REST route's own per-item permission check | status: active|open|pending|solved|closed|all, search: string, page: integer |
zinn-chat/reembed-contentzinn-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 edition | POST …/abilities/zinn-chat/reembed-content/run | the REST route's own per-item permission check | all: boolean, item_id: integer |
zinn-chat/reindex-contentzinn-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 edition | POST …/abilities/zinn-chat/reindex-content/run | the REST route's own per-item permission check | all: boolean, item_id: integer |
zinn-chat/reply-chatzinn-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 edition | POST …/abilities/zinn-chat/reply-chat/run | the REST route's own per-item permission check | id: string (required) |
zinn-chat/save-canned-replyzinn-chat-save-canned-reply | Save a saved reply (Pro) Creates or changes a saved reply (title, shortcut, body, department; id to change one). | Pro edition | POST …/abilities/zinn-chat/save-canned-reply/run | the REST route's own per-item permission check | id: integer, title: string (required), body: string (required), shortcut: string, department: string |
zinn-chat/save-kb-articlezinn-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 edition | POST …/abilities/zinn-chat/save-kb-article/run | edit_posts | id: integer, title: string, content: string, excerpt: string, categories: array, status: draft|publish |
zinn-chat/search-kbzinn-chat-search-kb | Search the knowledge base (Pro) Finds help articles to link in a reply (q: the search). | Pro edition | GET …/abilities/zinn-chat/search-kb/run | the REST route's own per-item permission check | q: string (required) |
zinn-chat/set-conversation-detailszinn-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 edition | POST …/abilities/zinn-chat/set-conversation-details/run | the REST route's own per-item permission check | kind: ticket|chat, id: integer (required), department: string, tags: array |
zinn-chat/set-kb-gap-statuszinn-chat-set-kb-gap-status | Mark unanswered questions (Pro) Marks unanswered questions as open, planned or dismissed (ids, status). | Pro edition | POST …/abilities/zinn-chat/set-kb-gap-status/run | the REST route's own per-item permission check | ids: array (required), status: open|drafted|answered|ignored (required) |
zinn-chat/set-presencezinn-chat-set-presence | Set your availability Marks the signed-in agent available or away for new chats (away: true or false). | Free edition | POST …/abilities/zinn-chat/set-presence/run | the REST route's own per-item permission check | away: boolean |
zinn-chat/suggest-replyzinn-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 edition | POST …/abilities/zinn-chat/suggest-reply/run | the REST route's own per-item permission check | kind: ticket|chat, id: integer (required) |
zinn-chat/summarise-conversationzinn-chat-summarise-conversation | Summarise a conversation with AI (Pro) Summarises a chat or ticket in a few lines. | Pro edition | POST …/abilities/zinn-chat/summarise-conversation/run | the REST route's own per-item permission check | kind: ticket|chat, id: integer (required) |
zinn-chat/take-chatzinn-chat-take-chat | Take a chat Assigns a waiting chat to the signed-in agent, so the visitor talks to a person. | Free edition | POST …/abilities/zinn-chat/take-chat/run | the REST route's own per-item permission check | id: string (required) |
zinn-chat/update-settingszinn-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 edition | POST …/abilities/zinn-chat/update-settings/run | zinn_chat_manage | settings: object (required) |
zinn-chat/update-ticketzinn-chat-update-ticket | Change a ticket Changes a ticket's status, priority or assignee. | Free edition | POST …/abilities/zinn-chat/update-ticket/run | the REST route's own per-item permission check | id: 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.
| Hook | Kind | What it does | Parameters | Edition |
|---|---|---|---|---|
zinn_chat_admin_pages | Filter | Filters the Zinn® Chat admin screens (Pro adds its own). | none | Free edition |
zinn_chat_agent_chat | Filter | Filters the chat payload for the agent console (Pro adds visitor details, notes, KB suggestions). | none | Free edition |
zinn_chat_agent_pages | Filter | Filters the Zinn® Chat screens a Support agent account may open. | none | Pro edition |
zinn_chat_agent_script_src | Filter | Filters the URL the standalone AI chat agent is loaded from. | string $src | Free edition |
zinn_chat_agent_ticket | Filter | Filters the ticket payload for wp-admin (Pro adds canned replies, SLA, KB suggestions). | none | Free edition |
zinn_chat_answer | Filter | Filters an assistant answer before it is shown (Pro adds its extras here). | string $question | Free edition |
zinn_chat_assistant_answered | Action | The assistant answered a visitor. | int $id, string $text | Free edition |
zinn_chat_challenge | Filter | Filters the human check shown to visitors (script URL, site key, and the global object the script defines with a `render( element, { sitekey, callback } )` method). | none | Free edition |
zinn_chat_challenge_ok | Filter | Filters 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 $where | Free edition |
zinn_chat_client_ip | Filter | Filters the visitor IP address used for rate limits and records. | string $ip | Free edition |
zinn_chat_console_config | Filter | Filters the extra configuration handed to the operator console's script. Zinn® Chat Pro adds its features here. | none | Free edition |
zinn_chat_conversation_started | Action | A visitor started a chat. | int $id | Free edition |
zinn_chat_conversation_status | Action | A conversation changed status. | int $id, string $status, string $old | Free edition |
zinn_chat_customer_ticket_url | Filter | Filters the link a customer is sent for their ticket. | string $url | Free edition |
zinn_chat_elements | Filter | Filters the front-end elements offered as blocks and builder modules. | none | Free edition |
zinn_chat_email | Filter | Filters an email before it is sent. Return an empty `to` to stop it. | none | Free edition |
zinn_chat_fs_loaded | Action | Fires once the licensing SDK has loaded (in the main file, before any Zinn® Chat code). Hook here to talk to `zinn_chat_fs()`. | none | Free edition |
zinn_chat_index_extract | Filter | Filters an extracted object (or supplies one for a custom object type). | string $type, int $id | Free edition |
zinn_chat_index_language | Filter | Filters the language (locale) of an indexed post. | string $language, \WP_Post $post | Free edition |
zinn_chat_index_object | Entry point (you fire it) | Hooks. | none | Free edition |
zinn_chat_index_post_types | Filter | Filters the post types the assistant reads. | none | Free edition |
zinn_chat_indexable | Filter | Filters whether a post is indexed. | bool $indexable, \WP_Post $post | Free edition |
zinn_chat_indexed | Action | An object was (re)indexed. | string $type, int $id | Free edition |
zinn_chat_is_pro | Filter | Filters 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 $pro | Free edition |
zinn_chat_loaded | Action | Zinn® Chat has loaded (the extension point for add-ons). | none | Free edition |
zinn_chat_message_added | Action | A message was added to a conversation. | int $id, int $conversation_id, string $role | Free edition |
zinn_chat_order_tracking | Filter | Filters the tracking information given to the assistant for an order. | \WC_Order $order | Free edition |
zinn_chat_pro_alert | Action | An alert-worthy event happened (push notifications listen here). | string $alert, int $id, string $text, string $link | Pro edition |
zinn_chat_pro_assigned | Action | A ticket was assigned to an agent automatically. | int $id, int $agent | Pro edition |
zinn_chat_pro_loaded | Action | The Pro layer has loaded. | none | Pro edition |
zinn_chat_pro_priority_changed | Action | A ticket's priority changed (SLA targets follow it). | int $id | Pro edition |
zinn_chat_pro_sla_breach | Action | An SLA target was missed. | int $ticket_id, string $which | Pro edition |
zinn_chat_pro_ticket_rated | Action | A customer rated a solved ticket (1-5). | int $id, int $score | Pro edition |
zinn_chat_rated | Action | Fires after a visitor rates a conversation. | int $conversation_id, int $rating | Free edition |
zinn_chat_role_capabilities | Filter | Filters which roles receive which Zinn® Chat capabilities. | none | Free edition |
zinn_chat_save_settings | Filter | Filters settings before they are stored (Pro adds its own keys here). | none | Free edition |
zinn_chat_script_src | Filter | Filters the URL the hosted chat widget is loaded from (connected mode). | string $src | Free edition |
zinn_chat_settings_before | Action | Output above a settings tab's form. | string $tab | Free edition |
zinn_chat_settings_fields | Filter | Filters the fields of a settings tab (Pro adds its own). | string $tab | Free edition |
zinn_chat_settings_tabs | Filter | Filters the settings tabs. | none | Free edition |
zinn_chat_setup_after | Action | Output under the setup checklist (the free edition shows the Pro card here). | none | Free edition |
zinn_chat_should_render | Filter | Filters whether the chat renders on this request (Pro's page targeting hooks here). | bool $render | Free edition |
zinn_chat_site_facts | Filter | Filters 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 $language | Free edition |
zinn_chat_site_strings | Filter | Filters the owner texts offered for translation (Pro adds its proactive messages). | none | Free edition |
zinn_chat_system_prompt | Filter | Filters the assistant's system prompt (Pro: persona and hand-off rules). | string $rules | Free edition |
zinn_chat_team_online | Filter | Filters whether a person can answer now (Pro adds business hours here). | bool $online | Free edition |
zinn_chat_ticket_assigned | Action | An agent assigned a ticket to an agent (2.14.0: the notification centre tells them). | int $id, int $assignee, int $by | Free edition |
zinn_chat_ticket_created | Action | A ticket was opened. Mailer sends the confirmation and the team alert from here. | int $id, string $token | Free edition |
zinn_chat_ticket_form_extra | Filter | Filters extra markup at the end of a guest ticket form (Pro's human check goes here). | string $html | Free edition |
zinn_chat_ticket_form_fields | Filter | Filters 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 $html | Free edition |
zinn_chat_ticket_reply | Action | A reply was added to a ticket. Mailer emails the other side from here. | int $id, int $ticket_id, string $author | Free edition |
zinn_chat_ticket_status | Action | A ticket changed status. | int $id, string $status, string $old | Free edition |
zinn_chat_uninstall | Action | Zinn® Chat is being uninstalled (Pro removes its own data here). | none | Free edition |
zinn_chat_widget_config | Filter | Filters the launcher configuration printed on the page. | none | Free edition |
zinn_chat_widget_status | Filter | Filters what the opened chat receives (Pro adds its own switches and words). | none | Free edition |