> For the complete documentation index, see [llms.txt](https://atlas.anywhere.now/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://atlas.anywhere.now/product-reference/dialogue-studio/dialogue-studio-example-flows/connect-microsoft-graph-application.md).

# Connect to Microsoft Graph as an application

Import a flow in Dialogue Studio that authenticates as an application and searches Microsoft Graph for a user by name.

This example connects Dialogue Studio to Microsoft Graph using application permissions and an OAuth client credentials flow, then searches for a user by first or last name. Use it as a starting point for looking up directory information from Microsoft Graph.

## What it does

Some Microsoft Graph resources require an access token. This flow requests a token, then uses it to search for a user whose given name or surname matches the search text. It is an inject-driven diagnostic example, not a complete caller-facing IVR.

## Prerequisites

* Register your app with Microsoft Entra ID. See [Register an application with the Microsoft identity platform](https://learn.microsoft.com/en-us/graph/auth-register-app-v2).
* Grant the app the API permission needed to list users. See [List users - Microsoft Graph v1.0](https://learn.microsoft.com/en-us/graph/api/user-list?view=graph-rest-1.0\&tabs=http).

## Preview

![Microsoft Graph user search flow](https://2627137428-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FscZpnEdBjDgQmlVn1iLr%2Fuploads%2Fgit-blob-13d70fab468aa26e3f276089a114a39eef6c7e38%2Fmicrosoft-graph-user-search.png?alt=media)

## Import the flow

{% file src="/files/jkwYwm32UpTSZeLE6qgm" %}
Microsoft Graph user search example
{% endfile %}

1. Log in to your Dialogue Studio environment.
2. Open or create a tab for the flow.
3. Download the JSON attachment above. From the menu in the top right, select **Import** and add that file.
4. Open the **Configure Graph configurations** change node and fill in:
   * `client_id` - from the app registration's **Overview** page.
   * `client_secret` - created and copied from **Manage > Certificates & secrets** on the app registration.
   * `tenant_id` - from the app registration's **Overview** page.
5. Open the inject node and enter the name of the user you want to search for.
6. Enable the diagnostic debug nodes whose outcomes you want to inspect. All five debug nodes are disabled in the supplied file. Keep their existing payload-only output selections; do not log the complete message, credentials, or authorization headers.
7. Deploy the example in a controlled test flow, then select the blue box before the inject node.
8. Use the debug sidebar to see which enabled debug node the result reached. Use test directory records and handle their personal data appropriately.

{% hint style="warning" %}
Enter the client secret using your organization's approved secret handling process. Never leave a real client secret in a flow you export, share, or debug.
{% endhint %}

## How the flow works

* **Graph access token** (group of nodes):
  * **Check Token Validity** checks whether a cached token in flow context is still valid. If so, it uses the existing token; otherwise it requests a new one.
  * **Use Existing Token** sets the Authorization header from the cached token.
  * **Prepare Token Request** builds the client credentials payload (`client_id`, `scope: https://graph.microsoft.com/.default`, `client_secret`) and headers for a token request.
  * **Get Token** sends the HTTP POST request to `https://login.microsoftonline.com/{tenant_id}/oauth2/v2.0/token`.
  * **Store Token and use New Token** stores the token response values in flow context and sets the Authorization header. Review the expiry mapping before relying on caching: the supplied function reads `expires_on`, while Microsoft identity platform v2 token responses describe lifetime using `expires_in`. This sample does not establish reliable token reuse without that review.
  * **Check statusCode** verifies the token response was `200`. If not, a debug node logs the failure.
* **Graph user search** (group of nodes):
  * **Prepare Contact Request** builds the Graph query URL: `https://graph.microsoft.com/v1.0/users/?$filter=startswith(givenName, '<q>') OR startswith(surname, '<q>')`.
  * **Get User** sends the HTTP GET request to Microsoft Graph.
* **Validate output** (group of nodes):
  * **Check statusCode** verifies the response was `200`. If not, a debug node logs the failure.
  * **Check if any results** and **Check if multiple results** branch to separate debug nodes for no results, a single result, or multiple results.

## Diagnostic outcomes, not caller fallback

A failed token request or a non-200 response from Microsoft Graph routes to a dedicated debug node. A search with no matching user has a separate outcome from a request error. These outcomes are visible only when the corresponding debug nodes are enabled.

The example has no incoming-call trigger, caller response, or caller continuation. Its debug branches are not production fallback. For a separate recovery pattern, see [Configure a Catch node](/product-reference/dialogue-studio/dialogue-studio-example-flows/configure-catch-node.md), then validate the errors and timeouts relevant to your integration.

## Verification

1. Trigger the inject node with a known user's first or last name and confirm the "Returned single contact" debug entry shows the expected user.
2. Trigger it with a name that matches multiple users and confirm the "Multiple results" debug entry fires.
3. Trigger it with a name that matches no user and confirm the "no results" debug entry fires instead of an error.
4. In an isolated test copy with no cached Graph token, use an invalid test secret and confirm the token-error debug node receives the failure. Do not alter production credentials for this check.
5. Restore the test configuration and disable diagnostics when they are no longer needed. Do not export or share the flow with real credentials.

## Related topics

* Go to [Connect to SharePoint sites and lists with Microsoft Graph](/product-reference/dialogue-studio/dialogue-studio-example-flows/connect-sharepoint-with-microsoft-graph.md) for a related application-permission pattern using Sites.Selected.
* Go to [Dialogue Studio example flows](/product-reference/dialogue-studio/dialogue-studio-example-flows.md) for the full gallery of example flows.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://atlas.anywhere.now/product-reference/dialogue-studio/dialogue-studio-example-flows/connect-microsoft-graph-application.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.