# Microsoft Dynamics

Nimbata's Microsoft Dynamics integration automatically sends call data to Dynamics 365, so you can capture caller details and track which marketing sources drive phone leads. When a caller is not in Dynamics yet, Nimbata creates the records you choose, such as a Lead and a Phone Call. When the caller already exists, it updates the record it finds or logs the call against it. A workflow decides which calls are sent.

The integration works through the Dynamics 365 Web API only: there is nothing to install in your environment. You connect by signing in with your Microsoft work account and choosing the Dynamics environment that receives the calls.

**Before you start**

- Plan: Marketing or Agency, or a Nimbata trial
- Permissions: Microsoft Dynamics, under Integrations, in your Nimbata role
- A Dynamics 365 environment, such as Dynamics 365 Sales, and a Microsoft work or school account that can sign in to it.
- A security role in that environment that lets the account create and update the records Nimbata writes (for example Leads, Contacts, Phone Calls and Tasks).
- If your organization lets only admins approve apps, a Microsoft Entra admin to approve Nimbata the first time you connect.
- The Nimbata project whose calls you want to send: the integration is set up per project.

## Connect Microsoft Dynamics

1. **Open the Microsoft Dynamics integration**

   Go to **Integrations** and click **Go to integration** on the **Microsoft Dynamics** tile (1), or go straight to [Integrations > Microsoft Dynamics](https://app.nimbata.com/integrations/microsoft-dynamics).

   [The Microsoft Dynamics tile on the Integrations page, with Go to integration marked 1]

   *Open the Microsoft Dynamics tile (1).*

2. **Connect your Microsoft account**

   - Click **Connect** (1). A Microsoft sign-in window opens.
   - Sign in with your Microsoft work or school account, the one you use for Dynamics 365.
   - Approve the access Nimbata asks for (see [What Nimbata can access](#what-nimbata-can-access) below). If Microsoft says the app needs admin approval, see [Troubleshooting](#microsoft-says-you-need-admin-approval).
   - A confirmation message appears once connected, and the page shows the Microsoft account you connected with.

   [The Microsoft Dynamics integration page before it is connected, with the Connect button marked 1, above the Caller not found and Caller found sections and Send Test and Save]

   *Click Connect (1) and sign in with your Microsoft work account.*

3. **Choose your Dynamics environment**

   - Click **Select Environment** at the top of the page (1). The list shows every enabled Dynamics environment your Microsoft account can reach, by name and URL.
   - Choose the environment that should receive your calls, for example your production environment rather than a sandbox.
   - The button now shows the environment's URL followed by **Environment**. Nimbata reads the objects and fields of that environment for your setup, so choose it before you map any fields. To change it later, disconnect and connect again.

   [The Select Environment menu open, listing the Harbor & Pine environment with its URL, marked 1, and a sandbox environment]

   *Click Select Environment and choose the environment that receives your calls (1).*

### What Nimbata can access

Nimbata connects with Microsoft's own sign-in, so you enter your password on Microsoft's page and Nimbata never sees it. It asks for three kinds of access:

| Access                                            | What Nimbata uses it for                                                                                                                                                            |
| ------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Dynamics 365, as you**                          | Lists your environments, reads the objects and fields of the one you choose, searches its phone fields for the caller's number, and creates or updates the records your setup maps. |
| **Your email address and basic profile**          | Shows on the integration page who connected Microsoft Dynamics.                                                                                                                     |
| **Keep access to the data you gave it access to** | Keeps the connection working with a refresh token, so calls are sent after you close the window.                                                                                    |

Nimbata acts as the account that connected: it can see and change only what that account's security roles allow in Dynamics 365.

## Configure Microsoft Dynamics

Click **Set up Microsoft Dynamics** to add a setup, such as **Microsoft Dynamics Settings 1**. Each setup has two sections: **Caller not found**, what Nimbata creates when the caller is not in Dynamics, and **Caller found**, what it does with the record it finds when they are. To send different calls to Dynamics in different ways, add another setup; each workflow picks the setup it sends.

1. **Map your fields**

   - Nimbata loads the fields of your environment, standard and custom, for the objects it can write: **Contact**, **Account**, **Lead**, **Phone Call**, **Fax** and **Task**.
   - Under **Caller not found**, choose the object to create, for example **Lead**. Click **+ Add object** to add another, such as a **Phone Call** linked to the new Lead.
   - Map the Nimbata call fields to the Dynamics fields, or click **Use Default Config** to fill in the recommended mapping: a new Lead with the caller's number as its **Business Phone**, and a Phone Call regarding that Lead.

   [The Microsoft Dynamics Caller not found section: Create a Lead with Business Phone, First Name and Last Name mapped, and Create a Phone Call regarding the new Lead with a Subject]

   *Caller not found: a new Lead with its fields mapped, then a Phone Call regarding it.*

2. **Choose how existing callers are matched**

   For every call, Nimbata searches your Contacts, Accounts and Leads for the caller's number, in their **Business Phone**, **Mobile Phone** (Contacts and Leads) and address phone fields. If it finds a record, it runs your **Caller found** actions on it; if not, it runs your **Caller not found** actions and creates the records. A call with a withheld number always counts as not found.

   In the **Caller found** section, answer the two matching questions first:

   1. **Which entity to enrich** (1), when the Caller ID is found in more than one object: **Contact**, **Lead**, **Account** or **All**.
   2. **How to handle duplicates** (2), when the same Caller ID is found more than once in one object: **Handle first**, **Handle all** or **Ignore all**. With **Ignore all**, Nimbata skips the call whenever the caller matches an existing record, even a single one, and doesn't create a new record either.

   Then choose what to send for the record Nimbata finds. **Use Default Config** here adds a Task and a Phone Call on the matched record.

   [The Microsoft Dynamics Caller found section: the entity question with All chosen, marked 1, and the duplicates question with Handle first chosen, marked 2]

   *Choose the entity to enrich (1) and how to handle duplicates (2).*

### What you can send

You can map any Nimbata call field, for example:

- The caller: **Caller ID**, **Caller Name**, **City**, **State** and **Country**.
- The call: **Start Time**, **Call Duration**, **Call Outcome**, **Tracking Number**, **Tracking Number Friendly Name**, **Tags**, **Value** and **Notes**.
- Where the call came from: **Source Type** (the tracking source), **UTM Source**, **UTM Medium**, **UTM Campaign**, the landing page and the click IDs (**Google Ads Click ID**, **Facebook Click ID**, **Microsoft Click ID**).
- The conversation: the recording link (**Rec Link**), the **Transcription** and the AI **Summary**. These have a value only when your plan and your workflows record, transcribe and summarize the call.

Dynamics keeps durations in minutes, so when you map **Call Duration** to a Dynamics duration field, Nimbata turns the seconds into minutes, rounded up. For a choice field, pick one of the options your environment defines.

## Test the integration

1. **Send a test event**

   - Click **Send Test and Save**. A test panel opens with the call fields your setup uses.
   - Fill in the test data fields, and click **Send event**. Include a **Caller ID**: if it is already in Dynamics, Nimbata runs your **Caller found** actions, otherwise your **Caller not found** actions.
   - The panel shows a result for each record, with its Dynamics ID, for example "Lead created successfully. ID: ...".

2. **Check the records in Dynamics**

   The test writes real records to your environment, such as a test Lead and a Phone Call. Open them to confirm the fields are mapped as you expect, and delete them when you are done.

3. **Save the setup**

   Click **Save**.

## Send calls with a workflow

Nimbata sends a call to Dynamics when a workflow with a **Microsoft Dynamics** action runs for it. Both inbound calls (to your tracking numbers) and outbound calls (placed by your team) can be sent. A workflow that runs when a call ends, with no filter, sends every call, and its filters (for example **1st Time Caller (1yr)**, call outcome or tracking number) narrow it down. Form submissions and SMS are not sent to Dynamics.

1. **Create a workflow**

   Go to **Workflows**, click **Create** and choose **From Scratch**. Keep the **Inbound Call** trigger, or choose **Outbound Call**, with **Call Ends**, and add any filters you need.

2. **Add the Microsoft Dynamics action**

   Click the **+** plus sign, select **Perform action**, and choose **Microsoft Dynamics** under **Integrations**. Pick your setup under **Select configuration** (1), then click **OK**.

   [The Microsoft Dynamics pop-up of the workflow builder, with the Microsoft Dynamics Settings 1 setup selected and marked 1]

   *Pick the Microsoft Dynamics setup to send (1), then click OK.*

3. **Enable the workflow**

   Click **Enable** (1).

   [A workflow firing on Inbound Call, Call Ends, with a Microsoft Dynamics action sending Microsoft Dynamics Settings 1, and the Enable button marked 1]

   *The workflow sends every inbound call to Microsoft Dynamics when it ends. Click Enable (1).*

Detailed guide: [Create a workflow](https://help.nimbata.com/workflows/workflows#create-a-workflow)

## Check it worked

The Microsoft Dynamics page now shows your environment and the workflow that uses the integration. Place a test call to one of your tracking numbers: once it ends, the record appears in Dynamics 365.

[The connected Microsoft Dynamics integration with the Harbor & Pine environment shown, used in 1 workflow, with Microsoft Dynamics Settings 1 used by the Dynamics calls workflow]

*The page shows the chosen environment, Used in 1 workflow, and the setup lists the workflow that sends it.*

🎉 Done! Nimbata sends call data to Dynamics 365 for every call your workflow sends.

## Disconnect Microsoft Dynamics

- **In Nimbata:** open the Microsoft Dynamics integration and click **Disconnect** in the page's three-dot menu. Nimbata deletes the Microsoft tokens it holds for the project, forgets the chosen environment and stops sending calls. Your setups are kept for when you connect again.
- **In Microsoft:** disconnecting in Nimbata does not withdraw the access you approved in Microsoft, so remove it there too if you want it gone. Open My Apps (myapps.microsoft.com) with the account you connected, open the Nimbata app's menu, choose **Manage your application** and click **Revoke permissions**. A Microsoft Entra admin can remove the app for the whole organization under **Enterprise applications** in the Microsoft Entra admin center.

Once access is removed in Microsoft, Nimbata can no longer reach your environment, and no calls are sent until you connect again.

## Troubleshooting

### Microsoft says you need admin approval

Your organization lets only admins approve apps that ask for access to its data. Ask a Microsoft Entra admin to approve Nimbata for the organization (they can do it from the same approval screen when they sign in), then click **Connect** again.

### Select Environment is greyed out, or your environment is missing

The list shows only enabled environments that the connected Microsoft account can reach.

- Check that the account you connected with has access to the environment in Dynamics 365 (a licence and a security role there).
- Check that the environment is enabled.
- Then disconnect in the page's three-dot menu and connect again with the right account.

### Records go to the wrong Dynamics environment

The environment button at the top of the page shows the URL of the environment Nimbata writes to. It cannot be changed while connected: disconnect from Microsoft Dynamics in the page's three-dot menu, connect again and choose the other environment under **Select Environment**.

### Existing callers are not found

Nimbata compares whole phone numbers: it looks for the caller ID as it comes in, and again without its country code. A number saved in Dynamics in another format (with spaces, brackets or dashes, say) may not be found, and the caller is treated as new.

- Save phone numbers in Dynamics in the same format as the Caller ID in your Nimbata call log.
- Keep the numbers in the fields Nimbata searches: **Business Phone**, **Mobile Phone** or the address phone fields.

### The Microsoft Dynamics tile says Disconnected

Nimbata has lost its connection to Dynamics, for example because the connected account lost access to the environment or its access was removed in Microsoft. Your setups are saved, but nothing is sent until you reconnect: open the integration, click **Reconnect** in the red **Disconnected.** banner, and check that the account you connect with still has access to the environment.

[The Microsoft Dynamics tile on the Integrations page with a red Disconnected badge]

*A disconnected integration shows a red Disconnected badge on its tile.*

### Send Test and Save is greyed out

- Connect Microsoft Dynamics and choose your environment first: the button stays off until the integration is connected.
- Map at least one field under **Caller not found** or **Caller found**.
- If the test answers "Please provide a valid caller id", fill in the **Caller ID** box in the test panel.

### Calls are not reaching Dynamics

- Check that a workflow with a **Microsoft Dynamics** action is enabled, and that its filters let the call through.
- Check that the workflow's Microsoft Dynamics action uses the setup you configured, under **Select configuration**.
- Check that the Microsoft Dynamics tile does not say **Disconnected**.
- Send a test from **Send Test and Save** to see the error Dynamics returns.