# Set up Helpdesk Integration Features

Once Cloud Voice is connected to your custom Helpdesk, you decide which capabilities to switch on and how call and contact data moves between the two systems. Each feature below is configured independently, so enable only the ones your team needs.

:::note
These steps assume you have already [connected Cloud Voice to your custom Helpdesk with an integration template](/pbx/integrations/custom-helpdesk-integration/integrate-cloud-voice-cloud-voice-with-a-helpdesk-using-template/).
:::

## Synchronize contacts

With contact synchronization on, every inbound and outbound call prompts a lookup in the Helpdesk. When a matching number is found, the corresponding contact is copied into the linked Cloud Voice phonebook. Synchronized contacts are read-only inside Cloud Voice.

1. In the management portal, go to **Integrations > Helpdesk**.
2. In the **Synchronize Contacts Automatically** section, turn on the switch.
3. From the **Synchronize Contacts From** drop-down list, choose which contact type or types should be pulled in from the Helpdesk.

   ![Drop-down list for choosing which Helpdesk contact types to synchronize](/images/pbx/sync-contacts-type.png)
4. From the **Synchronize to Phonebook** drop-down list, pick an existing empty phonebook or create a new one to hold the incoming contacts.

   :::note
   Contacts can only be synchronized into an empty phonebook.
   :::

   ![Creating a new phonebook to receive synchronized Helpdesk contacts](/images/pbx/create-new-phonebook-for-hp.png)
5. Use the **Always Query Helpdesk** option to decide whether Cloud Voice searches the Helpdesk in real time.

   
   ![Cloud Voice, Always Query Helpdesk toggle in the contact synchronization settings](/images/pbx/always-query-helpdesk.png)

   - **Enabled**: Cloud Voice queries the Helpdesk in real time and lets associated extension users search Helpdesk contacts as they dial from the Cloud Voice App.
   - **Disabled**: Cloud Voice only reaches out to the Helpdesk when no match is found in the company contacts.

   :::caution
   Real-time queries add to your API usage (API is the connection Cloud Voice uses to send automated requests to the Helpdesk), so keep an eye on your quota. Real-time search is also unavailable while masked number is turned on.
   :::
6. Click **Save**.

## Create contacts

When this feature is on, a new contact can be added to the Helpdesk, either automatically or by the agent, whenever an associated extension calls or is called by an unknown number.

1. In the management portal, go to **Integrations > Helpdesk**.
2. In the **Create New Contact** section, turn on the switch.
3. From the **Create Contact or Lead** drop-down list, choose the type of record to create.

   ![Selecting whether an unknown number becomes a contact or a lead](/images/pbx/auto-create-contact-integration-features.png)
4. In the **Create Method** section, choose how records are added:

   - **Automatically**: to have Cloud Voice create the record on its own for specific call types:
   1. Select **Automatically**.
   2. From the **Call Type** drop-down list, choose when a contact is created automatically.

        ![Choosing inbound or outbound calls as the trigger for automatic contact creation](/images/pbx/select-in-or-out-to-create-new-contact.png)

        - **Inbound**: an inbound call from an unknown number that does not match an existing Helpdesk contact.
        - **Outbound**: an outbound call to an unknown number that does not match an existing Helpdesk contact.
   - **Manually**: to let agents add the record themselves during a call. Select **Manually**; when an agent is on a call with an unknown number, they can save it to the Helpdesk straight from the call window.

     ![Adding an unknown caller to the Helpdesk from the call window](/images/pbx/manually-create-hp-contact.png)
5. Click **Save**.

## Show a contact pop-up during calls

Call pop-ups are configured per extension. When set up, an agent's Cloud Voice App web or desktop client can open the contact's profile automatically at a chosen point in the call, or let the agent open it on demand from the call window.

1. In the management portal, go to **Extension and Trunk > Extension**.
2. Click ![Edit](/images/pbx/edit.png) next to the extension tied to the Helpdesk user.
3. On the **Cloud Voice App** tab, scroll to the client you want and select the **Open Contact URL Using System-Integrated Helpdesk** checkbox.
4. In the **Popup Method** section, choose how the pop-up behaves:

   - **Automatically**: to have the Helpdesk profile open on its own:
   1. Select **Automatically (Only for Incoming Calls)**.
   2. From the **Trigger Event** drop-down list, set the moment the pop-up appears.

        ![Choosing the call event that triggers the automatic contact pop-up](/images/pbx/call-popup-event.png)

        - **Ringing**: the pop-up opens when an inbound call from a Helpdesk contact starts ringing.
        - **Answered**: the pop-up opens when the agent answers an inbound call from a Helpdesk contact.
        - **Call End**: the pop-up opens once the call with the Helpdesk contact ends.
   - **Manually**: to let the agent open the profile on demand. Select **Manually**; during a call with a Helpdesk contact, the agent can open the contact URL from the call window.

     ![Opening a Helpdesk contact URL manually from the call window](/images/pbx/manually-open-call-popup-hp.png)
5. Click **Save**.

## Log calls to the Helpdesk

Call journaling records every outbound, inbound, and missed call in the Helpdesk automatically, giving agents a running history of each conversation.

1. In the management portal, go to **Integrations > Helpdesk**.
2. In the **Call Journal** section, turn on the switch.
3. Set the content of each log entry.

   ![Fields for the subject and description of a synced call log](/images/pbx/call-log-content.png)

   - **Subject**: the title of the call log.
   - **Description**: the body of the call log.

   :::note
   You can build these fields from variables. See the [XML description of supported variables](/pbx/integrations/xml-descriptions-for-integration-template/#crm-integration-template-xml-description__var-2).
   :::
4. Adjust the following options as needed.

   | Setting | Description |
   | --- | --- |
   | Play Call Recording | When on, Helpdesk users linked to Cloud Voice extensions can view and play call recordings stored on Cloud Voice from inside the Helpdesk. |
   | Disable Display Missed Call Records in Unanswered Agents | When on, for queue and ring group calls only the agent who answers gets the log in their Helpdesk; the matching missed-call entry is not synced to agents who did not answer. |

   :::note
   When a Helpdesk user plays a recording, the Helpdesk requests the file from Cloud Voice. For how your Helpdesk protects recording data, check with the Helpdesk provider.
   :::
5. Click **Save**.

## Log chat sessions to the Helpdesk

With chat journaling on, once an external chat session between an extension user and a Helpdesk contact closes, whether the agent or the system ends it, every message from that session is synced to the Helpdesk, preserving the full history of the interaction.

1. In the management portal, go to **Integrations > Helpdesk**.
2. On the Helpdesk integration page, turn on **Chat Journal**.
3. In the **Subject** field, set the title used for the synced record.

   ![Setting the subject for a synced chat session record](/images/pbx/chat-journal.png)

   :::note
   You can build the subject from variables. See the [XML description of chat journal scenario variables](/pbx/integrations/xml-descriptions-for-integration-template/#crm-integration-template-xml-description__var-chat-journal).
   :::
4. Click **Save**.

## Create tickets automatically

You can turn inbound and outbound calls with Helpdesk contacts into support tickets automatically.

1. In the management portal, go to **Integrations > Helpdesk**.
2. On the Helpdesk integration page, turn on **Create New Ticket Automatically**.
3. Choose when tickets are raised and for which call types.

   | When to Create New Ticket | Description |
   | --- | --- |
   | **Before the Call** | A ticket is raised as soon as the agent receives an inbound call from, or places an outbound call to, a Helpdesk contact. In the **The Type of Call to Create Ticket** drop-down list, select the call types: **Inbound** or **Outbound**. |
   | **After the Call** | A ticket is raised once the agent ends the call with a Helpdesk contact. In the **The Type of Call to Create Ticket** drop-down list, select the call types: **Inbound Answered**, **Inbound No Answer**, **Outbound Answered**, or **Outbound No Answer**. |
4. Set the content of the ticket.

   ![Fields for the subject and description of an automatically created ticket](/images/pbx/ticket-info.png)

   - **Subject**: the title of the ticket.
   - **Description**: the body of the ticket.

   :::note
   You can build these fields from variables. See the [XML description of supported variables](/pbx/integrations/xml-descriptions-for-integration-template/#crm-integration-template-xml-description__variable).
   :::
5. Click **Save**.