# Integrate Cloud Voice with Microsoft SQL

Link Cloud Voice to a Microsoft SQL database and your PBX (Private Branch Exchange, the phone system) checks every inbound (incoming) call against that database. When the caller's number matches a stored record, the matching contact name is shown with the call, so staff can see who is calling before they answer.

## Requirements

| Item | Requirement |
| --- | --- |
| Cloud Voice | **Plan**: Enterprise Plan (EP) or Ultimate Plan (UP)<br />**Firmware**: Version 84.16.0.70 or later |
| Microsoft SQL | None. Any version of Microsoft SQL Server can be integrated with Cloud Voice. |

:::caution
This integration is available only on the Enterprise Plan (EP) or Ultimate Plan (UP), and the PBX must be running firmware 84.16.0.70 or later. On a lower plan or older firmware, the Microsoft SQL option will not appear.
:::

## Step 1. Turn on the Microsoft SQL integration

1. Open the Microsoft SQL configuration page.
   1. Sign in to the PBX web portal and go to **Contacts > Company Contacts**.
   2. Click **Synchronize Contacts** near the top of the page.

      ![Synchronize Contacts control on the Company Contacts page](/images/pbx/sync-contacts-from-thirdparty.png)

2. Switch on **Enable Microsoft SQL Integration**, then fill in the connection details described below.

   ![Microsoft SQL integration panel with the server and credential fields](/images/pbx/ms-sql-integration-pce.png)

   | Setting | Description |
   | --- | --- |
   | Server Address | Point Cloud Voice at your Microsoft SQL server.<br /><br />If the server listens on the default port `1433`, enter only its IP address or domain name, for example `112.48.21.123`.<br /><br />If the server uses a different port, append it after a colon, for example `112.48.21.123:20001`. |
   | Database Name | The name of the database to query. |
   | Timeout(s) | How long, in seconds, to wait when connecting to the server before the attempt times out. |
   | User | The account name used to sign in to the database. |
   | Password | The password for that account. |
   | Auto-match Contact Filter | A `SELECT` statement that tells Cloud Voice how to look up a caller's number, written as `select ${MAP} from {schema_name}.{table_name} where {condition_to_filter_number}`. See the breakdown below. |

   :::tip
   Create a dedicated Microsoft SQL login for this integration and grant it read-only access to just the contacts table. Limiting its rights keeps the rest of your database safe if these credentials are ever exposed.
   :::

### Building the Auto-match Contact Filter

Take this statement as a model:

```sql
select ${MAP} from testpbx.contacts where businumber like CONCAT('%', ${NUMBER}, '%')
```

Each part does the following:

- **`select ${MAP}`**, names the database column whose value you want shown as the caller ID name. At runtime, `${MAP}` is substituted with the PBX field or fields (First Name, Last Name, or both) that you enable in the **Map** section during Step 2.
- **`from testpbx.contacts`**, the table to read from. Always give it as a two-part name in the form `{schema_name}.{table_name}`.
- **`where businumber like CONCAT('%', ${NUMBER}, '%')`**, returns the rows where the `businumber` column contains the caller's number (`${NUMBER}`) anywhere within it.

:::caution
Write the table as a two-part name, `{schema_name}.{table_name}` (schema plus table). A single-part name will not resolve and the lookup will fail. Leave the `${MAP}` and `${NUMBER}` placeholders exactly as written: Cloud Voice fills them in automatically on each call.
:::

## Step 2. Map fields between Cloud Voice and Microsoft SQL

1. Scroll down to the **Map** section.
2. Map the fields needed to display the caller's name.

   
   ![Cloud Voice, Map section pairing PBX contact fields with Microsoft SQL columns](/images/pbx/sql-caller-id-map.png)

   1. For **Contacts ID**, **First Name**, and **Business Number**, enter the matching column name from your Microsoft SQL contacts table. Once saved, an inbound call that matches a record shows the contact's first name.

      :::note
      In this example, **Business Number** is mapped because it is the number column referenced in the `where` clause of the filter statement (see the example in Step 1). Map whichever number column fits your own table.
      :::

   2. **Optional:** to show the last name as well, select the **Last Name** checkbox and enter its corresponding Microsoft SQL column.
3. To pull Microsoft SQL contacts into the PBX, enable and map the additional fields you want to sync.

   ![Field mapping used when syncing Microsoft SQL contacts into the PBX](/images/pbx/sql-map-contacts-sync.png)

4. Click **Save**.

## Result

- Cloud Voice is connected to your Microsoft SQL server.

  ![Connection status confirming a successful link to the Microsoft SQL server](/images/pbx/ms-sql-integration-success.png)

  :::tip
  If the panel does not confirm a successful connection, re-check the server address and port, database name, username, and password, then save again.
  :::

- When an inbound call matches a record in your database, the caller's name is displayed.

## What to do next

To let extension users call your Microsoft SQL contacts directly from the Cloud Voice App, set up contact synchronization from the Microsoft SQL server. For details, see [Set up Contact Synchronization from Microsoft SQL](/pbx/integrations/microsoft-sql/set-up-contact-synchronization-from-microsoft-sql/).