How to use WSDesk create ticket API with third-party forms and plugins?

This article explains WSDesk create ticket API integration process. It also consists testing of the API using Postman tool, demonstrations to create a support ticket using a simple HTML form and integration to third-party contact forms like Contact Form 7 and Gravity Forms.

Refer the product page to know about other features or the documentation for a detailed explanation of each feature.

What is WSDesk create ticket API?

This API will allow users to submit WSDesk supports tickets from websites built on any platform. Although WSDesk is built on WordPress, with this API, you will be able to create support tickets from any page on the web into WSDesk. The API also supports custom form plugins like Contact Form  7 and Gravity Forms.

WSDesk API Parameters

There are two mandatory parameters required for API integration. They are:

attributetypedescription
actionstringWSDesk API name
api_keyalphanumericAPI key generated in WSDesk

 

The WSDesk API name is wsdesk_api_create_ticket. This is the action that triggers the API call. Whereas, the api_key is the unique key found in the WSDesk general settings. In addition to this, you need to add the slugs of WSDesk ticket fields to capture the form values (we will discuss this process in later part of this article).

JSON Response Object

statusmessagedescription
success“Support Request Received Successfully”The request is sent effectively
error“Authentication Error”Occurs when API key is incorrect
“API not enabled”Occurs when API key setting is not enabled in WSDesk

 

If the API is not returning any of the above statuses, you can check for HTTP status codes like 200, 400, 404 and so on. These codes are usually returned by the server. If you are not receiving the required response, you can inspect the element by right-clicking on the page and viewing the error code. You can check this link for a better understanding of these status codes.

Using WSDesk create ticket API

You can use the WSDesk create ticket API in the following ways:

Testing WSDesk create ticket API with Postman

Postman is one of the popular environment used for API development, testing, designing, debugging and so on. Hence, I am using this tool to test the WSDesk create ticket API for this demonstration.

Here are the steps to test WSDesk API with Postman:

  • The first step is to enable WSDesk API setting in WSDesk. Go to WSDesk > Settings > General tab, and scroll down to find the WSDesk API setting. Tick the Enable API checkbox to receive your WSDesk API key. Make a note of this API key and save changes.
    The setting is as shown in the screenshot below.
WSDesk Helpdesk | Enable WSDesk API

Enable WSDesk API

  • Next, move to the Ticket Fields section to create input fields for our support form. This step is crucial, as the ticket fields created in this step will only be used for raising the ticket in any environment.

For our demonstration, in addition to the default ticket fields, I have added an additional field for accepting attachment files as shown in the screenshot below.

WSDesk Helpdesk | Created Ticket Fields

Created Ticket Fields in WSDesk

 

Tip: You can refer to this section of the documentation to know how to create new ticket fields in WSDesk.

Now that we have configured WSDesk API settings, let us test in the Postman tool.

  • Download and install Postman tool. Once it is installed successfully, you are shown a window as shown in the screenshot below.
WSDesk Helpdesk | Postman Startup Window

Postman Startup Window

Close this window for now as we do not need it at this time.

  • Next, from the dropdown list located in the center part of the window, select POST request as shown in the below screenshot. This is because all requests have to be made using the POST method.
WSDesk Helpdesk | Postman | Selecting POST Method

Postman | Selecting POST Method

  • In the URL field given right next to the above dropdown list, enter your website URL appended with wp-admin/admin-ajax.php.
    A sample screenshot is shown below.
WSDesk Helpdesk | Postman | Entering Website URL

Postman | Entering Website URL

Replace http://localhost/demostore with your website URL before adding the remaining part of the URL.

  • In the next step, click on Body submenu to enter form data.

In the first row, enter the value action in the Key column and wsdesk_api_create_ticket in the Value column. Similarly, enter api_key in the first column and your respective WSDesk API in the second column as shown in the below screenshot.

WSDesk Helpdesk | Postman | Entering action & api_key

Postman | Entering action & api_key

In the remaining rows, users can enter the keys/slugs of the input fields created in WSDesk. These fields may vary depending on the user.

Let us add the keys of four input fields which we created in WSDesk in the earlier part of this article. To get the slug of each ticket field, go back to WSDesk Ticket Field section and hover on a ticket field to view respective key as shown in the screenshot below.

WSDesk Helpdesk | WSDesk Ticket Field Keys

WSDesk Ticket Field Keys

Note down all the key values or copy them by doing a right click and inspecting each element. Further, to test the API, enter appropriate values for each key in the Value column.

An important point to remember is that there is no slug/key for attachment files. Hence, you need to enter its Key value as “file[]“. This key represents file array but takes only one attachment at a time. You can use multiple file[] keys for accepting multiple attachments. Additionally, change the input type to file from the given drop-down in the Key column.

WSDesk Helpdesk | Postman | Keys and Values

Postman | Keys, and Values for Testing

  • Finally, click on the Send button to send the request. If the request is successful, you will see the success message as shown in the below screenshot.
WSDesk Helpdesk | Postman | Send Request

Postman | Send Request

Move to WSDesk Tickets section to see the generated ticket. The following screenshot shows the generated ticket based on our above demonstration.

WSDesk Helpdesk | Postman | Ticket Generated

Ticket Generated using Postman Tool

Now that we know the WSDesk create ticket API is working as expected, let us take a few examples to see how one can raise a ticket from any page.

Using WSDesk create ticket API with simple HTML form

For this example, I’ll create a simple HTML page and redirect it to a javascript function.

Open a text editor(like notepad++) and create an HTML file with the following code:

<html>
<head>
<script src="http://ajax.googleapis.com/ajax/libs/jquery/1.7.1/jquery.min.js" type="text/javascript"></script> <!-- Remove this code if you have already included jQuery-->
<script> 
 $( document ).ready( function(){
 jQuery('.eh_crm_support_main').on('submit','form#eh_crm_ticket_form',function (e) { //CHANGE THE CLASS NAME AND FORM NAME ACCORDING TO YOUR FORM
 e.preventDefault(); // avoid to execute the actual submit of the form you may remove this code if you want the form to submit after the ticket is added.

 var btn = jQuery("#crm_form_submit"); //id of the submit button
 btn.prop("disabled","disabled");
 var fd = new FormData();
 fd.append('action','wsdesk_api_create_ticket'); //THIS MUST REMAIN SAME
 fd.append('api_key', '6fd814bd95e1f39c6465609b03ddb70d'); //This will vary from user to user. Find this in the general settings tab.
 fd.append('request_title', jQuery('#request_title').val()); //The index must be the same as the slug of the field that you noted down by inspecting element.
 fd.append('request_description', jQuery('#request_description').val());
 fd.append('request_email', jQuery('#request_email').val());
 if(jQuery("#ticket_attachment").length !=0 ) //code for attachments
 {
 var files=[];
 var file = jQuery("#ticket_attachment");
 jQuery.each(jQuery(file), function (i, obj) {
 jQuery.each(obj.files, function (j, file) {
 fd.append('file[' + j + ']', file);
 });
 });
 }
 jQuery.ajax({
 type: "POST",
 url: "http://localhost/demostore/wp-admin/admin-ajax.php", //full URL of their wordpress site 
 processData: false,
 contentType: false,
 data:fd, // serializes the form's elements.
 success: function (data)
 {
 btn.removeProp("disabled");
 response=JSON.parse(data);
 if(response.status=="success")
 {
 alert(response.message); //success code
 }
 else
 {
 alert(response.message); //fail code
 }

 },
 error: function (jqXHR, textStatus, errorThrown) {
 console.log(textStatus, errorThrown);
 }
 });
 });
 });
</script>

</head>
<body>
<div class="eh_crm_support_main">
 <form class="support_form" id="eh_crm_ticket_form" method="POST">
 <span>Email </span>*<input type="email" name="request_email" id="request_email" placeholder="Enter Email" required="">
 <br>
 <span>Subject </span>*<input type="text" name="request_title" id="request_title" placeholder="Enter Subject" required="">
 <br>
 <span>Description </span>*<input type="text" name="request_description" id="request_description" placeholder="Enter Description" required="">
 <br>
 <span>Attachment </span> <input type="file" name="ticket_attachment" id="ticket_attachment" multiple="">
 <br>
 <br>
 <button type="submit" id="crm_form_submit" class="btn btn-primary" data-loading-text="Submitting...">Submit Request</button>
 </form>
</div>

</body>
</html>

Note: Replace the api_key value in the javascript with your WSDesk API key, and the website URL with your complete site URL.

Once you have saved the file with the .html extension, open it in the browser to create a ticket.

Further, enter the form fields and click on the Submit Request button to submit the ticket. To see the response status, right-click on the page to inspect the elements and click on the Network tab to see the response message.

A sample screenshot is shown below.

WSDesk Helpdesk | HTML Form | Submitted Request

HTML Form | Submitted Request

The ticket will be generated in WSDesk as shown in the screenshot below.

WSDesk Helpdesk | HTML Form | Ticket Generated

HTML Form | Ticket Generated

Using WSDesk create ticket API with Contact Form 7

To integrate WSDesk with Contact Form 7, copy the following code and paste it into the Theme Functions(functions.php) file of your active website theme.

add_action( 'wpcf7_mail_sent', 'your_wpcf7_mail_sent_function' ); // Action to get posted data from the contact form 7.
   function your_wpcf7_mail_sent_function( $contact_form ) {
       $title = $contact_form->title;
       $submission = WPCF7_Submission::get_instance();
     if ( $submission ) {
      $posted_data = $submission->get_posted_data();
     if($posted_data['_wpcf7']!=85)//85 is Form ID. Replace it with your respective form ID
      { return;
      }
$url="http://localhost/demostore/wp-admin/admin-ajax.php"; //Full URL of the admin-ajax file.
$response = wp_remote_post($url,array(
'method'=>'POST',
'body' => array(
'action'=>'wsdesk_api_create_ticket',
'api_key' => '7606eb3db86e989218cf0c644b5063ba',
'request_title' => $posted_data['your-subject'],
'request_email' => $posted_data['your-email'],
'request_description'=>$posted_data['your-message'] )
));
$response=json_decode($response['body'],true);

   if($response['status']=='success')
      {} //code if success
   else
      {} //code if fails
}
}

Following is a screenshot of the ticket raised using Contact Form 7.

WSDesk Helpdesk | Contact Form 7 | Ticket Raised

Contact Form 7 | Ticket Raised

The below screenshot shows the ticket generated using Contact Form 7 in WSDesk.

WSDesk Helpdesk | Contact Form 7 | Ticket Generated

Contact Form 7 | Ticket Generated

The Contact Forms IDs can be found in the short-code of the respective forms, as shown in the screenshot below.

WSDesk Helpdesk | Contact Form 7 | Form IDs

Contact Form 7 | Form IDs

 

Note: Contact Form 7 does not support uploading of files to this filter. Hence, uploading attachment is not possible from Contact Form 7 to WSDesk. Replace the api_key and website URL($url value) to your respective values.  

Using WSDesk create ticket API with Gravity Forms

You can integrate WSDesk with Gravity Forms by pasting the following code into the Theme Functions(functions.php) file of your active website theme.

add_action( 'gform_after_submission_8', 'after_submission', 10, 2 ); //8 is the example form ID. Replace it with yours.
 function after_submission($entry, $form)
 {
 $url="http://example.com/wp-admin/admin-ajax.php";
 $response = wp_remote_post($url,array(
 'method'=>'POST',
 'body' => array('action'=>'wsdesk_api_create_ticket', // THIS MUST REMAIN SAME
 'api_key'=>'03db2afcc8ae46846202900427d4a96c', //This will vary from user to user. Find this in the general settings tab.
 'request_email' => $entry[2],//2 is the Field ID number
 'request_title' => $entry[11],
 'request_description'=> $entry[12])
 ));
 $response=json_decode($response['body'],true);
 die(print_r($response,true));
 if($response['status']=='success')
 {die('success');} //code if success
 else
 {die('failed');} //code if fails
 }

Following screenshot shows a ticket raised using Gravity Form.

WSDesk Helpdesk | Gravity Form | Ticket Submitted

Gravity Form | Ticket Submitted

The below screenshots shows the ticket raised using Gravity Forms in WSDesk.

WSDesk Helpdesk | Gravity Form | Ticket Generated

Gravity Form | Ticket Generated

 

Note: The wp_remote_post function in the above code is a WordPress function to make API calls. It does not accept files. Hence, using this function, users will not be able to send attachments. If you need to accept attachments, you can do it via Javascript like shown in the HTML example or using cURL in PHP. Follow the same drill for replacing $url and api_key values with yours.

Hence in this way, WSDesk can be integrated into websites that are built by any other platforms. This gives you an advantage of using WSDesk(which is built on WordPress) to handle your customer support from websites that are not built using WordPress.

 


To explore more details about the plugins, go check out WSDesk – WordPress Helpdesk Plugin.

Read the product setting up article to understand the plugin, in detail. Or check out the product documentation section for more related articles.

You can also check out other WordPress and WooCommerce plugins in ELEX.

    Leave a Reply