Vision Helpdesk MCP by usefulapi

The ticket counts of the staff dashboard (quick view): for example new, open, overdue and assigned tickets. ticket / quick_view.

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

List tickets, with at most ONE filter: a ticket id, a status id, a department id or a folder (inbox, new, overdue, assigned, trash, spam, draft). Without a filter it lists the tickets the API user can see. Status ids come from vision_list_statuses. ticket / get_tickets.

{
  "type": "object",
  "properties": {
    "ticket_id": {
      "description": "Only this ticket.",
      "type": "integer",
      "exclusiveMinimum": 0,
      "maximum": 9007199254740991
    },
    "status_id": {
      "description": "Only tickets with this status id (vision_list_statuses).",
      "type": "integer",
      "exclusiveMinimum": 0,
      "maximum": 9007199254740991
    },
    "department_id": {
      "description": "Only tickets of this department id.",
      "type": "integer",
      "exclusiveMinimum": 0,
      "maximum": 9007199254740991
    },
    "folder": {
      "description": "A ticket folder.",
      "type": "string",
      "enum": [
        "inbox",
        "new",
        "overdue",
        "assigned",
        "trash",
        "spam",
        "draft"
      ]
    },
    "include_count": {
      "description": "Also ask for the total count.",
      "type": "boolean"
    },
    "offset": {
      "description": "How many results to skip (default 0), for the next page.",
      "type": "integer",
      "minimum": 0,
      "maximum": 1000000
    },
    "limit": {
      "description": "How many results to return, 1-100 (default 25).",
      "type": "integer",
      "minimum": 1,
      "maximum": 100
    }
  },
  "$schema": "https://json-schema.org/draft/2020-12/schema"
}

Find tickets by an EXACT ticket reference (the ticket hash such as VHD-218) or an EXACT subject. Give one of them. ticket / get_tickets with a filter on ticket_hash or subject.

{
  "type": "object",
  "properties": {
    "ticket_hash": {
      "description": "The ticket reference, for example VHD-218.",
      "type": "string",
      "pattern": "^[A-Za-z0-9_-]{1,40}$"
    },
    "subject": {
      "description": "The exact ticket subject.",
      "type": "string",
      "minLength": 1,
      "maxLength": 200
    },
    "offset": {
      "description": "How many results to skip (default 0), for the next page.",
      "type": "integer",
      "minimum": 0,
      "maximum": 1000000
    },
    "limit": {
      "description": "How many results to return, 1-100 (default 25).",
      "type": "integer",
      "minimum": 1,
      "maximum": 100
    }
  },
  "$schema": "https://json-schema.org/draft/2020-12/schema"
}

One ticket with its fields (status, owner, priority, department...) and its posts (the conversation). ticket / ticket_details.

{
  "type": "object",
  "properties": {
    "ticket_id": {
      "type": "integer",
      "exclusiveMinimum": 0,
      "maximum": 9007199254740991,
      "description": "Ticket id (the number, not the reference)."
    }
  },
  "required": [
    "ticket_id"
  ],
  "$schema": "https://json-schema.org/draft/2020-12/schema"
}

Tickets that carry a tag, by tag id. ticket / tag_search.

{
  "type": "object",
  "properties": {
    "tag_id": {
      "type": "integer",
      "exclusiveMinimum": 0,
      "maximum": 9007199254740991,
      "description": "Tag id."
    }
  },
  "required": [
    "tag_id"
  ],
  "$schema": "https://json-schema.org/draft/2020-12/schema"
}

Tickets that carry a label, by label id. ticket / search_label_tickets.

{
  "type": "object",
  "properties": {
    "label_id": {
      "type": "integer",
      "exclusiveMinimum": 0,
      "maximum": 9007199254740991,
      "description": "Label id."
    }
  },
  "required": [
    "label_id"
  ],
  "$schema": "https://json-schema.org/draft/2020-12/schema"
}

The ticket statuses of a department (ids and names), for filters and status changes. ticket / get_status.

{
  "type": "object",
  "properties": {
    "department_id": {
      "type": "integer",
      "exclusiveMinimum": 0,
      "maximum": 9007199254740991,
      "description": "Department id (statuses are per department)."
    }
  },
  "required": [
    "department_id"
  ],
  "$schema": "https://json-schema.org/draft/2020-12/schema"
}

The ticket priorities of a department (ids and names). ticket / get_priority.

{
  "type": "object",
  "properties": {
    "department_id": {
      "type": "integer",
      "exclusiveMinimum": 0,
      "maximum": 9007199254740991,
      "description": "Department id."
    }
  },
  "required": [
    "department_id"
  ],
  "$schema": "https://json-schema.org/draft/2020-12/schema"
}

The ticket types of a department (ids and names). ticket / get_ticket_type.

{
  "type": "object",
  "properties": {
    "department_id": {
      "type": "integer",
      "exclusiveMinimum": 0,
      "maximum": 9007199254740991,
      "description": "Department id."
    }
  },
  "required": [
    "department_id"
  ],
  "$schema": "https://json-schema.org/draft/2020-12/schema"
}

List clients (customers), with at most ONE filter: a client id, a first name (exact), or a parent client id (lists that client's contacts). client / get_clients.

{
  "type": "object",
  "properties": {
    "client_id": {
      "description": "Only this client.",
      "type": "integer",
      "exclusiveMinimum": 0,
      "maximum": 9007199254740991
    },
    "first_name": {
      "description": "Clients with exactly this first name.",
      "type": "string",
      "minLength": 1,
      "maxLength": 200
    },
    "parent_id": {
      "description": "The contacts of this client.",
      "type": "integer",
      "exclusiveMinimum": 0,
      "maximum": 9007199254740991
    },
    "include_count": {
      "description": "Also ask for the total count.",
      "type": "boolean"
    },
    "offset": {
      "description": "How many results to skip (default 0), for the next page.",
      "type": "integer",
      "minimum": 0,
      "maximum": 1000000
    },
    "limit": {
      "description": "How many clients to return, 1-200 (default 50). The helpdesk returns the whole list; it is cut here.",
      "type": "integer",
      "minimum": 1,
      "maximum": 200
    }
  },
  "$schema": "https://json-schema.org/draft/2020-12/schema"
}

Search clients by name or email text. client / list_clients.

{
  "type": "object",
  "properties": {
    "text": {
      "type": "string",
      "minLength": 1,
      "maxLength": 200,
      "description": "Part of a client name or email address."
    },
    "offset": {
      "description": "How many results to skip (default 0), for the next page.",
      "type": "integer",
      "minimum": 0,
      "maximum": 1000000
    },
    "limit": {
      "description": "How many clients to return, 1-200 (default 50).",
      "type": "integer",
      "minimum": 1,
      "maximum": 200
    }
  },
  "required": [
    "text"
  ],
  "$schema": "https://json-schema.org/draft/2020-12/schema"
}

A client's summary: notes and ticket counts. client / get_summary.

{
  "type": "object",
  "properties": {
    "client_id": {
      "type": "integer",
      "exclusiveMinimum": 0,
      "maximum": 9007199254740991,
      "description": "Client id."
    }
  },
  "required": [
    "client_id"
  ],
  "$schema": "https://json-schema.org/draft/2020-12/schema"
}

WRITE: confirm:true required. open a new ticket for a client, given by client id or email. By default no email and no autoresponder is sent; a normal ticket's first post is created on behalf of the client and shown to the client. Internal tickets are staff-only and cannot have client recipients or email enabled. Look up the department, status, priority and type ids first (vision_list_statuses, vision_list_priorities, vision_list_ticket_types). ticket / open_new_ticket.

{
  "type": "object",
  "properties": {
    "confirm": {
      "type": "boolean",
      "const": true,
      "description": "Required: confirm the exact change and any client-visible or email effects before setting true."
    },
    "domain_id": {
      "type": "integer",
      "exclusiveMinimum": 0,
      "maximum": 9007199254740991,
      "description": "Domain id the ticket is opened under (1 on a single-domain helpdesk)."
    },
    "department_id": {
      "type": "integer",
      "exclusiveMinimum": 0,
      "maximum": 9007199254740991,
      "description": "Department id."
    },
    "status_id": {
      "type": "integer",
      "exclusiveMinimum": 0,
      "maximum": 9007199254740991,
      "description": "Status id."
    },
    "priority_id": {
      "type": "integer",
      "exclusiveMinimum": 0,
      "maximum": 9007199254740991,
      "description": "Priority id."
    },
    "type_id": {
      "type": "integer",
      "exclusiveMinimum": 0,
      "maximum": 9007199254740991,
      "description": "Ticket type id."
    },
    "subject": {
      "type": "string",
      "minLength": 1,
      "maxLength": 250,
      "description": "Ticket subject."
    },
    "message": {
      "type": "string",
      "minLength": 1,
      "maxLength": 50000,
      "description": "The first post (HTML allowed)."
    },
    "from": {
      "type": "string",
      "minLength": 1,
      "maxLength": 200,
      "pattern": "^[^\\r\\n]+$",
      "description": "The from address shown on the post, for example [email protected]."
    },
    "client_id": {
      "description": "The client the ticket is for. Give this or client_email (not needed for an internal ticket).",
      "type": "integer",
      "exclusiveMinimum": 0,
      "maximum": 9007199254740991
    },
    "client_email": {
      "description": "A valid client email address. Give this or client_id.",
      "type": "string",
      "maxLength": 254,
      "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,}$"
    },
    "cc": {
      "description": "CC email addresses.",
      "type": "string",
      "maxLength": 500
    },
    "owner_ids": {
      "description": "Staff ids that own the ticket.",
      "maxItems": 20,
      "type": "array",
      "items": {
        "type": "integer",
        "exclusiveMinimum": 0,
        "maximum": 9007199254740991
      }
    },
    "send_autoresponder": {
      "description": "Send the autoresponder email to the client (default false).",
      "type": "boolean"
    },
    "send_email": {
      "description": "Send the post by email to the client (default false).",
      "type": "boolean"
    },
    "visible_to_client": {
      "description": "Show the first post to the client (default true).",
      "type": "boolean"
    },
    "as_client": {
      "description": "true (default): the post is the client's own; false: it is a staff reply.",
      "type": "boolean"
    },
    "internal": {
      "description": "An internal ticket (default false).",
      "type": "boolean"
    }
  },
  "required": [
    "confirm",
    "domain_id",
    "department_id",
    "status_id",
    "priority_id",
    "type_id",
    "subject",
    "message",
    "from"
  ],
  "$schema": "https://json-schema.org/draft/2020-12/schema"
}

WRITE: confirm:true required. add a staff reply to a ticket. Say explicitly whether the client can see it (visible_to_client) and whether it is emailed to the client (send_email, default false). ticket / reply_ticket.

{
  "type": "object",
  "properties": {
    "confirm": {
      "type": "boolean",
      "const": true,
      "description": "Required: confirm the exact change and any client-visible or email effects before setting true."
    },
    "ticket_id": {
      "type": "integer",
      "exclusiveMinimum": 0,
      "maximum": 9007199254740991,
      "description": "Ticket id."
    },
    "message": {
      "type": "string",
      "minLength": 1,
      "maxLength": 50000,
      "description": "The reply text (HTML allowed)."
    },
    "from": {
      "type": "string",
      "minLength": 1,
      "maxLength": 200,
      "pattern": "^[^\\r\\n]+$",
      "description": "The sender name or address shown on the reply."
    },
    "visible_to_client": {
      "type": "boolean",
      "description": "true: the client can see the reply; false: staff only."
    },
    "send_email": {
      "description": "Email the reply to the client (default false).",
      "type": "boolean"
    }
  },
  "required": [
    "confirm",
    "ticket_id",
    "message",
    "from",
    "visible_to_client"
  ],
  "$schema": "https://json-schema.org/draft/2020-12/schema"
}

WRITE: confirm:true required. add an internal note to a ticket (not shown to the client). ticket / add_note with notetype 0.

{
  "type": "object",
  "properties": {
    "confirm": {
      "type": "boolean",
      "const": true,
      "description": "Required: confirm the exact change and any client-visible or email effects before setting true."
    },
    "ticket_id": {
      "type": "integer",
      "exclusiveMinimum": 0,
      "maximum": 9007199254740991,
      "description": "Ticket id."
    },
    "note": {
      "type": "string",
      "minLength": 1,
      "maxLength": 20000,
      "description": "The note text."
    }
  },
  "required": [
    "confirm",
    "ticket_id",
    "note"
  ],
  "$schema": "https://json-schema.org/draft/2020-12/schema"
}

WRITE: confirm:true required. add an internal note to a client record. ticket / add_note with notetype 1.

{
  "type": "object",
  "properties": {
    "confirm": {
      "type": "boolean",
      "const": true,
      "description": "Required: confirm the exact change and any client-visible or email effects before setting true."
    },
    "client_id": {
      "type": "integer",
      "exclusiveMinimum": 0,
      "maximum": 9007199254740991,
      "description": "Client id."
    },
    "note": {
      "type": "string",
      "minLength": 1,
      "maxLength": 20000,
      "description": "The note text."
    }
  },
  "required": [
    "confirm",
    "client_id",
    "note"
  ],
  "$schema": "https://json-schema.org/draft/2020-12/schema"
}

WRITE: confirm:true required. change one property of a ticket to another id: status, priority, department or type. Look the ids up first (vision_list_statuses and the like). Changing the department can change which statuses and priorities apply. ticket / update_properties.

{
  "type": "object",
  "properties": {
    "confirm": {
      "type": "boolean",
      "const": true,
      "description": "Required: confirm the exact change and any client-visible or email effects before setting true."
    },
    "ticket_id": {
      "type": "integer",
      "exclusiveMinimum": 0,
      "maximum": 9007199254740991,
      "description": "Ticket id."
    },
    "property": {
      "type": "string",
      "enum": [
        "status",
        "priority",
        "department",
        "type"
      ],
      "description": "What to change."
    },
    "value_id": {
      "type": "integer",
      "exclusiveMinimum": 0,
      "maximum": 9007199254740991,
      "description": "The id of the new status, priority, department or type."
    }
  },
  "required": [
    "confirm",
    "ticket_id",
    "property",
    "value_id"
  ],
  "$schema": "https://json-schema.org/draft/2020-12/schema"
}

WRITE: confirm:true required. add a staff member as an owner of a ticket, or remove one. ticket / update_properties with action staff.

{
  "type": "object",
  "properties": {
    "confirm": {
      "type": "boolean",
      "const": true,
      "description": "Required: confirm the exact change and any client-visible or email effects before setting true."
    },
    "ticket_id": {
      "type": "integer",
      "exclusiveMinimum": 0,
      "maximum": 9007199254740991,
      "description": "Ticket id."
    },
    "staff_id": {
      "type": "integer",
      "exclusiveMinimum": 0,
      "maximum": 9007199254740991,
      "description": "Staff id."
    },
    "action": {
      "type": "string",
      "enum": [
        "assign",
        "unassign"
      ],
      "description": "assign or unassign."
    }
  },
  "required": [
    "confirm",
    "ticket_id",
    "staff_id",
    "action"
  ],
  "$schema": "https://json-schema.org/draft/2020-12/schema"
}

WRITE: confirm:true required. add a tag (by title) to a ticket. ticket / add_live_tag.

{
  "type": "object",
  "properties": {
    "confirm": {
      "type": "boolean",
      "const": true,
      "description": "Required: confirm the exact change and any client-visible or email effects before setting true."
    },
    "ticket_id": {
      "type": "integer",
      "exclusiveMinimum": 0,
      "maximum": 9007199254740991,
      "description": "Ticket id."
    },
    "tag": {
      "type": "string",
      "minLength": 1,
      "maxLength": 100,
      "description": "The tag title."
    }
  },
  "required": [
    "confirm",
    "ticket_id",
    "tag"
  ],
  "$schema": "https://json-schema.org/draft/2020-12/schema"
}