# Integrate Cloud Voice with blueFAX

Cloud Voice can hand off faxing to blueFAX, a hosted fax service, so the people in your organization send and receive faxes over the internet straight from the Cloud Voice App, with no fax machine or fax line involved. This page shows an administrator how to wire the two systems together.

## How the integration works

The link between the two platforms is built from two pieces: a Cloud Voice webhook and the blueFAX REST API. A webhook is an automatic message that one system sends another the moment an event happens (here, a fax arriving at blueFAX). An API (Application Programming Interface) is the set of commands one system uses to make another act (here, Cloud Voice submitting an outbound fax or pulling down an inbound one). Traffic flows in both directions.

![Cloud Voice, overview of the blueFAX faxing integration](/images/pbx/blue-fax-integration.png)

- **Sending**: When an extension user submits a fax from the Cloud Voice App, Cloud Voice calls the blueFAX API to queue the fax for delivery.

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

- **Receiving**: When a fax lands on one of your blueFAX numbers, blueFAX posts a webhook notification to Cloud Voice. Cloud Voice then pulls the fax file back through the API and routes it to the assigned extension users in the app, or to email.

  
  ![Cloud Voice, inbound fax path from blueFAX to extension users](/images/pbx/bluefax-receive-fax.png)

Setup follows three stages, which the steps below walk through in order:

1. Copy a webhook URL out of Cloud Voice.
2. Paste that URL into the blueFAX portal and collect the credentials it gives you.
3. Return to Cloud Voice, enter those credentials, and set up your fax numbers and routing.

## Requirements

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

- **Firmware**: `84.22.0.138` or later
- **Plan**: Enterprise or Ultimate

## Before you start

- Set up an account with blueFAX.
- Buy at least one fax number for that account.

## Step 1: Copy the webhook URL from Cloud Voice

Cloud Voice generates the webhook URL that blueFAX needs in order to notify it of incoming faxes. Copy it first.

1. Open the fax integration form.

   
   ![Cloud Voice, the Fax Integration tab 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. Grab the webhook URL for blueFAX.

   :::caution
   The webhook URL is regenerated the moment you navigate away from this form. Keep this page open until you have configured the URL in blueFAX and copied back the credentials in Step 3.
   :::

   
   ![Cloud Voice, selecting blueFAX and copying the generated webhook URL](/images/pbx/bluefax-webhook-url-pce.png)

   a. From the **Service Provider** drop-down, choose **blueFAX**.

   b. Click the copy icon in the **Webhook URL** field and set the URL aside for the next step.

## Step 2: Set the webhook and collect credentials in blueFAX

In the blueFAX portal you register the webhook URL and gather the values that let the two services trust each other.

### Register the webhook URL

1. Sign in to the [blueFAX portal](https://login.blue-fax.com/en/) with your account.
2. In the top navigation bar, open the **My Account** tab.
3. Go to **Fax settings > Cloud Voice PBX Integration**.

   a. Click **Go to setting page**.

   
   ![Cloud Voice, opening the integration setting page in the blueFAX portal](/images/pbx/access-bluefax-api-setting-page.png)

   b. In the **Webhook-URL** field, paste the URL you copied from Cloud Voice in Step 1.

   ![The Webhook-URL field on the blueFAX portal](/images/pbx/bluefax-portal-webhook-url-pce.png)

   c. In the bottom-right corner, click **Save settings**.

### Collect the credentials

1. In the top-right corner, next to your username, copy your **customer ID** and set it aside.

   ![Locating the customer ID beside the username in the blueFAX portal](/images/pbx/bluefax-get-customer-id.png)

2. Back under **My Account > Fax settings > Cloud Voice PBX Integration**, retrieve your API key and API secret.

   
   ![Cloud Voice, the REST API client authentication section in the blueFAX portal](/images/pbx/bluefax-get-api-key-secret-pce.png)

   a. Click **Go to setting page**.

   b. In the REST API client authentication section, copy the **API key** and **API secret** and save them.

3. Open **My Faxnumbers** and copy the fax number or numbers you want to use.

## Step 3: Enter credentials and configure faxing in Cloud Voice

Return to Cloud Voice, supply the blueFAX credentials, and define how faxes are routed.

1. Switch back to the fax form you left open in the Cloud Voice admin portal.

2. Fill in the **Authorization** section.

   
   ![Cloud Voice, the Authorization fields for the blueFAX integration](/images/pbx/bluefax-set-authorization-pce.png)

   | Setting | What to enter |
   | --- | --- |
   | Name | A label that helps you recognize this integration. |
   | Customer ID | The customer ID you copied from blueFAX. |
   | API Key | The API key you copied from blueFAX. |
   | API Secret | The API secret you copied from blueFAX. |

   :::caution
   Treat the API key and API secret like passwords. Anyone who has them can submit faxes billed to your blueFAX account. Do not share them or paste them anywhere other than this form.
   :::

3. **Optional**: To also deliver inbound faxes as email attachments, set up email routing.

   
   ![Cloud Voice, configuring fax-to-email delivery](/images/pbx/fax-to-email-setting.png)

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

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

   b. From the **Email Type** drop-down, pick a recipient type and complete the matching fields:

      - **Extension's Email**: Delivers inbound faxes to the mailboxes of extension users. Choose the extensions from the **Extension/Email** drop-down.

        :::note
        Make sure the extensions you select have a valid email address on file, or those users will not receive the emails.
        :::

      - **Specified Email**: Delivers inbound faxes to a fixed address. Type the address into the **Extension/Email** field.

4. Add your fax numbers and decide who may use them.

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

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

      | Setting | What to enter |
      | --- | --- |
      | Fax Number | A fax number from blueFAX, written in E.164 format (a leading `+`, then the country code, then the number, with no spaces or dashes). For instance, the German number `089-41324038` (country code `49`) is entered as `+498941324038`. A number that does not exactly match one held on your blueFAX account will not receive faxes. |
      | Fax Reception Destination | The extensions or extension groups allowed to receive inbound faxes. These users 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. These users send faxes from the Cloud Voice App under **Fax Management > Fax**. |

   c. In the bottom-right corner, click **Save**.

   d. Repeat steps a through c for each additional fax number.

5. Click **Save**.

## Result

- The **Status** shows a success indicator, confirming the blueFAX integration is live.

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

- The authorized extension users can now send and receive faxes through blueFAX directly from the Cloud Voice App (Web or Desktop).

## Next steps

- **(Optional) Build cover pages.** Create reusable cover sheets that fax senders can attach to outbound faxes. See [Add a Fax Cover Page](/pbx/integrations/fax/add-a-fax-cover-page/).
- **Brief your users.** Show the authorized extension users how to send faxes and review inbound faxes from the Cloud Voice App.