# Integrate Cloud Voice with Telnyx Fax

Connecting Cloud Voice to Telnyx Fax gives your team internet-based faxing: extension users send and receive faxes straight from the Cloud Voice App (Desktop or Web), carried over Telnyx's network instead of a physical fax line.

## How the integration works

The link between the two systems relies on the Cloud Voice webhook and the Telnyx Fax API V2. A webhook is an automatic notification that one service sends to another when an event happens, and an API (Application Programming Interface) is the connection that lets software send commands to a service. Here is what happens in each direction:

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

  
  ![Cloud Voice, outbound fax flow from the app through Cloud Voice to Telnyx](/images/pbx/telnyx-receive-fax.png)

- **Inbound**: When a fax arrives at your Telnyx fax number, Telnyx notifies Cloud Voice through the webhook. Cloud Voice then pulls the fax file back over the API and routes it to the extension users you designate.

  
  ![Cloud Voice, inbound fax flow from Telnyx through Cloud Voice to the app](/images/pbx/telnyx-send-fax.png)

![Cloud Voice, overview of the Telnyx fax integration architecture](/images/pbx/telnyx-fax-integration.png)

Setting it up comes down to three stages, which the rest of this page walks through:

1. Copy the webhook URL from Cloud Voice.
2. Build the required resources in Telnyx and collect the credentials they generate, an API key, an outbound voice profile, a fax-capable phone number, and a fax application.
3. Return to Cloud Voice, enter those credentials, 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 Plan or Ultimate Plan

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

Telnyx needs this URL when you create the fax application later, so grab it first.

1. Open the fax integration screen.

   
   ![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. Retrieve the webhook URL.

   
   ![Cloud Voice, the Webhook URL field with Telnyx selected as the service provider](/images/pbx/webhook-url-pce.png)

   a. Set **Service Provider** to **Telnyx**.

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

## Step 2. Create resources and collect credentials in Telnyx

Everything in this step happens inside the [Telnyx portal](https://portal.telnyx.com/). You'll create four things and note the credentials each one produces.

### 1. Create an API key

1. Open the API keys page.

   a. Sign in to the [Telnyx portal](https://portal.telnyx.com/).

   b. Click your account in the top-right corner and choose **API keys**.

   
   ![Cloud Voice, the API keys entry in the Telnyx account menu](/images/pbx/telnyx-api-page.png)

2. Generate the key.

   a. Click **Create API Key** in the top-right corner.

   ![Telnyx API keys list with the Create API Key button](/images/pbx/create-api-key.png)

   b. In the dialog, set a tag and an expiration date if you want, then click **Create**. Telnyx generates and displays the new key.

      :::tip
      The tag is only a label to help you find this key later. If you set an expiration date, the fax integration stops working the moment the key expires, so either leave it open-ended or note the date and replace the key before it lapses.
      :::

   ![Telnyx dialog for setting an API key tag and expiration date](/images/pbx/api-tag-expdate.png)

   c. Copy the key, save it for later, and close the dialog.

      :::caution
      Treat the API key like a password: it grants access to your Telnyx account, so anyone who obtains it could run up fax and call charges. Store it somewhere secure and never share it in plain text. Copy it before you close the dialog, as you may not be able to view the full key again.
      :::

   ![Telnyx dialog showing the generated API key with a copy control](/images/pbx/copy-api-key.png)

### 2. Create an outbound voice profile

An outbound voice profile is what later authorizes your fax application to place outbound faxes, so create one now.

1. Open the outbound voice profiles page.

   a. Click **Back** in the top-left corner to return to the home menu.

   ![Telnyx Back control returning to the home menu](/images/pbx/back-home-menu.png)

   b. In the left navigation, go to **Real-Time Communications > Voice > Settings > Outbound Voice Profiles**.

2. Click **Create Profile** in the top-right corner.

   ![Telnyx Outbound Voice Profiles page with the Create Profile button](/images/pbx/telnyx-create-voice-profile.png)

3. Set up the profile however suits your account.

### 3. Buy a fax-capable phone number

1. In the left navigation, go to **Real-Time Communications > Numbers > Buy Numbers**.

   ![Telnyx Buy Numbers entry in the Numbers menu](/images/pbx/telnyx-buy-numbers-entry.png)

2. Search for and purchase a number that supports fax.

   a. On the **Buy Number** tab, set **Features** to **Fax**, add any other filters you need, and click **Search Numbers** to list what's available.

   ![Telnyx number search filtered to the Fax feature](/images/pbx/buy-number-fax-capability.png)

   b. Pick a number and complete the purchase. Telnyx sends you to the **Manage Numbers** page, where the new number appears.

   ![Telnyx Manage Numbers page showing the purchased number](/images/pbx/telnyx-purchased-number.png)

### 4. Create a fax application

1. Open the fax application page.

   ![Telnyx Fax page with the Create Fax App button](/images/pbx/fax-app-creation-page.png)

   a. In the left navigation, go to **Real-Time Communications > Fax**.

   b. Click **Create Fax App** in the top-right corner.

2. On the **Details** step, fill in the following and click **Create**.

   
   ![Cloud Voice, the Details step of the Telnyx fax application form](/images/pbx/fax-app-detail-pce.png)

   | Setting | What to enter |
   | --- | --- |
   | Application name | A label that helps you recognize the application. |
   | Webhook URL | Paste the webhook URL you copied from Cloud Voice in Step 1. |
   | Timezone | The time zone to use in the fax header timestamps. |

3. On the **Inbound** step, leave the defaults or adjust them as needed, then click **Next**.

   ![Telnyx Inbound settings for the fax application](/images/pbx/fax-app-inbound.png)

4. On the **Outbound** step, choose the outbound voice profile you created earlier from the **Outbound Voice Profile** list to allow outbound faxing, then click **Next**.

   ![Telnyx Outbound settings with the voice profile selected](/images/pbx/fax-app-outbound.png)

5. On the **Numbers** step, click the link icon ![assign number icon](/images/pbx/link-telnyx.png) to attach the fax number you bought to this application.

   ![Telnyx step for assigning a number to the fax application](/images/pbx/telnyx-assign-number.png)

6. Click **Complete** in the bottom-left corner. A confirmation window tells you the application is created.

   ![Telnyx confirmation that the fax application was created](/images/pbx/telnyx-app-created.png)

7. Get the application ID.

   a. Click **View my application**.

   ![Telnyx confirmation window with the View my application button](/images/pbx/telnyx-view-app.png)

   b. On the **Details** tab, copy the application ID and save it for later.

   ![Telnyx application Details tab showing the application ID](/images/pbx/telnyx-app-id.png)

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

Back in Cloud Voice, plug in the Telnyx credentials and finish the fax settings to complete the integration.

1. Open the fax integration screen.

   
   ![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. Complete the **Authorization** section.

   
   ![Cloud Voice, the Authorization fields for the Telnyx fax integration](/images/pbx/telnyx-auth-pce.png)

   | Setting | What to enter |
   | --- | --- |
   | Name | A label that helps you recognize the integration. |
   | Service Provider | Select **Telnyx**. |
   | API Key | Paste the API key you copied from Telnyx. |
   | Application ID | Paste the application ID you copied from Telnyx. |

3. **Optional:** To forward inbound faxes to email addresses as attachments, set this up in the **Settings** section.

   
   ![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. From the **Email Type** list, pick the kind of recipient and fill in the matching fields:

      - **Extension's Email**: Deliver inbound faxes to extension users' mailboxes. Choose the extensions from the **Extension/Email** list.

        :::caution
        Make sure the selected extensions have valid email addresses configured, or those users won't get the emails.
        :::

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

4. Define your fax number(s) and decide which extension users may send and receive faxes.

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

   b. In the pop-up window, fill in the following and click **Save**.

      | Setting | What to enter |
      | --- | --- |
      | Fax Number | Your Telnyx fax number in E.164 format: a plus sign, the country code, then the number, with no spaces or separators. Example: `+12498037994`. |
      | Fax Reception Destination | The extensions or extension groups allowed to receive inbound faxes. Recipients open them 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 number without hyphens (`-`). A number that contains hyphens will fail to deliver.
      :::

   c. To add another fax number, repeat sub-steps a and b.

5. Click **Save**.

## Result

The **Status** column shows a success indicator ![success icon](/images/pbx/trunk-ok.png), which confirms the Telnyx Fax integration is live.

![Fax integration list showing the Telnyx entry with a success status](/images/pbx/telnyx-succeed.png)

## What to do next

- Optionally build cover pages that your users can attach to outbound faxes. See [Add a Fax Cover Page](/pbx/integrations/fax/add-a-fax-cover-page/).
- Show your extension users how to send faxes and read incoming ones from the Cloud Voice App, under **Fax Management > Fax**.