happyfox_add_private_note

Add an internal note (never sent to the contact), optionally alerting agents and changing status, priority, assignee, due date or tags. HappyFox: POST /api/1.1/json/ticket/<ticket_number>/staff_pvtnote/.

destructive

Argument	Type	Description
html	string	Note in HTML.
tags	string	Tags to set, as a comma-separated string.
alert	string	Send a private alert: `s` = all subscribers, `c` = all agents in the ticket's category, or an agent id.
staff*	integer	The agent adding the note (happyfox_list_staff) id.
status	integer	New status id (happyfox_list_statuses).
assignee	any	Agent id to assign the ticket to (from happyfox_list_staff); null to unassign.
due_date	string	Due date, yyyy-mm-dd or dd/mm/yyyy.
priority	integer	New priority id (happyfox_list_priorities).
plaintext	string	Note in plain text.
time_spent	integer	Minutes to add to the ticket's time spent (some categories require it).
custom_fields	object	Custom field values keyed "t-cf-<id>". Ticket fields (ids from happyfox_list_ticket_custom_fields); compulsory-on-completion fields are required when closing. Values: text = string, number = number, dropdown = choice id, multiple choice = array of choice ids, date = yyyy-mm-dd.
ticket_number*	integer	The ticket NUMBER (the `id` field, e.g. 3 for #DC00000003) — not the prefixed display id.

Input schema (JSON)

{
  "type": "object",
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "required": [
    "ticket_number",
    "staff"
  ],
  "properties": {
    "html": {
      "type": "string",
      "description": "Note in HTML."
    },
    "tags": {
      "type": "string",
      "description": "Tags to set, as a comma-separated string."
    },
    "alert": {
      "type": "string",
      "pattern": "^(s|c|\\d+)$",
      "description": "Send a private alert: `s` = all subscribers, `c` = all agents in the ticket's category, or an agent id."
    },
    "staff": {
      "type": "integer",
      "maximum": 9007199254740991,
      "minimum": 1,
      "description": "The agent adding the note (happyfox_list_staff) id."
    },
    "status": {
      "type": "integer",
      "maximum": 9007199254740991,
      "minimum": 1,
      "description": "New status id (happyfox_list_statuses)."
    },
    "assignee": {
      "anyOf": [
        {
          "type": "integer",
          "maximum": 9007199254740991,
          "minimum": 1
        },
        {
          "type": "null"
        }
      ],
      "description": "Agent id to assign the ticket to (from happyfox_list_staff); null to unassign."
    },
    "due_date": {
      "type": "string",
      "pattern": "^(\\d{4}-\\d{2}-\\d{2}|\\d{2}\\/\\d{2}\\/\\d{4})$",
      "description": "Due date, yyyy-mm-dd or dd/mm/yyyy."
    },
    "priority": {
      "type": "integer",
      "maximum": 9007199254740991,
      "minimum": 1,
      "description": "New priority id (happyfox_list_priorities)."
    },
    "plaintext": {
      "type": "string",
      "description": "Note in plain text."
    },
    "time_spent": {
      "type": "integer",
      "maximum": 9007199254740991,
      "minimum": 0,
      "description": "Minutes to add to the ticket's time spent (some categories require it)."
    },
    "custom_fields": {
      "type": "object",
      "description": "Custom field values keyed \"t-cf-<id>\". Ticket fields (ids from happyfox_list_ticket_custom_fields); compulsory-on-completion fields are required when closing. Values: text = string, number = number, dropdown = choice id, multiple choice = array of choice ids, date = yyyy-mm-dd.",
      "propertyNames": {
        "type": "string",
        "pattern": "^(t\\-cf\\-)\\d+$"
      },
      "additionalProperties": {
        "anyOf": [
          {
            "type": "string"
          },
          {
            "type": "number"
          },
          {
            "type": "array",
            "items": {
              "type": "integer",
              "maximum": 9007199254740991,
              "minimum": -9007199254740991
            }
          }
        ]
      }
    },
    "ticket_number": {
      "type": "integer",
      "maximum": 9007199254740991,
      "minimum": 1,
      "description": "The ticket NUMBER (the `id` field, e.g. 3 for #DC00000003) — not the prefixed display id."
    }
  }
}

happyfox_add_staff_reply

Add an agent reply to a ticket and/or change its status, priority, assignee, due date or tags. The contact is emailed ONLY if update_customer is true (HappyFox default: false). With no message it just updates properties. Moving to a completed status may require the category's compulsory custom fields. HappyFox: POST /api/1.1/json/ticket/<ticket_number>/staff_update/.

destructive

Argument	Type	Description
cc	string	CC email addresses, as a comma-separated string.
bcc	string	BCC email addresses, as a comma-separated string.
html	string	Reply in HTML.
tags	string	Tags to set, as a comma-separated string.
staff*	integer	The agent making the reply (happyfox_list_staff) id.
status	integer	New status id (happyfox_list_statuses).
subject	string	Override the subject of the email sent to the contact.
assignee	any	Agent id to assign the ticket to (from happyfox_list_staff); null to unassign.

happyfox_create_contact

Create a contact. HappyFox treats this as create-or-edit keyed on email: if the email already exists that contact is updated, and any contact custom field NOT passed is reset — use happyfox_update_contact to edit an existing contact. HappyFox: POST /api/1.1/json/users/.

destructive

Argument	Type	Description
name*	string	Contact name.
email*	string	Contact email address.
phones	array	Phone numbers.
custom_fields	object	Custom field values keyed "c-cf-<id>". Contact fields (happyfox_list_contact_custom_fields); required ones must be present. Values: text = string, number = number, dropdown = choice id, multiple choice = array of choice ids, date = yyyy-mm-dd.

Input schema (JSON)

{
  "type": "object",
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "required": [
    "name",
    "email"
  ],
  "properties": {
    "name": {
      "type": "string",
      "minLength": 1,
      "description": "Contact name."
    },
    "email": {
      "type": "string",
      "format": "email",
      "pattern": "^(?:[A-Za-z0-9_'+\\-]+\\.)*[A-Za-z0-9_'+\\-]*[A-Za-z0-9_+-]@(?:[A-Za-z0-9][A-Za-z0-9\\-]*\\.)+[A-Za-z]{2,}$",
      "description": "Contact email address."
    },
    "phones": {
      "type": "array",
      "items": {
        "type": "object",
        "required": [
          "number"
        ],
        "properties": {
          "id": {
            "type": "integer",
            "maximum": 9007199254740991,
            "minimum": -9007199254740991,
            "description": "Existing phone id, to edit that number instead of adding one."
          },
          "type": {
            "enum": [
              "mo",
              "w",
              "m",
              "h",
              "o"
            ],
            "type": "string",
            "description": "mo = mobile, w = work, m = main, h = home, o = other (default)."
          },
          "number": {
            "type": "string",
            "minLength": 1,
            "description": "The phone number."
          },
          "is_primary": {
            "type": "boolean",
            "description": "Make this the primary number."
          }
        }
      },
      "description": "Phone numbers."
    },
    "custom_fields": {
      "type": "object",
      "description": "Custom field values keyed \"c-cf-<id>\". Contact fields (happyfox_list_contact_custom_fields); required ones must be present. Values: text = string, number = number, dropdown = choice id, multiple choice = array of choice ids, date = yyyy-mm-dd.",
      "propertyNames": {
        "type": "string",
        "pattern": "^(c\\-cf\\-)\\d+$"
      },
      "additionalProperties": {
        "anyOf": [
          {
            "type": "string"
          },
          {
            "type": "number"
          },
          {
            "type": "array",
            "items": {
              "type": "integer",
              "maximum": 9007199254740991,
              "minimum": -9007199254740991
            }
          }
        ]
      }
    }
  }
}

happyfox_create_ticket

Open a new ticket on behalf of a contact (created if the email is new). Needs a category id (a public category), a subject and a message in `text` or `html`. HappyFox: POST /api/1.1/json/tickets/.

destructive

Argument	Type	Description
cc	string	CC email addresses, as a comma-separated string.
bcc	string	BCC email addresses, as a comma-separated string.
html	string	Message in HTML (text or html is required).
name*	string	Contact name.
tags	string	Tags, as a comma-separated string.
text	string	Message in plain text (text or html is required).
email*	string	Contact email address.
phone	string	Contact phone number.
subject*	string	Ticket subject.

happyfox_get_contact

Fetch a contact by id or by email address — phones, contact groups, ticket counts and custom fields. HappyFox: GET /api/1.1/json/user/<id or email>/.

read-only

Argument	Type	Description
contact*	string	The contact's numeric id (e.g. "33") or email address.

Input schema (JSON)

{
  "type": "object",
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "required": [
    "contact"
  ],
  "properties": {
    "contact": {
      "type": "string",
      "minLength": 1,
      "description": "The contact's numeric id (e.g. \"33\") or email address."
    }
  }
}

happyfox_get_contact_group

Fetch a contact group and its member contacts. HappyFox: GET /api/1.1/json/contact_group/<id>/.

read-only

Argument	Type	Description
contact_group_id*	integer	The contact group id.

Input schema (JSON)

{
  "type": "object",
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "required": [
    "contact_group_id"
  ],
  "properties": {
    "contact_group_id": {
      "type": "integer",
      "maximum": 9007199254740991,
      "minimum": 1,
      "description": "The contact group id."
    }
  }
}

happyfox_get_report_summary

Summary counts for a saved report: ticket, completed, assigned, pending and unassigned counts. HappyFox: GET /api/1.1/json/report/<id>/.

read-only

Argument	Type	Description
report_id*	integer	The report (from happyfox_list_reports) id.

Input schema (JSON)

{
  "type": "object",
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "required": [
    "report_id"
  ],
  "properties": {
    "report_id": {
      "type": "integer",
      "maximum": 9007199254740991,
      "minimum": 1,
      "description": "The report (from happyfox_list_reports) id."
    }
  }
}

happyfox_get_report_tabular_data

The tabular view of a saved report — one row per ticket (display_id, subject, status, assignee, due date), paginated. HappyFox: GET /api/1.1/json/report/<id>/tabulardata/.

read-only

Argument	Type	Description
page	integer	Page number, starting at 1.
size	integer	Results per page, 1-50 (HappyFox default 10).
report_id*	integer	The report (from happyfox_list_reports) id.

Input schema (JSON)

{
  "type": "object",
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "required": [
    "report_id"
  ],
  "properties": {
    "page": {
      "type": "integer",
      "maximum": 9007199254740991,
      "minimum": 1,
      "description": "Page number, starting at 1."
    },
    "size": {
      "type": "integer",
      "maximum": 50,
      "minimum": 1,
      "description": "Results per page, 1-50 (HappyFox default 10)."
    },
    "report_id": {
      "type": "integer",
      "maximum": 9007199254740991,
      "minimum": 1,
      "description": "The report (from happyfox_list_reports) id."
    }
  }
}

happyfox_get_ticket

Fetch a ticket with its full conversation: status, priority, category, contact, assignee, custom fields, SLA breaches and every update (messages, private notes, property changes, attachment links that expire in 5 minutes). HappyFox: GET /api/1.1/json/ticket/<ticket_number>/.

read-only

Argument	Type	Description
ticket_number*	integer	The ticket NUMBER (the `id` field, e.g. 3 for #DC00000003) — not the prefixed display id.
show_cf_changes	boolean	Include the history of custom-field changes in the updates.

Input schema (JSON)

{
  "type": "object",
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "required": [
    "ticket_number"
  ],
  "properties": {
    "ticket_number": {
      "type": "integer",
      "maximum": 9007199254740991,
      "minimum": 1,
      "description": "The ticket NUMBER (the `id` field, e.g. 3 for #DC00000003) — not the prefixed display id."
    },
    "show_cf_changes": {
      "type": "boolean",
      "description": "Include the history of custom-field changes in the updates."
    }
  }
}

happyfox_list_categories

List ticket categories (queues) with their ids — needed to create a ticket or filter tickets. HappyFox: GET /api/1.1/json/categories/.

read-only

No arguments.

Input schema (JSON)

{
  "type": "object",
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "properties": {}
}

happyfox_list_contact_custom_fields

List contact custom fields: id, type, choices and required flag. Use the ids as c-cf-<id>. HappyFox: GET /api/1.1/json/user_custom_fields/.

read-only

No arguments.

Input schema (JSON)

{
  "type": "object",
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "properties": {}
}

happyfox_list_contact_groups

List contact groups (typically customer companies) with their tagged email domains. HappyFox: GET /api/1.1/json/contact_groups/.

read-only

No arguments.

Input schema (JSON)

{
  "type": "object",
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "properties": {}
}

happyfox_list_contacts

List contacts (customers), paginated, or search them. Search `q` fields: name, email, phone (digits only, no +), updated_since, created_since — e.g. `name:adam email:[email protected]` (space-separated, all must match). HappyFox: GET /api/1.1/json/users/.

read-only

Argument	Type	Description
q	string	Search string, `field:value` pairs separated by spaces.
page	integer	Page number, starting at 1.
size	integer	Results per page, 1-50 (HappyFox default 10).

Input schema (JSON)

{
  "type": "object",
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "properties": {
    "q": {
      "type": "string",
      "description": "Search string, `field:value` pairs separated by spaces."
    },
    "page": {
      "type": "integer",
      "maximum": 9007199254740991,
      "minimum": 1,
      "description": "Page number, starting at 1."
    },
    "size": {
      "type": "integer",
      "maximum": 50,
      "minimum": 1,
      "description": "Results per page, 1-50 (HappyFox default 10)."
    }
  }
}

happyfox_list_kb_articles

Export the knowledge base: external (customer-facing) articles by default, or internal (agent-only) articles. HappyFox: GET /api/1.1/json/kb/articles/ or /kb/internal-articles/.

read-only

Argument	Type	Description
internal	boolean	true = internal articles; false/omitted = external articles.

Input schema (JSON)

{
  "type": "object",
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "properties": {
    "internal": {
      "type": "boolean",
      "description": "true = internal articles; false/omitted = external articles."
    }
  }
}

happyfox_list_priorities

List ticket priorities with ids — ids used to set a ticket's priority. HappyFox: GET /api/1.1/json/priorities/.

read-only

No arguments.

Input schema (JSON)

{
  "type": "object",
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "properties": {}
}

happyfox_list_reports

List the saved reports (id, name, description) from the Reports module. HappyFox: GET /api/1.1/json/reports/.

read-only

No arguments.

Input schema (JSON)

{
  "type": "object",
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "properties": {}
}

happyfox_list_staff

List agents (staff) with their ids, roles, categories and active flag — the `staff` id every reply/note needs, and assignee ids. HappyFox: GET /api/1.1/json/staff/.

read-only

No arguments.

Input schema (JSON)

{
  "type": "object",
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "properties": {}
}

happyfox_list_statuses

List ticket statuses with ids and behaviour (pending / completed) — ids used to change a ticket's status. HappyFox: GET /api/1.1/json/statuses/.

read-only

No arguments.

Input schema (JSON)

{
  "type": "object",
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "properties": {}
}

happyfox_list_ticket_custom_fields

List ticket custom fields: id, type, choices (with choice ids), required flags and categories. Use the ids as t-cf-<id>. HappyFox: GET /api/1.1/json/ticket_custom_fields/.

read-only

No arguments.

Input schema (JSON)

{
  "type": "object",
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "properties": {}
}

happyfox_list_tickets

List tickets, newest activity first, with optional filters and HappyFox's search syntax. Paginated (page_info + data). Search `q` examples: `status:"New","In Progress"`, `priority:"High"`, `assignee:none`, `tag:"billing"`, `contact:"[email protected]"`, `unresponded:true`, `breached:true`, `duedate:overdue`, `created-after:"2026/01/31"`, `last-modified-on-or-after:"2026/09/01"`, `"Custom Field":"value"`. Separate several filters with a space. HappyFox: GET /api/1.1/json/tickets/.

read-only

Argument	Type	Description
q	string	HappyFox search/filter string (see description).
page	integer	Page number, starting at 1.
size	integer	Results per page, 1-50 (HappyFox default 10).
sort	string	Sort key, e.g. created (newest first), createa, updated, due, priorityd.
fields	string	Comma-separated top-level fields to return, e.g. id,display_id,subject,status — keeps responses small.
status	string	`_all` (default), `_pending` (every pending-behaviour status), or a status id from happyfox_list_statuses.
category	integer	Only tickets in this category id (happyfox_list_categories).

happyfox_update_contact

Edit an existing contact's name, email or contact custom fields (c-cf-<id>). Phone numbers are edited via happyfox_create_contact with the phone id. HappyFox: POST /api/1.1/json/user/<id>/.

destructive

Argument	Type	Description
name	string	New name.
email	string	New email address.
contact_id*	integer	The contact id.
custom_fields	object	Custom field values keyed "c-cf-<id>". Contact fields. Values: text = string, number = number, dropdown = choice id, multiple choice = array of choice ids, date = yyyy-mm-dd.

Input schema (JSON)

{
  "type": "object",
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "required": [
    "contact_id"
  ],
  "properties": {
    "name": {
      "type": "string",
      "minLength": 1,
      "description": "New name."
    },
    "email": {
      "type": "string",
      "format": "email",
      "pattern": "^(?:[A-Za-z0-9_'+\\-]+\\.)*[A-Za-z0-9_'+\\-]*[A-Za-z0-9_+-]@(?:[A-Za-z0-9][A-Za-z0-9\\-]*\\.)+[A-Za-z]{2,}$",
      "description": "New email address."
    },
    "contact_id": {
      "type": "integer",
      "maximum": 9007199254740991,
      "minimum": 1,
      "description": "The contact id."
    },
    "custom_fields": {
      "type": "object",
      "description": "Custom field values keyed \"c-cf-<id>\". Contact fields. Values: text = string, number = number, dropdown = choice id, multiple choice = array of choice ids, date = yyyy-mm-dd.",
      "propertyNames": {
        "type": "string",
        "pattern": "^(c\\-cf\\-)\\d+$"
      },
      "additionalProperties": {
        "anyOf": [
          {
            "type": "string"
          },
          {
            "type": "number"
          },
          {
            "type": "array",
            "items": {
              "type": "integer",
              "maximum": 9007199254740991,
              "minimum": -9007199254740991
            }
          }
        ]
      }
    }
  }
}

happyfox_update_ticket_custom_fields

Set ticket custom-field values (t-cf-<id>, ids from happyfox_list_ticket_custom_fields). HappyFox: POST /api/1.1/json/ticket/<ticket_number>/update_custom_fields/.

destructive

Argument	Type	Description
staff*	integer	The agent making the change id.
custom_fields*	object	Custom field values keyed "t-cf-<id>". Ticket fields only. Values: text = string, number = number, dropdown = choice id, multiple choice = array of choice ids, date = yyyy-mm-dd.
ticket_number*	integer	The ticket NUMBER (the `id` field, e.g. 3 for #DC00000003) — not the prefixed display id.

Input schema (JSON)

{
  "type": "object",
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "required": [
    "ticket_number",
    "staff",
    "custom_fields"
  ],
  "properties": {
    "staff": {
      "type": "integer",
      "maximum": 9007199254740991,
      "minimum": 1,
      "description": "The agent making the change id."
    },
    "custom_fields": {
      "type": "object",
      "description": "Custom field values keyed \"t-cf-<id>\". Ticket fields only. Values: text = string, number = number, dropdown = choice id, multiple choice = array of choice ids, date = yyyy-mm-dd.",
      "propertyNames": {
        "type": "string",
        "pattern": "^(t\\-cf\\-)\\d+$"
      },
      "additionalProperties": {
        "anyOf": [
          {
            "type": "string"
          },
          {
            "type": "number"
          },
          {
            "type": "array",
            "items": {
              "type": "integer",
              "maximum": 9007199254740991,
              "minimum": -9007199254740991
            }
          }
        ]
      }
    },
    "ticket_number": {
      "type": "integer",
      "maximum": 9007199254740991,
      "minimum": 1,
      "description": "The ticket NUMBER (the `id` field, e.g. 3 for #DC00000003) — not the prefixed display id."
    }
  }
}

happyfox_update_ticket_tags

Add and/or remove tags on a ticket without touching anything else. HappyFox: POST /api/1.1/json/ticket/<ticket_number>/update_tags/.

destructive

Argument	Type	Description
add	string	Tags to add, as a comma-separated string.
remove	string	Tags to remove, as a comma-separated string.
staff_id*	integer	The agent making the change (shown in the ticket history) id.
ticket_number*	integer	The ticket NUMBER (the `id` field, e.g. 3 for #DC00000003) — not the prefixed display id.

Input schema (JSON)

{
  "type": "object",
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "required": [
    "ticket_number",
    "staff_id"
  ],
  "properties": {
    "add": {
      "type": "string",
      "description": "Tags to add, as a comma-separated string."
    },
    "remove": {
      "type": "string",
      "description": "Tags to remove, as a comma-separated string."
    },
    "staff_id": {
      "type": "integer",
      "maximum": 9007199254740991,
      "minimum": 1,
      "description": "The agent making the change (shown in the ticket history) id."
    },
    "ticket_number": {
      "type": "integer",
      "maximum": 9007199254740991,
      "minimum": 1,
      "description": "The ticket NUMBER (the `id` field, e.g. 3 for #DC00000003) — not the prefixed display id."
    }
  }
}

HappyFox MCP by usefulapi

Try it

happyfox_add_private_note Destructive

HappyFox MCP by usefulapi

Try it

happyfox_add_private_note Destructive

Tools (23)