GraphQL API

Leverage the power of GraphQL with Help Desk MX to seamlessly integrate your store’s support system with external tools, mobile applications, and other services. By connecting Help Desk MX with external systems, your store can efficiently manage customer queries, emails, and offline chat messages from a unified interface. This API helps you streamline support operations, enhance customer satisfaction, and ultimately drive more conversions.

For comprehensive information about GraphQL, refer to the GraphQL developer guide on the Magento DevDocs page.

Prerequisites

To begin using GraphQL with Help Desk MX, ensure that the Help Desk MX module is installed on your store. Additionally, the Helpdesk GraphQL module must be installed, which is included with the purchase of Help Desk MX. To install Helpdesk GraphQL module refer to Installing the extension section.

Helpdesk GraphQL objects overview

Customer object

The Customer object allows you to retrieve customer-specific ticket data. This object supports the following attributes:

Attribute	Data Type	Description
mstHelpdeskTickets	HelpdeskTickets	Fetches the tickets associated with a given customer. You must provide either the customer's information or parameters like external_id or order_id.

Mutation object

Mutations are used to create, update, or delete resources. In GraphQL, mutations function similarly to POST, PUT, or DELETE requests in REST.

The Mutation object in this module contains the following attributes:

Attribute	Data Type	Description
mstHelpdeskCreateTicket	MstHelpdeskTicketInput	Creates a new help desk ticket. This attribute is required and cannot be null.
mstHelpdeskAddMessage	MstHelpdeskMessageInput	Adds a message to an existing ticket. This attribute is required and cannot be null.

HelpdeskTicketInput input object

The HelpdeskTicketInput object is an input type that contains various fields. It allows users to create and submit tickets with specific details.

Attribute	Data Type	Description
subject	String	The subject line of the ticket. This field is required.
message	String	The body of the ticket message. This field is required.
channel	HelpdeskTicketChannel	Indicates the communication channel through which the ticket was submitted. This field is required.
telephone	String	Customer's phone number.
current_url	String	The current URL where the ticket was submitted.
close_ticket	Boolean	Indicates whether the ticket is marked as closed.
department_id	Int	The ID of the department handling the ticket.
priority_id	Int	The priority level assigned to the ticket.
custom_fields	Array	An array of custom field inputs related to the ticket.

HelpdeskTicketsFilterInput input object

The HelpdeskTicketsFilterInput object allows you to filter tickets based on specific criteria.

Attribute	Data Type	Description
external_id	String	Filters tickets by External ID.
order_id	Int	Filters tickets by Order ID.

HelpdeskMessageInput input object

The HelpdeskMessageInput object is used to send messages within a ticket.

Attribute	Data Type	Description
customer_name	String	Name of the guest customer (if applicable).
customer_email	String	Email address of the guest customer.
message	String	The message content to be added to the ticket.

HelpdeskCustomFieldInput input object

The HelpdeskCustomFieldInput object handles custom fields related to tickets.

Field	Data Type	Description
code	String	The identifier for the custom field. This field is required.
value	String	The value entered for the custom field.

HelpdeskTicketsOutput output object

This object provides the output details of tickets fetched from the system. The MstHelpdeskTicketsOutput contains data with the following attributes:

Attribute	Data Type	Description
items	Array	An array of ticket objects. This field is required.
total_count	Int	Total number of tickets retrieved.
page_info	SearchResultPageInfo	Pagination information for the search results.

HelpdeskStatus object

The HelpdeskStatus object provides the current status of a ticket. The MstHelpdeskStatus contains data with the following attributes:

Attribute	Data Type	Description
status_id	Int	The ID of the ticket's current status. This field is required.
name	String	The name of the ticket's current status. This field is required.
code	String	The code representing the ticket status. This field is required.
color	String	The color associated with the ticket's status. This field is required.

HelpdeskDepartment object

The HelpdeskDepartment object manages department-related data for help desk tickets. The MstHelpdeskDepartment contains data with the following attributes:

Attribute	Data Type	Description
department_id	Int	The ID of the help desk department. This field is required.
name	String	The name of the help desk department. This field is required.

HelpdeskPriority Object

The HelpdeskPriority object manages priority data for tickets. The MstHelpdeskPriority contains data with the following attributes:

Attribute	Data Type	Description
priority_id	Int	The ID of the priority level. This field is required.
name	String	The name of the priority level. This field is required.
color	String	The color representing the priority level. This field is required.

HelpdeskTicket object

The HelpdeskTicket object represents individual tickets within the system.The MstHelpdeskTicket contains data with the following attributes:

Attribute	Data Type	Description
subject	String	The subject of the ticket. This field is required.
code	String	The ticket type code. This field is required.
priority	MstHelpdeskPriority	Priority data for the ticket.
status	MstHelpdeskStatus	Current status of the ticket.
department	MstHelpdeskDepartment	Department handling the ticket.
customer	Customer	Customer information.
order	Order	Order information associated with the ticket.
messages	MstHelpdeskMessages	List of messages associated with the ticket.
customFields	Array	Array of custom fields related to the ticket.

HelpdeskMessages object

The HelpdeskMessages object is used to work with the ticket's messages data. The MstHelpdeskMessages contains data with the following attributes:

Attribute	Data Type	Description
items	Array	Array of ticket messages. This field is required.
page_info	SearchResultPageInfo	Pagination information for messages.
total_count	Int	Total number of messages in the ticket.

HelpdeskMessage object

The HelpdeskMessage object is used to work with the message data fields. The MstHelpdeskMessage contains data with the following attributes:

Attribute	Data Type	Description
triggeredBy	MstHelpdeskTriggeredBy	Indicates who triggered the message. This field is required.
ownerName	String	The name of the person who triggered the message. This field is required.
text	String	The message content. This field is required.
createdAt	String	The date and time the message was created. This field is required.

HelpdeskTicketCustomField object

The HelpdeskTicketCustomField object manages custom fields for tickets. The MstHelpdeskTicketCustomField contains data with the following attributes:

Attribute	Data Type	Description
name	MstHelpdeskTriggeredBy	The name of the custom field. This field is required.
value	String	The value of the custom field.

HelpdeskCustomFieldsFilterInput object

The HelpdeskCustomFieldsFilterInput object filters custom fields based on visibility.

Attribute	Data Type	Description
is_visible_customer	Boolean

HelpdeskCustomFieldsOutput object

It is used to output the custom fields. The MstHelpdeskCustomFieldsOutput contains data with the following attributes:

Attribute	Data Type	Description
items	Array of MstHelpdeskCustomField	Represents the custom fields of the ticket The field is non-nullable.
total_count	Int	Depicts the total number of messages.
page_info	SearchResultPageInfo	Displays the resulting page of the search.

HelpdeskCustomField object

Works with the custom fields of the ticket. The MstHelpdeskCustomField contains data with the following attributes:

Attribute	Data Type	Description
name	String	Represents the name of the custom field. The field is non-nullable.
code	String	Stands for the code marking of the custom field. The field is non-nullable.
type	String	The type of the custom field data. The field is non-nullable.
options	Array of MstHelpdeskCustomFieldOption	Options of the custom field.
description	String	Description of the custom field. The field is non-nullable.
is_required_customer	Boolean	If the field requires customer actions. The field is non-nullable.
is_visible_customer	Boolean	If the field is customer visible. The field is non-nullable.
is_editable_customer	Boolean	If the field can be edited by customer. The field is non-nullable.
is_visible_contact_form	Boolean	If the field contains customer visible contact form. The field is non-nullable.

HelpdeskCustomFieldOption object

Sets the options for the custom fields of the ticket. The MstHelpdeskCustomFieldOption contains data with the following attributes:

Attribute	Data Type	Description
value	String	Represents the value of the custom field option. The field is non-nullable.
label	String	Stands for the label of the custom field option. The field is non-nullable.