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
    • Firmware: Version 83.21.0.66 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, OAuth2, or Bearer token authentication method are supported).

      If OAuth2 or Bearer token authentication method is used, gather the following necessary API endpoints and data specification.

      Function Description
      Authorization The authorization URL to redirect users to the authorization page for authentication and consent.
      Get access token The API request URL for obtaining an access token.
      Refresh access token Optional. The API request URL for obtaining a refresh token.
    • 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.
      Note: If you need to fetch a large number of users, you should also collect the relevant pagination parameters (such as page, pageSize, limit, or offset) to retrieve user information in batches.
      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 Pagination Type drop-down list, select the appropriate pagination mode according to the Helpdesk requirements.
    Note: For the pagination modes that require multiple requests, a maximum of 100 requests are supported in a single synchronization operation.
    Mode Description
    Disabled PBX only sends one request and no pagination parameters are required.

    This mode can be used when the API returns all records in a single response without splitting the results.

    Page Number Pagination

    PBX sends multiple requests to retrieve user data based on page number and page size. It automatically increments the page number with each subsequent request until all data is retrieved.

    If selected, you need to configure the pagination parameters as follows:

    • Page Parameter Name: Enter the parameter name used to specify the page number in API requests.
    • Page Start Value: Specify the initial page number from which to start querying data.
    • Page Size Parameter Name: Enter the parameter name used to specify the number of records per page in API requests.
    • Page Size Value: Specify the maximum number of records to return in a single page.
    Offset Pagination PBX sends multiple requests to retrieve user data based on a starting offset and record limit. It automatically increases the offset value by the limit value with each subsequent request until all data is retrieved.

    If selected, you need to configure the pagination parameters as follows:

    • Offset Parameter Name: Enter the parameter name used to specify the initial offset position for pagination.
    • Offset Value: Specify the starting position for data retrieval by indicating the number of records to skip.

      For example, a value of 1 starts from the first record, while 100 starts retrieval from the 100th record.

    • Limit Parameter Name: Enter the parameter name used to specify the number of records per page in API requests.
    • Limit Value: Specify the maximum number of records to return in a single page.
    Link Pagination PBX sends multiple requests to retrieve user data by using the URL pointing to the next page of data in the API response, continuing this process until all data has been retrieved.

    If selected, you need to specify the JSON path (e.g. links.next) in the Next Page Link Path field to obtain the link for the next page of data.
  4. 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. Configure the OAuth2 Authorization settings.

    Setting Description
    Authorization Endpoint 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}}
    Token Endpoint Enter the Helpdesk API request URL for obtaining an access token and refresh token.

    For example,

    https://www.api.example.com/oauth/v2/token?client_id={{.client_id}}&client_secret={{.client_secret}}
    Content Type Select the content type of the token retrieval request.
    Scope Optional. 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
    Additional Query String Optional. If the Helpdesk system authenticates requests using query parameters instead of scope, add the query parameters in this field.

    For example, client_id={{.client_id}}&redirect_uri={{.redirect_uri}}.
  4. Optional: Configure token refresh settings as needed.

    Setting Description
    Token Refresh Request Method Select the HTTP request method for the token refresh API.
    Token Refresh Endpoint Enter the API request URL for refreshing the access token.
    Token Refresh Content Type Select the content type of the token refresh request.
    Token Refresh Time (min) Specify how often (in minutes) the system should automatically refresh the access token.
    Note:
    • If set to 0, the system will not refresh the token automatically.
    • If left blank, the system will automatically refresh the access token every 25 minutes by default.
    Token Refresh Request Body The request body for the token refresh API.
Bearer Token authentication
This method authenticates requests using a bearer token, which is typically obtained through an authorization process (such as OAuth2). Every HTTP request sent to the Helpdesk must include a header field in the format of Authorization: Bearer {{.AccessToken}}, where {{.AccessToken}} is the token value granted by the Helpdesk.
  1. In the Authentication Method drop-down list, select Bearer Token.

  2. Configure the required fields for users to enter credentials, and add additional custom fields if needed.

    Note:
    • Supports up to 10 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.
  3. Configure token retrieval settings according to the API specification.

    Setting Description
    Token Endpoint Enter the Helpdesk API request URL to request the access token.

    For example,

    https://www.api.example.com/oauth/v2/token?client_id={{.client_id}}&client_secret={{.client_secret}}&grant_type=client_credentials
    The token obtained from the endpoint will be stored in the variable {{.AccessToken}}.
    Content Type Select the content type of the token retrieval request.
  4. Optional: Configure token refresh settings as needed.

    Setting Description
    Token Refresh Request Method Select the HTTP request method for the token refresh API.
    Token Refresh Endpoint Enter the API request URL for refreshing the access token.
    Token Refresh Content Type Select the content type of the token refresh request.
    Token Refresh Time (min) Specify how often (in minutes) the system should automatically refresh the access token.
    Note:
    • If set to 0, the system will not refresh the token automatically.
    • If left blank, the system will automatically refresh the access token every 25 minutes by default.
    Token Refresh Request Body The request body for the token refresh API.

(Optional) Configure request headers

Define custom HTTP headers to be included in predefined Helpdesk synchronization requests (e.g., user association, contact synchronization. etc.).
Note:

  • Supports to add up to 20 custom headers.

  • These custom headers will not be applied to the authentication-related requests (e.g. obtaining or refreshing an access token) and custom-configured requests.

  • Avoid defining the Authorization header here, as it will override the one set by the authentication method (Basic, OAuth2, and Bear Token authentication).
  1. In the Headers section, click Add.
  2. Add and configure the desired header.
    Setting Description
    Name Header name, such as Content-Type for content type or Accept for expected data format.
    Value Header value, either a specific value or a variable.
    Note: The variables defined in the Authentication Method can also be used. For example, if a variable named client_id is set, you can reference it in the header value as {{.client_id}}.
    Description A brief explanation of the header’s function or purpose for reference.

(Optional) Add follow-up requests

If your integration requires additional operations after specific pre-defined requests are completed, you can configure follow-up requests here. These requests will be automatically triggered upon successful completion of the specified operations, and their response data can be extracted and stored in global variables for reuse elsewhere in the integration.
Note: You can add up to 10 follow-up requests.

  1. In the Request Configuration > Follow-up Requests section, click Add.
  2. Configure the details of the follow-up request.
    Setting Description
    Triggered Event Specify the pre-configured system event that triggers this request.
    Request Method Select the HTTP method for the API request.
    URL Enter the endpoint URL for the subsequent operation.
    For example, 
    https://api.example.com/rest-services/login
    Headers Define HTTP headers of the request as a JSON object. You can use {{.varname}} to insert dynamic values.

    For example,

    {"Content-Type":"application/json", "X-Custom-Header": "{{.DynamicValue}}"}
    Request Body Define the data payload of the request as a JSON object. You can use {{.varname}} to insert dynamic values.
    For example,
    {"lastName":"{{.LastName}}","ownerId":"{{.Id}}","phone":"{{.BusinessNumber}}"}
    Response Field Path Define the JSON path to extract data from the response of this follow-up request.
    Note: Use commas , to separate multiple variable names. For example, $.data.access_token, $.tokens[0].value
    Target Variable Name Define the name of the system variable to store the value extracted from the response. These can be existing variables or new custom variables.
    Note:
    • Use commas , to separate multiple variable names. For example, token,refresh.

    • The variables are assigned in the same order as the fields specified in the Response Field Path. For example, the first variable receives the value of the first JSONPath, the second variable receives the value of the second JSONPath, and so on.

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. Optional: To configure which call journaling settings will be available in the integration, select the checkbox of the desired options, and set their default values.
    Option Description
    Subject If enabled, the corresponding setting will be available to configure in the integration. This can be used to set a default subject for all synchronized call logs.
    Note:
    Description If enabled, the corresponding setting will be available to configure in the integration. This can be used to specify the details of the synchronized call logs.
    For example, 
    Call: {{.Time}} {{.Call_Log_Status}} from {{.Call_From}} to {{.Call_To}} {{.Talk_Duration}}
    Note:
    Play Call Recording If enabled, the corresponding setting will be available to configure in the integration. This can be used to determine whether to enable call recording playback within the Helpdesk.
    Disable Display Missed Call Records in Unanswered Agents If enabled, the corresponding setting will be available to configure in the integration. This can be used to determine whether call logs for queue and ring group calls are synchronized only to the Helpdesk of the agent who answered the call, while missed call logs for the same call are not synchronized to the Helpdesk of agents who did not answer.

(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}}