# Add a Helpdesk Integration Template

When your helpdesk isn't one of the pre-built integrations, you can describe the connection yourself with a custom template. The template tells Cloud Voice how to authenticate against the helpdesk's REST API and which endpoints to call for each feature, so the two systems can share and sync data. This page walks through creating a template and filling in the settings you need.

## Requirements and restrictions

**Requirements**

- **PBX server** (the Private Branch Exchange that runs your phone system)
  - **Firmware**: version 84.23.0.123 or later.
  - **Plan**: Enterprise Plan (EP) or Ultimate Plan (UP).
- **Helpdesk system**: must expose a REST API.

**Restrictions**

- You can add up to **10** custom helpdesk integration templates.

## Before you begin

Building a template means mapping your helpdesk's API onto Cloud Voice's fields and requests, so plan for the following:

- You are comfortable with basic coding and reading API documentation.
- You have your helpdesk's REST API reference on hand and have collected the details below.

**Authentication method**

Identify how the helpdesk authenticates requests. Cloud Voice supports **None**, **Basic**, **OAuth2**, and **Bearer token**. If the helpdesk uses **OAuth2** or **Bearer token**, gather these endpoints and their data specifications:

| Function | Purpose |
|----------|---------|
| Authorization | The URL that redirects users to the helpdesk's authorization and consent page. |
| Get access token | The API request URL that issues an access token. |
| Refresh access token | Optional. The API request URL that issues a refresh token. |

**API request information**

Depending on which features you want and what the helpdesk offers, collect the request URLs and data specifications for the following:

| API request | Purpose |
|-------------|---------|
| Search contacts | URLs that look up helpdesk contacts by specific criteria. |
| Get users | Optional. The URL that returns helpdesk user information. |
| Create contacts | Optional. The URL that adds new contacts to the helpdesk. |
| Call journaling | Optional. The URL that creates and/or updates call records in the helpdesk. |
| Chat journaling | Optional. The URL that creates an object (such as a task) to hold synced chat data. |
| Create tickets | Optional. The URL that opens new tickets in the helpdesk. |

:::note
If you plan to pull a large user list with **Get users**, also note the pagination parameters the API uses (for example `page`, `pageSize`, `limit`, or `offset`) so you can retrieve users in batches.
:::

## Create a template

1. Sign in to the PBX web portal and go to **Integrations > Helpdesk**.
2. In the helpdesk list, click **Custom**. You are taken to the Template Management page.

   ![The Custom option in the helpdesk list that opens Template Management](/images/pbx/helpdesk-template-entry.png)

3. Click **Add** to start a new template.
4. In the dialog, complete the settings that apply to your helpdesk and your goals:
   - [General settings](#general-settings)
   - [User association](#user-association-optional) (optional)
   - [Authentication method](#authentication-method)
   - [Request headers](#request-headers-optional) (optional)
   - [Follow-up requests](#follow-up-requests-optional) (optional)
   - [Connection keepalive](#connection-keepalive-optional) (optional)
   - [Contact search and call popup](#contact-search-and-call-popup)
   - [New contact creation](#new-contact-creation-optional) (optional)
   - [Call journaling](#call-journaling-optional) (optional)
   - [Chat journaling](#chat-journaling-optional) (optional)
   - [Automatic ticket creation](#automatic-ticket-creation-optional) (optional)
5. Click **Save** to generate the custom helpdesk integration template.

## General settings

In the **General** section, set the template's basic details.

![The General section with logo, name, and concurrency fields](/images/pbx/helpdesk-general-settings.png)

- **Logo**: Upload an icon for the helpdesk. It appears next to the helpdesk in the list on the Integration page.

  :::note
  The logo file must meet these requirements:
  - **Format**: PNG (recommended), JPG, or JPEG
  - **Suggested resolution**: 150 × 150
  - **Size**: under 500 KB
  :::

- **Helpdesk Name**: The display name of the helpdesk.
- **Max Concurrent Request**: The maximum number of simultaneous HTTP requests Cloud Voice may send to the helpdesk.
- **Remark**: Optional. A description shown on the Template Management page.

## User association (optional)

Turn on the **User Association** section to link helpdesk users to Cloud Voice extensions.

:::note
When this is enabled, whoever sets up the integration must pair each helpdesk user with a Cloud Voice extension, as shown below. Only paired extension users can use the helpdesk integration features.

![The user-to-extension pairing shown during integration setup](/images/pbx/custom-user-association-helpdesk.png)
:::

1. Switch on **User Association**.

   ![The User Association toggle](/images/pbx/turn-on-user-association.png)

2. In the **Get User** field, enter the helpdesk API request URL that returns the list of helpdesk users.

   ![The Get User endpoint field](/images/pbx/get-user-endpoint.png)

   :::note
   - The request method defaults to `GET`. To use a different method, edit the template afterward. For the template parameters used here, see [XML Description - User Association Scenario](/pbx/integrations/xml-descriptions-for-integration-template/#crm-integration-template-xml-description__section_m1g_2th_r2c).
   - You can reference values that users enter during [authentication](#authentication-method) as variables in the request.
   :::

   For example:

   ```
   https://www.api.example.com/v1/users?type=ActiveUsers
   ```

3. In the **Pagination Type** list, choose the mode that matches the helpdesk API.

   :::note
   For modes that issue multiple requests, a single synchronization runs at most 100 requests.
   :::

   | Mode | Behavior |
   |------|----------|
   | Disabled | Cloud Voice sends one request with no pagination parameters. Use this when the API returns every record in a single response. |
   | Page Number Pagination | Cloud Voice sends repeated requests keyed on page number and page size, incrementing the page each time until all data is retrieved. |
   | Offset Pagination | Cloud Voice sends repeated requests keyed on a starting offset and record limit, raising the offset by the limit each time until all data is retrieved. |
   | Link Pagination | Cloud Voice follows the "next page" URL returned in each response until no more pages remain. |

   For **Page Number Pagination**, set these parameters:

   ![Page number pagination parameters](/images/pbx/get-user-page.png)

   - **Page Parameter Name**: The parameter that carries the page number in the request.
   - **Page Start Value**: The page number to begin querying from.
   - **Page Size Parameter Name**: The parameter that sets how many records each page returns.
   - **Page Size Value**: The maximum records per page.

   For **Offset Pagination**, set these parameters:

   ![Offset pagination parameters](/images/pbx/get-user-offset.png)

   - **Offset Parameter Name**: The parameter that carries the starting offset.
   - **Offset Value**: How many records to skip before retrieval begins. For example, `1` starts at the first record and `100` starts at the 100th.
   - **Limit Parameter Name**: The parameter that sets how many records each page returns.
   - **Limit Value**: The maximum records per page.

   For **Link Pagination**, enter the JSON path (for example `links.next`) that holds the next-page link in the **Next Page Link Path** field.

   ![Link pagination next-page path](/images/pbx/get-user-link.png)

4. In the **User Field Mapping** section, map helpdesk response fields to the Cloud Voice fields below by giving the JSON path (for example `data.#(key=="value").field`) of each field in the helpdesk response.

   :::tip
   For path syntax, see the [GJSON path syntax reference](https://github.com/tidwall/gjson/blob/master/README.md#path-syntax).
   :::

   | Cloud Voice field | Description |
   |-------------------|-------------|
   | User Unique ID | The user's unique identifier. For example, `users.#.id`. |
   | First Name | The user's first name, shown in the helpdesk user list. For example, `users.#.First_Name`. |
   | Last Name | The user's last name, shown in the helpdesk user list. For example, `users.#.Last_Name`. |
   | Email | The user's email, shown in the user list and usable for automatically pairing helpdesk users with Cloud Voice extensions. For example, `users.#.Email`. |

## Authentication method

In the **Configure Authentication Method** section, pick the method the helpdesk expects.

### None

Use this when the helpdesk needs no authentication, or when it only needs a few values for the integration (such as an API key for requests, or a webhook URL for real-time delivery).

![The None authentication option](/images/pbx/none-auth.png)

1. In the **Authentication Method** list, select **None**.
2. Optional. Click **Add** to create custom fields. Each field appears as an input on the integration page, prompting whoever sets up the integration to supply the value.

   :::note
   - If you add no fields, the helpdesk connects directly with no further input.
   - You can add up to 5 custom fields.
   - Values entered during authentication can be saved as global variables and reused anywhere in the integration.
   :::

   | Setting | Description |
   |---------|-------------|
   | Type | The field type: **Text Input** (plain text), **Password Input** (masked for sensitive values), or **Dropdown List** (a preset list of choices). |
   | Name | The variable name for the field, referenced within the template. |
   | Title | The label shown above the input. |
   | Dropdown Options | For a **Dropdown List** type, the choices to offer. Separate multiple options with commas, for example `option1,option2`. |

### Basic

Requests are authenticated with credentials, such as a username and password or an API key. Every request to the helpdesk carries a header of the form `Authorization: Basic {{.basic_string}}`, where `{{.basic_string}}` is the Base64-encoded credential supplied during integration.

![The Basic authentication settings](/images/pbx/basic-oauth.png)

1. In the **Authentication Method** list, select **Basic**.
2. In the **Credential Type** list, select **Username and Password** or **API Key**, depending on the helpdesk.
3. Configure the fields users fill in for their credentials, adding custom fields if needed.

   :::note
   - You can add up to 5 fields.
   - Values entered during authentication can be saved as global variables and reused anywhere in the integration.
   :::

   | Setting | Description |
   |---------|-------------|
   | Type | The field type: **Text Input**, **Password Input**, or **Dropdown List**. |
   | Name | The variable name for the field. |
   | Title | The label shown above the input. |
   | Dropdown Options | For a **Dropdown List** type, comma-separated choices, for example `option1,option2`. |

4. In the **Base64 Encoded Credential** field, define how the credential variables combine to form the Basic string (`basic_string`). For example, `{{.username}}:{{.password}}` or `{{.api_key}}`.

### OAuth2

Requests are granted access with tokens instead of shared credentials, which the integration obtains through specific API calls to the helpdesk. OAuth2 supports both the **Standard Authorization Code** flow and the **Authorization Code with PKCE** (Proof Key for Code Exchange) flow.

1. Set the method and authorization mode.

   ![Selecting OAuth2 and an authorization mode](/images/pbx/select-oauth2.png)

   a. In the **Authentication Method** list, select **OAuth2**.

   b. In the **Authorization Mode** list, choose the mode:

   | Mode | When to use it |
   |------|----------------|
   | Standard Authorization Code | Requires a `client_secret`. Use it when the helpdesk expects a `client_secret`. |
   | Authorization Code (PKCE) | Makes `client_secret` optional and adds a layer of security. Cloud Voice generates a `code_verifier`, derives a `code_challenge` from it (SHA256 hash, Base64URL encoded), and sends the challenge up front while keeping the verifier locally. At token exchange, it presents the verifier; the authorization server hashes it the same way and compares it to the stored challenge. A match proves the client holds the original verifier, so only that client can exchange the code for a token, which blocks interception attacks. |

2. Configure the fields users fill in for their credentials.

   ![OAuth2 credential input fields](/images/pbx/oauth2-input.png)

   :::note
   - You can add up to 10 fields. If you need more, add custom fields by editing the template afterward; for the parameters involved, see [XML Description - Authentication Scenario](/pbx/integrations/xml-descriptions-for-integration-template/#crm-integration-template-xml-description__section_lvt_dth_r2c).
   - Values entered during authentication can be saved as global variables and reused anywhere in the integration.
   :::

   | Setting | Description |
   |---------|-------------|
   | Type | The field type: **Text Input**, **Password Input**, or **Dropdown List**. |
   | Name | The variable name for the field. |
   | Title | The label shown above the input. |
   | Dropdown Options | For a **Dropdown List** type, comma-separated choices, for example `option1,option2`. |
   | Required | Whether the field is mandatory: **Yes** (required) or **No** (may be left blank). |

3. Configure the OAuth2 authorization settings.

   ![OAuth2 authorization endpoint settings](/images/pbx/oauth2-token-setting.png)

   | Setting | Description |
   |---------|-------------|
   | Authorization Endpoint | The helpdesk authorization URL users are redirected to during integration. For example, `https://www.api.example.com/auth/v2/authorize?client_id={{.client_id}}`. |
   | Token Endpoint | The helpdesk API URL that issues the 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 | The content type of the token request. |
   | PKCE Verification Method | How to turn the `code_verifier` into the `code_challenge`. Available only when **Authorization Mode** is **Authorization Code (PKCE)**. Choose **S256** (SHA256 hash, Base64URL encoded, recommended) or **Plain** (use the verifier directly, for systems without SHA256 support). |
   | Scope | Optional. The scope that limits what data Cloud Voice may access. Separate multiple values with commas, for example `contacts.read,contacts.write,calls.read,calls.write,user.read,user.write`. |
   | Additional Query String | Optional. If the helpdesk authenticates with query parameters rather than a scope, add them here, for example `client_id={{.client_id}}&redirect_uri={{.redirect_uri}}`. |

4. Optional. Configure token refresh.

   ![OAuth2 token refresh settings](/images/pbx/oauth2-token-refresh-setting.png)

   | Setting | Description |
   |---------|-------------|
   | Token Refresh Request Method | The HTTP method for the token refresh API. |
   | Token Refresh Endpoint | The API URL that refreshes the access token. |
   | Token Refresh Content Type | The content type of the refresh request. |
   | Token Refresh Time (min) | How often, in minutes, to refresh the access token automatically. Set to `0` to disable automatic refresh; leave blank to refresh every 25 minutes by default. |
   | Token Refresh Request Body | The request body for the refresh API. |

   :::caution
   Setting **Token Refresh Time** to `0` stops Cloud Voice from refreshing the access token. Once that token expires, requests to the helpdesk fail and the integration stops working, so use `0` only when the helpdesk issues tokens that never expire.
   :::

### Bearer Token

Requests are authenticated with a bearer token, usually obtained through an authorization process such as OAuth2. Every request to the helpdesk carries a header of the form `Authorization: Bearer {{.AccessToken}}`, where `{{.AccessToken}}` is the token the helpdesk grants.

1. In the **Authentication Method** list, select **Bearer Token**.

   ![Selecting Bearer Token authentication](/images/pbx/select-bear.png)

2. Configure the fields users fill in for their credentials, adding custom fields if needed.

   ![Bearer token credential input fields](/images/pbx/bear-input-setting.png)

   :::note
   - You can add up to 10 fields.
   - Values entered during authentication can be saved as global variables and reused anywhere in the integration.
   :::

   | Setting | Description |
   |---------|-------------|
   | Type | The field type: **Text Input**, **Password Input**, or **Dropdown List**. |
   | Name | The variable name for the field. |
   | Title | The label shown above the input. |
   | Dropdown Options | For a **Dropdown List** type, comma-separated choices, for example `option1,option2`. |

3. Configure token retrieval to match the API specification.

   ![Bearer token retrieval settings](/images/pbx/bear-token-setting.png)

   | Setting | Description |
   |---------|-------------|
   | Token Endpoint | The helpdesk API URL that requests 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 returned token is stored in the `{{.AccessToken}}` variable. |
   | Content Type | The content type of the token request. |

4. Optional. Configure token refresh.

   ![Bearer token refresh settings](/images/pbx/oauth2-token-refresh-setting.png)

   | Setting | Description |
   |---------|-------------|
   | Token Refresh Request Method | The HTTP method for the token refresh API. |
   | Token Refresh Endpoint | The API URL that refreshes the access token. |
   | Token Refresh Content Type | The content type of the refresh request. |
   | Token Refresh Time (min) | How often, in minutes, to refresh the access token automatically. Set to `0` to disable automatic refresh; leave blank to refresh every 25 minutes by default. |
   | Token Refresh Request Body | The request body for the refresh API. |

## Request headers (optional)

Add custom HTTP headers that ride along with the built-in synchronization requests (user association, contact sync, and so on).

:::note
- You can add up to 20 custom headers.
- These headers are not applied to authentication requests (such as obtaining or refreshing a token) or to custom-configured requests.
- Don't define an `Authorization` header here, it would override the one set by your authentication method (Basic, OAuth2, or Bearer Token).
:::

![Adding custom request headers](/images/pbx/custom-crm-header.png)

1. In the **Headers** section, click **Add**.
2. Configure the header:

   | Setting | Description |
   |---------|-------------|
   | Name | The header name, such as `Content-Type` or `Accept`. |
   | Value | The header value, a fixed value or a variable. Variables from the authentication method work here too; for example, reference a `client_id` variable as `{{.client_id}}`. |
   | Description | A short note on what the header is for. |

## Follow-up requests (optional)

If your integration needs extra operations after certain built-in requests finish, define follow-up requests. Each one fires automatically when its trigger operation succeeds, and you can extract data from its response into global variables for reuse elsewhere.

:::note
You can add up to 10 follow-up requests.
:::

![Configuring a follow-up request](/images/pbx/followup-requests.png)

1. In **Request Configuration > Follow-up Requests**, click **Add**.
2. Configure the request:

   | Setting | Description |
   |---------|-------------|
   | Triggered Event | The built-in system event that fires this request. |
   | Request Method | The HTTP method for the request. |
   | URL | The endpoint for the follow-up operation, for example `https://api.example.com/rest-services/login`. |
   | Headers | The request headers as a JSON object. Insert dynamic values with `{{.varname}}`, for example `{"Content-Type":"application/json", "X-Custom-Header": "{{.DynamicValue}}"}`. |
   | Request Body | The payload as a JSON object, again using `{{.varname}}` for dynamic values, for example `{"lastName":"{{.LastName}}","ownerId":"{{.Id}}","phone":"{{.BusinessNumber}}"}`. |
   | Response Field Path | The JSON path(s) that extract data from the response. Separate multiple paths with commas, for example `.data.access_token, .tokens[0].value`. |
   | Target Variable Name | The variable(s) that store the extracted values, existing or new. Separate multiple names with commas, for example `token,refresh`. Values are assigned in the same order as the paths in **Response Field Path**. The stored values become global variables reusable across the integration. |

## Connection keepalive (optional)

Keep the connection alive so it isn't dropped after a network timeout or a period of inactivity. When enabled, Cloud Voice sends keep-alive requests to the helpdesk at a set interval to check connection status and authentication validity.

![Connection keepalive settings](/images/pbx/connection-keepalive.png)

1. Switch on **Connection Keepalive**.
2. In the **Keepalive Interval (minutes)** field, set how often to send the keep-alive request.

## Contact search and call popup

In the **Synchronize Contacts Automatically** section, define the contact types users can choose from and the requests that search for them. These settings power contact lookup, automatic contact synchronization, and call popup.

1. Add a contact type and its search request.

   ![Adding a contact type and search request](/images/pbx/add-helpdesk-contacts.png)

   - **Contact Type**: A name for the type, for example `Contacts`. This name appears as an automatic-sync option when users set up the integration.
   - **Contact Match Query URL**: The helpdesk API URL that searches contacts by criteria. You can use these variables in the criteria:
     - Variables from user input during [authentication](#authentication-method).
     - [Target variables](#follow-up-requests-optional) extracted from follow-up responses.
     - `{{.Phone}}`: the number tied to the inbound or outbound call, or the number a user types when 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. Set the call popup URL using one of these methods.

   **Specify URL Format**

   Build the popup URL from a format string, using variables to fill it in dynamically.

   ![Specifying the call popup URL format](/images/pbx/specify-url-format-helpdesk.png)

   a. In the **Contact Popup URL** list, select **Specify URL Format**.

   b. In the **URL Format** field, enter the URL expression. You can use these variables, whose values come from the contact search results:
   - Variables from user input during [authentication](#authentication-method).
   - [Target variables](#follow-up-requests-optional) extracted from follow-up responses.
   - `{{.ContactSyncType}}`: the contact type.
   - `{{.ContactId}}`: the contact ID.
   - `{{.CustomValue}}`: a custom field mapped in the **Contact Field Mapping** section.

     :::note
     If these variables aren't enough, edit the template later to define more custom variables and retrieve their values. See [XML Description - Retrieve Additional Variables](/pbx/integrations/xml-descriptions-for-integration-template/#crm-integration-template-xml-description__global).
     :::

     For example:

     ```
     {{.doman_url}}{{.CustomValue}}/tab/{{Capitalize .ContactSyncType}}/{{.ContactId}}
     ```

   **Retrieve from Contact Fields**

   Pull the popup URL straight from a field in the contact search response.

   ![Retrieving the call popup URL from a contact field](/images/pbx/retrieve-url-from-fields.png)

   a. In the **Contact Popup URL** list, select **Retrieve from Contact Fields**.

   b. In the **Contact Field for URL** field, enter the JSON path of the field in the response, for example `data.#.contactUrl`.

3. In the **Contact Field Mapping** section, map helpdesk response fields to Cloud Voice fields by giving each field's JSON path (for example `data.#(key=="value").field`).

   :::note
   - Mapped values retrieved from a call are stored as variables and can be referenced across modules until the call ends.
   - To retrieve more than one variable for a field, separate them with commas. This applies only to phone number fields, for example `data.#(phone=="{{.Phone}}")#.phone,data.#(mobile=="{{.Phone}}")#.mobile`.
   :::

   a. Map the required fields:

   ![Mapping required contact fields](/images/pbx/required-pbx-field.png)

   - **Contact ID**: The ID of the matched contact, for example `data.0.id`.
   - **First Name**: The first name of the matched contact, for example `data.0.First_Name`.

   b. Enable and map any optional Cloud Voice fields you need.

   :::note
   You must enable and map at least one phone number.
   :::

   ![Mapping optional contact fields](/images/pbx/optional-mapping-contact-field.png)

   c. If the built-in Cloud Voice fields don't cover a value you need, enable and map the response field to **Custom Value**, then reference it as `{{.CustomValue}}`.

   :::note
   `{{.CustomValue}}` is meant for building the contact popup URL and does not appear in Cloud Voice contact details.
   :::

   ![The Custom Value field mapping](/images/pbx/custom-value.png)

## New contact creation (optional)

To add a new contact to the helpdesk when a caller's number matches no existing contact, enable **Create New Contact**.

![Automatic helpdesk contact creation settings](/images/pbx/auto-create-helpdesk-contact.png)

1. Switch on **Create New Contact**.
2. Add the contact types users can choose when configuring the integration:
   - **Contact Type**: The type of contact, for example `Contacts`.
   - **Contact Creation URL (POST)**: The helpdesk API URL that creates a contact, for example `https://www.api.example.com/v1/Contacts`.
   - **Contact Creation Request Body**: The JSON body carrying the contact details. You can use:
     - Variables from user input during [authentication](#authentication-method).
     - [Target variables](#follow-up-requests-optional) extracted from follow-up responses.
     - `{{.LastName}}`: required. The contact's last name.
     - `{{.FirstName}}`: required. The contact's first name.
     - `{{.BusinessNumber}}`: required. The contact's phone number.

     :::note
     If these variables aren't enough, edit the template later to define more custom variables and retrieve their values. See [XML Description - Retrieve Additional Variables](/pbx/integrations/xml-descriptions-for-integration-template/#crm-integration-template-xml-description__global).
     :::

     For example:

     ```json
     {
       "data": [
         {
           "Last_Name": "{{.LastName}}",
           "First_Name": "{{.FirstName}}",
           "Phone": "{{.BusinessNumber}}"
         }
       ]
     }
     ```

## Call journaling (optional)

To log call activity and details in the helpdesk automatically, enable **Call Journal**.

![Call journal settings](/images/pbx/set-call-journal-helpdesk.png)

1. Switch on **Call Journal**.
2. Configure the request and body for journaling.

   a. Configure the request that creates a new call log:
   - **Create Call Journal URL**: The helpdesk API URL that creates a call log, for example `https://www.api.example.com/v2/Calls`.
   - **Create Call Log Request Method**: **POST** or **PUT**.
   - **Call Journal Creation Request Body**: The JSON body carrying the call details.

     :::note
     For the variables you can use in the body, see [XML Description - Call Journal Variables](/pbx/integrations/xml-descriptions-for-integration-template/#crm-integration-template-xml-description__var-2).
     :::

     For example:

     ```json
     {
       "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}}"
           }
         }
       ]
     }
     ```

   b. Optional. Configure the request that updates an existing call log with extra information:
   - **Update Call Journal URL**: The helpdesk API URL that updates a call log, for example `https://www.api.example.com/v2/Calls/{{.CallId}}`.
   - **Update Call Log Request Method**: **POST** or **PUT**.
   - **Call Journal Update Request Body**: The JSON body carrying the call details.

     :::note
     For the variables you can use in the body, see [XML Description - Call Journal Variables](/pbx/integrations/xml-descriptions-for-integration-template/#crm-integration-template-xml-description__var-2).
     :::

     For example:

     ```json
     {
       "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}}",
             "AI_Transcription": "{{.AI_Transcription}}",
             "AI_Summary": "{{.AI_Summary}}",
             "Call_Note": "{{.Call_Note}}"
           }
         }
       ]
     }
     ```

3. Optional. Choose which call journaling settings are available in the integration by selecting their checkboxes, and set default values.

   :::note
   The values set in these fields can also be captured as variables if needed. For the supported variables, see [XML Description - Call Journal Variables](/pbx/integrations/xml-descriptions-for-integration-template/#crm-integration-template-xml-description__var-2).
   :::

   | Option | Description |
   |--------|-------------|
   | Subject | Makes a subject setting available in the integration, used to set a default subject for all synced call logs. |
   | Description | Makes a description setting available, used to detail synced call logs, for example `Call: {{.Time}} {{.Call_Log_Status}} from {{.Call_From}} to {{.Call_To}} {{.Talk_Duration}}`. |
   | Play Call Recording | Makes a setting available that controls whether call recordings can be played back inside the helpdesk. |
   | Disable Display Missed Call Records in Unanswered Agents | Makes a setting available that controls whether queue and ring group call logs sync only to the helpdesk of the agent who answered, while missed-call logs for the same call are not synced to agents who didn't answer. |

## Chat journaling (optional)

To sync chat conversations with helpdesk contacts into the helpdesk automatically, enable **Chat Journal**.

![Chat journal settings](/images/pbx/template-chat-journal.png)

1. Switch on **Chat Journal**.
2. Configure the request and body for journaling.
   - **Create Chat Journal URL (POST)**: The helpdesk API URL that creates an object to store chat messages, for example `https://www.api.example.com/v2/Tasks`.
   - **Chat Journal Creation Request Body**: The JSON body carrying the chat details.

     :::note
     For the variables you can use in the body, see [XML Description - Chat Journal Variables](/pbx/integrations/xml-descriptions-for-integration-template/#crm-integration-template-xml-description__var-chat-journal).
     :::

     For example:

     ```json
     {
       "data": [
         {
           "Owner": {
             "id": "{{.OwnerId}}"
           },
           "Who_Id": "{{.ContactEntityId}}",
           "Subject": "{{.Subject}}",
           "Due_Date": "{{ TimeFormat .StartTimeUnix "yyyy-MM-dd" "0" }}",
           "Closed_Time": "{{ TimeFormat .EndTimeUnix "yyyy-MM-ddTHH:mm:ss.000Zz" "0" }}",
           "Status": "Completed",
           "Priority": "Normal",
           "Description": "Message Channel Type: {{.Channel_Display}}\n\n{{.Messages}}"
         }
       ]
     }
     ```

3. Optional. In the **Subject** section, decide whether users may customize the subject of the synced record.

   a. Select the checkbox to make the **Subject** field available in the integration, used to set a default subject for all synced records.

   b. Set the default value for the **Subject** field.

   :::note
   The value set here can also be captured as a variable if needed. For the supported variables, see [XML Description - Chat Journal Variables](/pbx/integrations/xml-descriptions-for-integration-template/#crm-integration-template-xml-description__var-chat-journal).
   :::

## Automatic ticket creation (optional)

To open a new helpdesk ticket automatically from a call, enable **Create New Ticket Automatically**.

:::caution
If you later set the feature to create the ticket before the call connects (that is, when the phone rings), the ticket may be missing some information. In that case, edit the template to fill in the ticket details. See [XML Description - Extended Configurations](/pbx/integrations/xml-descriptions-for-integration-template/#crm-integration-template-xml-description__ticket-id-retrieve).
:::

![Automatic ticket creation settings](/images/pbx/set-ticket-creation-helpdesk.png)

1. Switch on **Create New Ticket Automatically**.
2. Configure the request and body for ticket creation.
   - **Create New Ticket URL (POST)**: The helpdesk API URL that creates a ticket, for example `https://www.api.example.com/api/v1/tickets`.
   - **New Ticket Creation Request Body**: The JSON body carrying the ticket details.

     :::note
     For the variables you can use in the body, see [XML Description - New Ticket Creation Variables](/pbx/integrations/xml-descriptions-for-integration-template/#crm-integration-template-xml-description__variable).
     :::

     For example:

     ```json
     {
        "subject":"{{.Subject}}",
        "contactId":"{{.ContactId}}",
        "phone":"{{.ContactNumber}}",
        "description":"{{.Description}}"
     }
     ```

3. To let users customize the subject and description of the new ticket, enable the options below and set their defaults.

   :::note
   The values set in these fields can also be captured as variables if needed. For the supported variables, see [XML Description - New Ticket Creation Variables](/pbx/integrations/xml-descriptions-for-integration-template/#crm-integration-template-xml-description__variable).
   :::

   - **Subject**: If enabled, enter a default subject, for example `{{.Communication_Type}} {{.Call_Status}} - from {{.Call_From}} to {{.Call_To}}`.
   - **Description**: If enabled, enter default details, for example `{{.Time}} {{.Communication_Type}} {{.Call_Status}} - from {{.Call_From}} to {{.Call_To}} {{.Talk_Duration}}`.