Add a Helpdesk Integration Template

Yeastar P-Series Software Edition allows you to create and configure custom integration templates, which can be used to seamlessly integrate the PBX with a Helpdesk system via API, enabling data exchange and synchronization. This topic describes how to create a Helpdesk integration template and configure the necessary settings to meet specific operational requirements.

Requirements and restrictions

Requirements
  • PBX Server: The PBX server should meet the following requirements.
    • Firmware: Version 83.18.0.102 or later.
    • Plan: Enterprise Plan (EP) or Ultimate Plan (UP)
  • Helpdesk System: Supports REST API.
Restrictions
Supports to add up to 10 custom Helpdesk integration templates.

Prerequisites

  • You have basic coding skills
  • You have obtained the REST API documentation of your desired Helpdesk for reference, and get the following information:
    • Authentication method: Determine the authentication method used by your desired Helpdesk (None, basic, or OAuth2 authentication method are supported).
    • API request information: You have gathered the necessary API request URLs and data specification for the following features according to the capabilities of the Helpdesk and your specific requirements.
      API request Description
      Search contacts The API request URLs to search contacts within the Helpdesk using specific criteria.
      Get users Optional. The API request URL to retrieve user information from the Helpdesk.
      Create contacts Optional. The API request URL to add new contacts to the Helpdesk.
      Call journalling Optional. The API request URL to create call records in the Helpdesk.
      Create tickets Optional. The API request URL to create new tickets in the Helpdesk.

Procedure

  1. Log in to PBX web portal, go to Integrations > Helpdesk.
  2. In the Helpdesk list, click Custom.

    You are redirected to the Template Management page.

  3. Click Add to add a template.
  4. In the pop-window, complete the following template settings according to the capabilities the Helpdesk system and your specific requirements.
  5. Click Save to generate a custom Helpdesk integration template.

Configure general settings

In the General section, complete the basic settings for the template.

  • Logo: Upload a logo for the Helpdesk, which will be displayed in the Helpdesk list on the Integration page.
    Note: The logo file should meet the following requirements:
    • File format: PNG (recommended), JPG, or JPEG
    • Suggested Resolution: 150 × 150
    • File size: Less than 500KB
  • Helpdesk Name: Enter the name of the Helpdesk.
  • Max Concurrent Request: Specify the maximum number of concurrent HTTP requests allowed to the Helpdesk.
  • Remark: Optional. Enter a description for the Helpdesk template, which will be displayed in the Template Management page.

(Optional) Configure user association

In the User Association section, enable and configure the feature to support associating Helpdesk users with PBX extensions.
Note: If enabled, the system will require associating Helpdesk users with PBX extensions during integration, as shown in the following picture. Only the associated extension users can use the Helpdesk integration functionalities.

  1. Turn on the switch of User Association.
  2. In the Get User field, enter the Helpdesk API request URL for getting the list of Helpdesk users.
    Note:
    • The default HTTP request method is GET, if you need to use a different request method, you can manually change it in the template later. For more detailed descriptions about the template parameters in this scenario, see XML Description - User Association Scenario.
    • The values input by the users during the integration authentication process can be used as variables in the request if necessary.
    For example,
    https://www.api.example.com/v1/users?type=ActiveUsers
  3. In the User Field Mapping section, map the Helpdesk fields to the required PBX fields by specifying the JSON path (e.g. data.#(key=="value").field) for the corresponding fields in the Helpdesk response.
    Tip: For more information about the path syntax, see GJSON Path Syntax.
    PBX Field Description
    User Unique ID The unique ID of the user.

    For example, users.#.id.
    First Name The first name of the user, which will be displayed in the Helpdesk user list.

    For example, users.#.First_Name.
    Last Name The last name of the user, which will be displayed in the Helpdesk user list.

    For example, users.#.Last_Name.
    Email The email of the user, which will be displayed in the Helpdesk user list, and can be used for automatic association of Helpdesk users and PBX extensions.

    For example, users.#.Email.

Configure authentication method

In the Configure Authentication Method section, configure the authentication method based on the Helpdesk system's requirements.
None authentication

This method is used when there is no authentication required, or when the Helpdesk only requires relevant variables for the integration, such as an API Key for the request, or a webhook URL for real-time data delivery.

  1. In the Authentication Method drop-down list, select None.
  2. Optional: Click Add to add custom fields, which will be displayed as input field on the integration page, requiring users to provide the necessary information for the integration.
    Note:
    • If no fields are added, the Helpdesk will be integrated directly without requiring any additional settings or input from the users.
    • Supports up to 5 custom fields.
    • The values input by users during the integration authentication process can be used as variable values in the template.
    Setting Description
    Type Select the type of the custom field.
    • Text Input: A standard input field where users can enter plain text.
    • Password Input: A specialized input field for sensitive information, with text masked for privacy.
    • Dropdown List: A selectable list that allows users to choose from a pre-defined list of options.
    Name Specify the variable name for the field, which can be referenced within the template as needed.
    Title Specify the title for the field, which will be display above the input component.
    Dropdown Options If the Type is set to Dropdown List, enter the options in this field.
    Note: Use commas to separate multiple options. For example, option1,option2.
Basic authentication
This method authenticate requests using credentials, such as username and password or an API key. In this case, every HTTP request sent to the Helpdesk will include a header field in the format of Authorization: Basic {{.basic_string}}, where {{.basic_string}} is the Base64-encoded combination of the username and password or API key specified during the integration.

  1. In the Authentication Method drop-down list, select Basic.
  2. In the Credential Type drop-down list, select Username and Password or API Key according to the Helpdesk system's requirements.
  3. Configure the required fields for users to enter credentials, and add additional custom fields if needed.
    Note:
    • Supports up to 5 fields.
    • The values input by users during the integration authentication process can be used as variable values in the template.
    Setting Description
    Type Select the type of the custom field.
    • Text Input: A standard input field where users can enter plain text.
    • Password Input: A specialized input field for sensitive information, with text masked for privacy.
    • Dropdown List: A selectable list that allows users to choose from a pre-defined list of options.
    Name Specify the variable name for the field, which can be referenced within the template as needed.
    Title Specify the title for the field, which will be display above the input component.
    Dropdown Options If the Type is set to Dropdown List, enter the options in this field.
    Note: Use commas to separate multiple options. For example, option1,option2.
  4. In the Base64 Encoded Credential field, define the combination format of the credential variables, which will be used to generate the basic authentication string (basic_string).

    For example, {{.username:.password}} or {{.api_key:}}.

OAuth2 authentication

This method uses tokens to grant access without sharing credentials. It requires obtaining the necessary header and other parameters (e.g. OAuth access token) using specific API requests to the Helpdesk.

  1. In the Authentication Method drop-down list, select OAuth2.
  2. Configure the required fields for users to enter credentials.
    Note:
    • If more fields are required, you need to manually add custom fields in the template later. For more detailed descriptions about the template parameters in this scenario, see XML Description - Authentication Scenario.
    • The values input by users during the integration authentication process can be used as variable values in the template.
    Setting Description
    Type Select the type of the custom field.
    • Text Input: A standard input field where users can enter plain text.
    • Password Input: A specialized input field for sensitive information, with text masked for privacy.
    • Dropdown List: A selectable list that allows users to choose from a pre-defined list of options.
    Name Specify the variable name for the field, which can be referenced within the template as needed.
    Title Specify the title for the field, which will be display above the input component.
    Dropdown Options If the Type is set to Dropdown List, enter the options in this field.
    Note: Use commas to separate multiple options. For example, option1,option2.
  3. In the Authorization Endpoint field, enter the Helpdesk authorization URL, to which users will be redirected for authorization during integration.

    For example,

    https://www.api.example.com/auth/v2/authorize?client_id={{.client_id}}
  4. In the Token Endpoint field, enter the Helpdesk API request URL for getting access token and refresh token.

    For example,

    https://www.api.example.com/oauth/v2/token?client_id={{.client_id}}&client_secret={{.client_secret}}
  5. Optional: In the Scope (Optional) field, enter the scope to specify the data in the Helpdesk that the PBX is allowed to access.
    Note: Use comma to separate multiple fields.

    For example,

    contacts.read,contacts.write,calls.read,calls.write,user.read,user.write
  6. Optional: If the Helpdesk system authenticates requests using query parameters instead of scope, you can add the query parameters in the Additional Query String (Optional) field.

    For example, client_id={{.client_id}}&redirect_uri={{.redirect_uri}}.

After the template setting is saved, the authentication page of the Helpdesk will automatically display the PBX authentication information, which can be used to create an application in the Helpdesk system and retrieve the required authorization information from the Helpdesk for the integration.

Configure contacts searching for synchronization and call popup

In the Synchronize Contacts Automatically section, specify the contacts type available for users to select when configuring integration features, and specify the API requests to search for the specified types of contacts. These configurations can be used to implement Helpdesk contacts searching, automatic contact synchronization and call popup.
  1. Add and configure contact types and specify the corresponding API requests.

    • Contact Type: Enter the name of the contact type. For example Contacts.

      The name set here will appear as an option for automatic contact synchronization when users configure the integration features.

    • Contact Match Query URL: Enter the Helpdesk API request URL used to search for contacts with specific criteria.

      In this scenario, the following variables can be used as the values of criteria parameters:

      • The variables obtained from user input during the integration authentication process.
      • {{.Phone}}: The phone number associated with inbound or outbound calls, or the number entered by users for contact searching.
      For example,
      https://www.api.example.com/v1/Contacts/search?criteria=((Phone:equals:{{.Phone}})or(Home_Phone:equals:{{.Phone}})or(Mobile:equals:{{.Phone}})or(Asst_Phone:equals:{{.Phone}}))
  2. Configure the URL for call popup using one of the following methods.
    Specify URL Format
    Configure the call popup URL by specifying the URL format, where you can use variables to dynamically construct the URL.
    1. In the Contact Popup URL drop-down list, select Specify URL Format.
    2. In the URL Format field, enter the expression of the Contact URL.

      In this scenario, the following variables can be used, the values of which are obtained from the Helpdesk contact search results.

      Note: If the provided variables do not meet your requirements, you can manually edit the template later to define additional custom variables and retrieve the corresponding values. For more detailed descriptions about the template parameters in this scenario, see XML Description - Retrieve Additional Variables.
      For example,
      {{.doman_url}}{{.CustomValue}}/tab/{{Capitalize .ContactSyncType}}/{{.ContactId}}
    Retrieve from Contact Fields
    Extract the Contact URL directly from a specific field in the contact search response, where the contact URL can be retrieved.

    1. In the Contact Popup URL drop-down list, select Retrieve from Contact Fields.
    2. In the Contact Field for URL field, specify the JSON path for the corresponding field in the response. For example, data.#.contactUrl.
  3. In the Contact Field Mapping section, map the Helpdesk fields to the required PBX fields by specifying the JSON path (e.g. data.#(key=="value").field) for the corresponding fields in the Helpdesk response.
    Note: If more than one variable need to be retrieved for a field, use commas to separate the variables. For example, data.#(phone=="{{.Phone}}")#.street,data.#(mobile=="{{.Phone}}")#.street.
    1. Map the following required fields.

      • Contact ID: The ID of the searched contact. For example, data.#.id.
      • First Name: The first name of the searched contact. For example, data.#.first_name.
    2. Enable and map the respective PBX fields according to your needs.
      Note: You need to enable and map at least one phone number.

    3. If the existing PBX fields do not provide the variables you need, enable and map the desired response field to the Custom Value field, which can be referenced in the template with the variable name {{.CustomValue}}.
      Note: This variable is specially used for constructing the Contact URL, and will not appear in the PBX contact details.

(Optional) Configure new contact creation

If you want to enable the creation of a new contact in the Helpdesk when the caller’s number does not match any existing Helpdesk contact, enable and configure the Create New Contact settings.

  1. Turn on the switch of Create New Contact.
  2. Add and configure the contact types available for users to select when configuring integration features.
    • Contact Type: Specify the type of the contact. For example, Contacts.
    • Contact Creation URL (POST): Enter the Helpdesk API request URL used to create a new contact.
      For example,
      https://www.api.example.com/v1/Contacts
    • Contact Creation Request Body: Enter the request body (in JSON format) to pass the contact information.
      In this scenario, the following variables can be used:
      • The variables obtained from user input during the integration authentication process.
      • {{.LastName}}: Required. The last name of the contact.
      • {{.FirstName}}: Required. The first name of the contact.
      • {{.BusinessNumber}}: Required. The phone number of the contact.
      Note: If the provided variables do not meet your requirements, you can manually edit the template later to define additional custom variables and retrieve the corresponding values. For more detailed descriptions about the template parameters in this scenario, see XML Description - Retrieve Additional Variables.
      For example,
      {
  "data": [
    {
      "Last_Name": "{{.LastName}}",
      "First_Name": "{{.FirstName}}",
      "Phone": "{{.BusinessNumber}}"
    }
  ]
}

(Optional) Configure call journaling

If you want to enable call journaling to automatically log call activities and details in the Helpdesk, enable and configure the Call Journal feature.

  1. Turn on the switch of Call Journal.
  2. Configure the API request and body for call journaling.
    • Create Call Journal URL (POST): Enter the Helpdesk API request URL used to create a call log in the Helpdesk.
      For example, 
      https://www.api.example.com/v2/Calls
    • Call Journal Creation Request Data: Enter the request body (in JSON format) to pass the call details.
      Note: For the variables supported in the request body, see XML Description - Call Journal Variables.
      For example,
      {
  "data": [
    {
      "{{.Owner}}{{.WhoModule}}": {
        "Description": "{{.Description}}",
        "Voice_Recording__s": "{{.RecordPath}}",
        "Call_Start_Time": "{{TimeFormat .StartTimeUnix 'yyyy-MM-ddTHH:mm:ss-z' '1'}}",
        "Subject": "{{.Subject}}",
        "Call_Type": "Inbound",
        "Call_Result": "{{.Call_Log_Status}}",
        "Call_Duration": "{{.Talk_Duration_Sec}}"
      }
    }
  ]
}
  3. If you want to allow users to customize specific settings for call journaling, including key attributes such as logging details and call recording playback option, enable the following options and configure the default values as needed.
    Note:
    • Subject: If enabled, enter a default subject for call journal. All call logs will be created with the specified subject.
    • Description: If enabled, specify the details of the call logs.
      For example, 
      Call: {{.Time}} {{.Call_Log_Status}} from {{.Call_From}} to {{.Call_To}} {{.Talk_Duration}}
    • Play Call Recording: Decide whether to allow users to configure the option for playing call recordings in the Helpdesk.

(Optional) Configure automatic new ticket creation

If you want to enable the automatic creation of new tickets based on calls, enable and configure the Create New Ticket Automatically settings.
Note: When the feature is set to create a ticket before the call (i.e. when the phone rings) in later use, it might be missing some information. In this case, you need to manually edit the template to update the information for the created ticket. For more information, see XML Description - Extended Configurations,

  1. Turn on the switch of Create New Ticket Automatically.
  2. Configure the API request and body for new ticket creation.
    • Create New Ticket URL (POST): Enter the Helpdesk API request URL used to create a new ticket in the Helpdesk.
      For example, 
      https://www.api.example.com/api/v1/tickets
    • New Ticket Creation Request Body: Enter the request body (in JSON format) to pass the ticket details.
      Note: For the variables supported in the request body, see XML Description - New Ticket Creation Variables.
      For example,
      {
   "subject":"{{.Subject}}",
   "contactId":"{{.ContactId}}",
   "phone":"{{.ContactNumber}}",
   "description":"{{.Description}}"
}
  3. If you want to allow users to customize subjects and descriptions for the new ticket, enable the following options and configure the default values as needed.
    Note:
    • Subject: If enabled, enter a default subject for the ticket.
      For example, 
      {{.Communication_Type}} {{.Call_Status}} - from {{.Call_From}} to {{.Call_To}}
    • Description: If enabled, specify the details of the ticket.
      For example, 
      {{.Time}} {{.Communication_Type}} {{.Call_Status}} - from {{.Call_From}} to {{.Call_To}} {{.Talk_Duration}}