# Integrate a Helpdesk Using a Template

When the helpdesk your team uses isn't among the built-in integrations, you can still connect it to Cloud Voice through a custom Helpdesk integration template. This page walks you through completing that connection.

:::note
Connecting a helpdesk lets Cloud Voice and the helpdesk exchange and synchronize data through an API (Application Programming Interface: a defined way for two systems to talk to each other). Build the link from a template only when your helpdesk is not already offered as a ready-made integration.
:::

## Before you begin

Make sure the following are in place:

- You have [added a Helpdesk integration template](/pbx/integrations/custom-helpdesk-integration/add-a-helpdesk-integration-template/).
- You have gathered the authorization information your helpdesk requires. What you need to collect depends on the helpdesk's authentication method:

| Authentication method | What to obtain |
| --- | --- |
| None | Any integration details the helpdesk expects, such as an API (Application Programming Interface) key or a webhook URL (Uniform Resource Locator: the web address the helpdesk sends data to). |
| Basic | The credentials used to sign in, for example a username and password, or an API key. |
| OAuth2 (Open Authorization, version 2) | Register an application in your helpdesk (see below), then note the client ID and client secret it returns. |
| Bearer Token | The client ID and client secret used for authentication. |

For OAuth2, open the phone system's authentication details first, at **Integrations > Helpdesk > Custom Helpdesk**. Use those details to create an application in your helpdesk, which then gives you the client ID and client secret.

:::caution
Follow this order for OAuth2. Collect the Cloud Voice authentication details before you register the application in your helpdesk. The helpdesk needs those details to create the application, and only then does it hand back the client ID and client secret you enter into Cloud Voice. Creating the application first leaves you without the values needed to finish the setup.
:::

![Cloud Voice, phone system authentication details used to register an OAuth2 application in the helpdesk](/images/pbx/custom-oauth-integrate-hp.png)

## Set up the integration

1. Sign in to the Cloud Voice portal and go to **Integrations > Helpdesk**.
2. In the helpdesk list, select the helpdesk you added from a template.

   ![Helpdesk list showing an entry added from a custom template](/images/pbx/click-to-integrate-custom-hp.png)
3. Authenticate the connection using the method your helpdesk requires.

   **None authentication**

   ![Settings section for a helpdesk that requires no authentication](/images/pbx/custom-crm-none-auth.png)

   a. In the **Settings** section, enter the details needed for the integration.

   b. Click **Save**.

   :::note
   If no extra information is needed, the integration completes the moment you select the helpdesk.
   :::

   **Basic authentication**

   ![Credential fields for a helpdesk that uses basic authentication](/images/pbx/custom-crm-basic-auth.png)

   a. In the **Settings** section, enter the required credentials.

   b. Click **Save**.

   **OAuth2 authentication**

   
   ![Cloud Voice, authorization fields for connecting a helpdesk with OAuth2](/images/pbx/custom-hp-oauth-auth.png)

   a. In the **Authorization** section, enter the authorization details from the application you created in the helpdesk.

   b. Click **Save**. A new browser tab opens and asks for permission to access your helpdesk data.

   :::tip
   If the new tab does not appear, check that your browser is not blocking pop-ups for the Cloud Voice portal, then click **Save** again.
   :::

   c. Approve the request so Cloud Voice can reach the data in your helpdesk account. Back on the configuration page, a pop-up reports the result.

   ![Pop-up confirming the helpdesk authentication succeeded](/images/pbx/hp-success.png)

   d. Click **OK**. When the **Status** field reads **Connected**, the helpdesk integration is in place.

   **Bearer Token authentication**

   ![Credential fields for a helpdesk that uses bearer token authentication](/images/pbx/custom-crm-bearer-auth.png)

   a. In the **Settings** section, enter the required credentials.

   b. Click **Save**.
4. Associate helpdesk users with extensions.

   If your helpdesk requires its users to be linked to extensions before the integration features work, complete these steps:

   a. On the helpdesk integration page, click ![refresh](/images/pbx/refresh-firefox.png) to pull in the current list of helpdesk users.

   ![Synchronized list of helpdesk users on the integration page](/images/pbx/custom-hp-user-list.png)

   :::note
   Syncing fetches the latest users from your helpdesk. Run it again whenever people are added to or removed from the helpdesk so the list here stays current.
   :::

   b. Link the helpdesk users to extensions using one of the following methods.

   **Associate automatically**

   When users sign in to both their helpdesk account and their extension with the same email address, you can match them all in one step:

   ![Associate Automatically option for matching helpdesk users to extensions by email](/images/pbx/auto-association-custom-hp.png)

   i. Click **Associate Automatically**.

   ii. In the pop-up window, click **OK**.

   :::tip
   Automatic matching relies on the email address being identical in both systems. Any user whose helpdesk email does not match an extension email is left unlinked, so link those users by hand with the manual method below.
   :::

   **Associate manually**

   When a user's helpdesk email differs from the email on their extension, link the two by hand:

   
   ![Cloud Voice, manually linking a helpdesk user to an extension](/images/pbx/custom-hp-manually-association.png)

   i. In the **Extension** field beside the helpdesk user, click ![edit](/images/pbx/edit.png).

   ii. In the pop-up window, select the extension(s) for that user.

   iii. Click **Confirm**.

   c. Click **Save**.