> Documentation index for AI agents: https://docs.pagerduty.com/llms.txt

# Create a Dedicated Chat

`POST https://api.pagerduty.com/integration-ms-teams/incidents/{incident_id}/dedicated_chat`

Creates a Microsoft Teams Group Chat for the specified Incident and returns its details.

> ### Important
>
>  Make sure that your PagerDuty account is connected to your MS Teams tenant and your
>  PagerDuty user is linked to your MS Teams user. You can do this on the MS Teams
>  add-on page in your PagerDuty account or by interacting with the PagerDuty bot
>  in Microsoft Teams.

## Authorization

- **apiKey** (apiKey) — `Authorization` header. The API Key with format `Token token=<API_KEY>`

## Path parameters

| Name | Type | Required | Description |
|---|---|---|---|
| `incident_id` | string | yes | PagerDuty Incident ID. |

## Header parameters

| Name | Type | Required | Description |
|---|---|---|---|
| `Accept` | string | yes | The `Accept` header is used as a versioning header. Default: `application/vnd.pagerduty+json;version=2`. |

## Request body (`application/json`) — required

| Field | Type | Required | Description |
|---|---|---|---|
| `mst_tenant_id` | string | yes | ID of the Microsoft Teams tenant connected to PagerDuty. |
| `owner_pd_user_id` | string |  | PagerDuty User ID of the user whose MS Teams account should own the chat. Defaults to the requesting user. |
| `chat` | object |  | Details of the Group Chat to be created in Microsoft Teams. |
| `chat.name` | string |  | Name of the Group Chat in Microsoft Teams. |
| `events` | string |  | Preset name for the type of Incident updates to send to the chat. Valid values: highlights_only, status_updates_only, all_updates, no_updates. Defaults to all_updates. |

Example: Request Example

```json
{
  "mst_tenant_id": "dd649b90-2b30-45cb-a264-1130134c625e",
  "chat": {
    "name": "Incident #1234: Server Room is on Fire"
  },
  "events": "all_updates"
}
```

## Response 201

Returns details of the Group Chat created in Microsoft Teams.

### `application/json`

| Field | Type | Required | Description |
|---|---|---|---|
| `chat` | object | yes | Microsoft Teams Group Chat details. |
| `chat.name` | string | yes | Name of the Group Chat in Microsoft Teams. |
| `chat.url` | string | yes | URL to open the Group Chat in Microsoft Teams. |

Example: Response Example

```json
{
  "chat": {
    "name": "Incident #1234: Server Room is on Fire",
    "url": "https://teams.microsoft.com/l/chat/19%3Ameeting_xyz%40thread.v2/0"
  }
}
```

## Response 400

The request was malformed or invalid.

### `application/json`

| Field | Type | Required | Description |
|---|---|---|---|
| `error` | object | yes |  |
| `error.message` | string | yes | Error message string. Read-only. |

Example: Bad Request

```json
{
  "error": {
    "message": "Bad Request"
  }
}
```

## Response 401

Caller did not supply credentials or did not provide the correct credentials.
If you are using an API key, it may be invalid or your Authorization header may be malformed.

### `application/json`

| Field | Type | Required | Description |
|---|---|---|---|
| `error` | object | yes |  |
| `error.message` | string | yes | Error message string. Read-only. |

Example: Unauthorized

```json
{
  "error": {
    "message": "Unauthorized"
  }
}
```

## Response 403

Caller is not authorized to access the requested resource.
While the authentication is valid, the authenticated user does not have permission to perform this action.

### `application/json`

| Field | Type | Required | Description |
|---|---|---|---|
| `error` | object | yes |  |
| `error.message` | string | yes | Error message string. Read-only. |

Example: Forbidden

```json
{
  "error": {
    "message": "Forbidden"
  }
}
```

## Response 404

The requested resource was not found.

### `application/json`

| Field | Type | Required | Description |
|---|---|---|---|
| `error` | object | yes |  |
| `error.message` | string | yes | Error message string. Read-only. |

Example: Not Found

```json
{
  "error": {
    "message": "Not Found"
  }
}
```

## Response 409

A dedicated chat already exists for the specified Incident.

### `application/json`

| Field | Type | Required | Description |
|---|---|---|---|
| `error` | object | yes |  |
| `error.message` | string | yes | Error message string. Read-only. |

Example: Conflict

```json
{
  "error": {
    "message": "The incident chat group already exists."
  }
}
```

## Developer Agreement

Your access to and use of the PagerDuty Developer Services is governed by the [PagerDuty Developer Agreement](https://docs.pagerduty.com/developer/pagerduty-developer-agreement).