# Integrate Cloud Voice with IZT Cloud Fax

Linking Cloud Voice to IZT Cloud Fax gives your team secure, Internet-based faxing. Once the integration is in place, extension users send and receive faxes straight from the Cloud Voice App on their desktop or in the browser, with delivery handled over IZT Cloud's communications network.

## How the integration works

The connection relies on two pieces working together: the Cloud Voice **Webhook** (a URL that IZT Cloud automatically calls to notify Cloud Voice when something happens, such as a fax arriving) and the **IZT Cloud Fax API** (Application Programming Interface: the set of endpoints Cloud Voice calls to submit and retrieve faxes).

![Cloud Voice, overview of fax traffic flowing between Cloud Voice and IZT Cloud Fax](/images/pbx/izt-fax-integration.png)

- **Outbound.** When an extension user sends a fax from the Cloud Voice App, Cloud Voice calls the IZT Cloud API to hand the fax off for delivery.

  
  ![Cloud Voice, outbound fax path from the app through Cloud Voice to IZT Cloud](/images/pbx/izt-send-fax.png)

- **Inbound.** When a fax reaches your IZT Cloud fax number, IZT Cloud posts a webhook notification back to Cloud Voice. Cloud Voice then pulls the fax file through the API and routes it to the extension users you designated.

  
  ![Cloud Voice, inbound fax path from IZT Cloud back to the designated extensions](/images/pbx/izt-receive-fax.png)

Setting this up comes down to three stages:

1. Copy a Webhook URL out of Cloud Voice.
2. In IZT Cloud, create the resources you'll need and collect their credentials:
   - A **fax-enabled phone number** for sending and receiving.
   - An **API key** that authenticates your account against the IZT Cloud API.
   - A **notification group** that carries the webhook notifications.
3. Enter those credentials back in Cloud Voice and finish the fax settings.

## Requirements

Before you begin, confirm your Cloud Voice system meets both of these:

- **Firmware**: version 84.20.0.74 or later.
- **Plan**: Enterprise or Ultimate.

## Before you start

Purchase one or more fax numbers from IZT Cloud.

## Step 1. Copy the Webhook URL from Cloud Voice

You'll need this URL later, when you build the notification group in IZT Cloud, so grab it first.

1. Open the fax integration screen.

   
   ![Cloud Voice, the Fax integration screen with the Add button](/images/pbx/fax-integration-page.png)

   a. Sign in to the Cloud Voice admin portal and go to **Integrations > Fax**.

   b. On the **Fax Integration** tab, click **Add**.

2. Retrieve the Webhook URL for IZT Cloud Fax.

   
   ![Cloud Voice, the Service Provider list and the Webhook URL field](/images/pbx/izt-webhook-url-pce.png)

   a. In the **Service Provider** list, choose **IZT Cloud Fax**.

   b. In the **Webhook URL** field, click the copy icon ![copy icon](/images/pbx/copy.png) and keep the URL somewhere handy for the next step.

## Step 2. Create resources and collect credentials in IZT Cloud

These tasks all happen in the IZT Cloud portal and produce the credentials Cloud Voice uses to authenticate:

1. Create an API key.
2. Create a notification group.
3. Attach the notification group to your fax number.

### 1. Create an API key

1. Open the API key page.

   ![The API Keys settings page with the Manage API Keys button](/images/pbx/izt-manage-api-key.png)

   a. Sign in to the [IZT Cloud Fax portal](https://portal.fax.izt.cloud/).

   b. Go to **Settings > API Keys**, then click **Manage API Keys**.

2. Generate the key.

   a. In the top-right corner, click **Generate New Key**.

   ![The Generate New Key button on the API key management page](/images/pbx/izt-generate-api-key.png)

   b. In the **API Key Name** field, type a name you'll recognize, then click **Generate API Key**.

   ![Naming the new API key before generating it](/images/pbx/izt-set-api-key.png)

   The key is created and shown on screen.

   c. Copy the key and store it for later, then click **I've Saved the Key** to dismiss the window.

   ![The generated API key with a copy control and confirmation button](/images/pbx/izt-copy-api-key.png)

   :::caution
   The full key is displayed only once. If you close the window without copying it, you'll have to generate a new one.
   :::

### 2. Create a notification group

1. Open the notification group page.

   ![The Notifications area with the Create Group button](/images/pbx/izt-create-group.png)

   a. In the left navigation bar, click **Notifications**.

   b. In the top-right corner, click **Create Group**.

2. Fill in the group and click **Create Group**.

   
   ![Cloud Voice, the notification group form with a webhook entry](/images/pbx/izt-group-pce.png)

   | Setting | What to enter |
   | --- | --- |
   | Group Name | A name that helps you identify the group. |
   | Email Notifications | Leave as-is or adjust to suit your needs. |
   | User Notifications | Leave as-is or adjust to suit your needs. |
   | Webhooks | Click **Add Webhook** and paste the Webhook URL you copied from Cloud Voice in Step 1. |

   :::note
   Set the webhook **Method** to **POST**.
   :::

### 3. Attach the notification group to your fax number

1. Open the fax number's settings.

   a. In the left navigation bar, click **Numbers**, then click **View** next to the number you want.

   ![The Numbers list with a View action beside each number](/images/pbx/izt-view-number.png)

   b. In the side panel, click **Edit Number Settings**.

   ![The number's side panel with the Edit Number Settings button](/images/pbx/izt-edit-number.png)

2. In the **Notification Group** list, select the group you just created, then click **Save Changes**.

   ![Selecting the notification group for the fax number](/images/pbx/izt-select-group.png)

## Step 3. Enter the credentials and configure fax settings in Cloud Voice

Back in Cloud Voice, supply the credentials you gathered from IZT Cloud and finish the fax options.

1. Open the fax integration screen.

   
   ![Cloud Voice, the Fax integration screen with the Add button](/images/pbx/fax-integration-page.png)

   a. Sign in to the Cloud Voice admin portal and go to **Integrations > Fax**.

   b. On the **Fax Integration** tab, click **Add**.

2. In the **Authorization** section, complete the fields.

   
   ![Cloud Voice, the Authorization section of the fax integration form](/images/pbx/izt-auth-pce.png)

   | Setting | What to enter |
   | --- | --- |
   | Name | A label that helps you identify this integration. |
   | Service Provider | Select **IZT Cloud Fax**. |
   | API Key | Paste the API key you created in IZT Cloud. |

3. **Optional.** To also deliver inbound faxes as email attachments, set up one or more email destinations.

   
   ![Cloud Voice, the fax-to-email settings with email type options](/images/pbx/fax-to-email-setting.png)

   a. In the **Settings** section, click **Add**.

   :::note
   You can add up to **5** email entries.
   :::

   b. In the **Email Type** list, pick how the address is resolved and fill in the matching field:

   - **Extension's Email**: sends inbound faxes to the mailboxes of the extension users you choose. Select those extensions from the **Extension/Email** list.

     :::note
     Make sure each selected extension has a valid email address on file, or the messages won't arrive.
     :::

   - **Specified Email**: sends inbound faxes to a fixed address. Type that address in the **Extension/Email** field.

4. Add your fax numbers and set who may send and receive on each.

   a. In the **Fax Number** section, click **Add**.

   b. In the pop-up, complete the settings below, then click **Save**.

   | Setting | What to enter |
   | --- | --- |
   | Fax Number | The fax number in E.164 format (the international standard: a plus sign, the country code, then the number, with no spaces or punctuation), for example `+12498037994`. |
   | Fax Reception Destination | The extensions or extension groups allowed to receive inbound faxes. They read incoming faxes in the Cloud Voice App under **Fax Management > Fax**. |
   | Extensions Allowed to Send Fax | The extensions or extension groups allowed to send faxes. They send from the Cloud Voice App under **Fax Management > Fax**. |

   :::caution
   Enter the fax number without hyphens (`-`). Faxes to a number that contains hyphens will fail.
   :::

   c. Repeat steps a and b for each additional fax number.

5. Click **Save**.

## Result

When the **Status** shows the green OK indicator ![OK status icon](/images/pbx/trunk-ok.png), the IZT Cloud Fax integration is live.

![The fax integration listed with a successful status](/images/pbx/izt-succeed.png)

## What to do next

- **(Optional) Build cover pages.** Design cover pages that extension users can attach to outbound faxes. See [Add a Fax Cover Page](/pbx/integrations/fax/add-a-fax-cover-page/).
- **Show your users the ropes.** Let extension users know they can send new faxes and open received ones from the Cloud Voice App, under **Fax Management > Fax**, on both the desktop and web clients.