---
title: NerdGraph tutorial: Alerts channels
source: https://docs.newrelic.com/docs/apis/nerdgraph/examples/nerdgraph-api-notifications-channels
---

In addition to managing your [alert notification channels in the UI](https://docs.newrelic.com/docs/alerts-applied-intelligence/notifications/intro-notifications), you can use our NerdGraph API.

> #### ⚠️ IMPORTANT
>
> This document refers to using Nerdgraph APIs for the new notification platform using destinations and notification messages. Notification messages are also referred to as channels, which are different from legacy notification channels.

> #### 💡 TIP
>
> For help getting started with NerdGraph, see [Introduction to NerdGraph](https://docs.newrelic.com/docs/apis/nerdgraph/get-started/introduction-new-relic-nerdgraph).

## List and filter channels [#list-and-filter]

The `channels` query allows you to paginate through all of your channels per account. It also allows some filtering functionality.

**Listing all channels for an account**

Here's an example:

````graphql
{
  actor {
    account(id: YOUR_ACCOUNT_ID) {
      aiNotifications {
        channels {
          entities {
            id
            name
          }
          error {
            details
          }
        }
      }
    }
  }
}
```

````

**Paginating through channels with cursor pagination**

In order to paginate through your channels, you must request the `nextCursor` field on your initial query.

With cursor pagination, you continue to make a request through the result set until the `nextCursor` that is returned from the response comes back empty. This signifies that you reached the end of your results.

Here's an example:

````graphql
{
  actor {
    account(id: YOUR_ACCOUNT_ID) {
      aiNotifications {
        channels(cursor: "") {
          nextCursor
          entities {
            id
            name
          }
          totalCount
        }
      }
    }
  }
}
```

The code above returns a set of results like this:

```json
{
  "data": {
    "actor": {
      "account": {
        "aiNotifications": {
          "channels": {
            "nextCursor": "/8o0y2qiR54m6thkdgHgwg==:jZTXDFKbTkhKwvMx+CtsPVM=",
            "entities": [
              {
                "id": "01c0cbe7-3d70-47c1-99e0-adf906eed6c2",
                "name": "Channel Name"
              },
              {
                "id": "05db0207-c137-4985-8cb5-f21e7e57b8cc",
                "name": "Another Channel Name"
              }
              // ... more channels here in reality
            ],
            "totalCount": 807
          }
        }
      }
    }
  }
}
```

So, in your subsequent request, provide the cursor like so, until the cursor is empty:

```graphql
{
  actor {
    account(id: YOUR_ACCOUNT_ID) {
      aiNotifications {
        channels(cursor: "/8o0y2qiR54m6thkdgHgwg==:jZTXDFKbTkhKwvMx+CtsPVM=") {
          nextCursor
          entities {
            id
            name
          }
          totalCount
        }
      }
    }
  }
}
```

````

**Find all channels by name**

The API allows channel queries by name. The `name` filter returns exact matches and partial matches. It's case insensitive. This will only return the information for the channels that match the name supplied.

In this example, we want to find channels with `"DevOps"` in the name:

````graphql
{
  actor {
    account(id: YOUR_ACCOUNT_ID) {
      aiNotifications {
        channels(filters: {
          name: "DevOps"
        }) {
          entities {
            id
            name
          }
        }
      }
    }
  }
}
```

````

**Find channel by id**

The API lets you query by channel ID:

````graphql
{
  actor {
    account(id: YOUR_ACCOUNT_ID) {
      aiNotifications {
        channels(filters: {id: YOUR_CHANNEL_ID}) {
          entities {
            id
            name
          }
        }
      }
    }
  }
}
```

````

**Find all channels by destination id**

The API lets you query channels by destination ID:

````graphql
{
  actor {
    account(id: YOUR_ACCOUNT_ID) {
      aiNotifications {
        channels(filters: {destinationId: YOUR_DESTINATION_ID}) {
          entities {
            id
            name
          }
        }
      }
    }
  }
}
```

````

**Find all channels by type**

The API lets you query by channel type. The following query will return all email channels on the chosen account:

````graphql
{
  actor {
    account(id: YOUR_ACCOUNT_ID) {
      aiNotifications {
        channels(filters: {type: EMAIL}) {
          entities {
            id
            name
          }
        }
      }
    }
  }
}
```

````

## Create a channel [#create-channel]

In order to create a channel, different inputs must be supplied for each channel type. Each channel is connected to a destination. For information on destinations, see the [NerdGraph tutorial on destinations](https://docs.newrelic.com/docs/apis/nerdgraph/examples/nerdgraph-api-notifications-destinations).

The best practice is to use the `channelSchema` endpoint to see which fields must be sent under `properties` like so:

```graphql
{
  actor {
    account(id: YOUR_ACCOUNT_ID) {
      aiNotifications {
        channelSchema(
          channelType: CHANNEL_TYPE,
          destinationId: YOUR_DESTINATION_ID,
          product:  YOUR_PRODUCT,
          constraints: []
        ) {
          schema {
            fields {
              mandatory
              label
              key
              component
            }
          }
          result
        }
      }
    }
  }
}
```

**Atlassian Jira**

Jira is a configurable ticketing system, and therefore there's no static way to create this channel.

There are two static fields - `project` and `issuetype`.

Fetch the `project` suggestions, and use one of the values as the constraint for `issuetype`, as shown here:

````graphql
{
  actor {
    account(id: YOUR_ACCOUNT_ID) {
      aiNotifications {
        channelSuggestions(
          channelType: JIRA_CLASSIC,
          destinationId: YOUR_DESTINATION_ID,
          key: FIELD_NAME
          constraints: [
            {
              key: "project",
              value: YOUR_PROJECT_VALUE
            }
          ]
        ) {
          entities {
            value
          }
          error
        }
      }
    }
  }
}
```

The chosen values will be used as constraints to fetch the schema:

```graphql
{
  actor {
    account(id: YOUR_ACCOUNT_ID) {
      aiNotifications {
        channelSchema(
          channelType: JIRA_CLASSIC,
          destinationId: YOUR_DESTINATION_ID,
          product:  YOUR_PRODUCT,
          constraints: [
            {
              key: "project",
              value: YOUR_PROJECT_VALUE
            },
            {
              key: "issuetype",
              value: YOUR_ISSUE_TYPE_VALUE
            }
          ]
        ) {
          schema {
            fields {
              mandatory
              label
              key
              component
            }
          }
          result
        }
      }
    }
  }
}
```

After you've fetched each field and chosen a value from the suggestions or as free text, you can create a channel:

```graphql
mutation {
  aiNotificationsCreateChannel(accountId: YOUR_ACCOUNT_ID, channel: {
    type: JIRA,
    name: "Channel Name",
    destinationId: YOUR_DESTINATION_ID,
    product: YOUR_PRODUCT,
    properties: [
      {
        key: YOUR_FIELD_NAME,
        value: YOUR_FIELD_NAME,
      },
      // ... And so forth with the rest of the fields
    ]
  }) {
    channel {
      id
      name
    }
  }
}
```

````

**ServiceNow (Incident-Management)**

ServiceNow is a configurable ticketing system, and therefore there's no static way to create this channel.

The schema must be fetched like shown above, then each field must be filled with free text or by using suggestions:

````graphql
{
  actor {
    account(id: YOUR_ACCOUNT_ID) {
      aiNotifications {
        channelSchema(
          channelType: SERVICE_NOW,
          destinationId: YOUR_DESTINATION_ID,
          product:  YOUR_PRODUCT,
          constraints: []
        ) {
          schema {
            fields {
              mandatory
              label
              key
              component
            }
          }
          result
        }
      }
    }
  }
}
```

After you've fetched each field and chosen a value from the suggestions or as free text, you can create a channel:

```graphql
mutation {
  aiNotificationsCreateChannel(accountId: YOUR_ACCOUNT_ID, channel: {
    type: SERVICE_NOW,
    name: "Channel Name",
    destinationId: YOUR_DESTINATION_ID,
    product: YOUR_PRODUCT,
    properties: [
      {
        key: YOUR_FIELD_NAME,
        value: YOUR_FIELD_NAME,
      },
      // ... And so forth with the rest of the fields
    ]
  }) {
    channel {
      id
      name
    }
  }
}
```

````

**Slack**

````graphql
mutation {
  aiNotificationsCreateChannel(accountId: YOUR_ACCOUNT_ID, channel: {
    type: SLACK,
    name: "Channel Name",
    destinationId: YOUR_DESTINATION_ID,
    product: YOUR_PRODUCT,
    properties: [
      {
        key: "channelId",
        value: YOUR_SLACK_CHANNEL_ID
      }
    ]
  }) {
    channel {
      id
      name
    }
  }
}
```

````

**Microsoft Teams**

> #### 💡 NOTE
>
> The Microsoft Teams integration is now available in the US, EU, and JP regions.

### Prerequisites

Before configuring New Relic to send notifications to Microsoft Teams, you must:

-   Have an existing Microsoft Teams channel where you want to receive notifications.
-   Create a [Microsoft Teams destination](https://docs.newrelic.com/docs/apis/nerdgraph/examples/nerdgraph-api-notifications-destinations/#microsoft-teams) in New Relic and obtain the `destinationId`.

    ### Step 1: Fetch available Team IDs

    > #### 💡 TIP
    >
    > If you already know your Team ID and Channel ID, you can skip Steps 1 and 2 and go directly to [Step 3](#step-3-configure-the-new-relic-notification-channel) to configure the notification channel.

    This query discovers which Microsoft Teams are accessible through your destination. You provide the `destinationId` and specify that you want Team IDs (via `key: "teamId"`), and the API returns a list of available teams with their names and IDs:

    ```graphql
    {
      actor {
        account(id: YOUR_ACCOUNT_ID) {
          aiNotifications {
            suggestions(
              destinationId: YOUR_DESTINATION_ID,
              key: "teamId",
              channelType: MICROSOFT_TEAMS,
              constraints: []
            ) {
              entities {
                displayValue
                value
              }
              errors {
                description
                details
                type
              }
            }
          }
        }
      }
    }
    ```

    The response will contain a list of teams with their display names and unique Team IDs:

    ```json
    {
      "data": {
        "actor": {
          "account": {
            "aiNotifications": {
              "suggestions": {
                "entities": [
                  {
                    "displayValue": "Engineering Team",
                    "value": "389e7f6c-xxxx-47f0-aa77-xxxxxxxxxxxx"
                  },
                  {
                    "displayValue": "DevOps Team",
                    "value": "834dc358-xxxx-4445-9938-xxxxxxxxxxxx"
                  }
                ],
                "errors": []
              }
            }
          }
        }
      }
    }
    ```

    > #### 💡 TIP
    >
    > If you don't see the team you're looking for in the results, you can use the `filter` parameter to search for it by name:
    >
    > ```graphql
    > {
    >   actor {
    >     account(id: YOUR_ACCOUNT_ID) {
    >       aiNotifications {
    >         suggestions(
    >           destinationId: YOUR_DESTINATION_ID,
    >           key: "teamId",
    >           channelType: MICROSOFT_TEAMS,
    >           constraints: [],
    >           filter: {
    >             type: CONTAINS,
    >             value: "Engineering"
    >           }
    >         ) {
    >           entities {
    >             displayValue
    >             value
    >           }
    >         }
    >       }
    >     }
    >   }
    > }
    > ```

    ### Step 2: Fetch available Channel IDs for a Team

    Once you have a Team ID from Step 1, this query discovers which channels exist within that specific team. You provide the `destinationId` and the `teamId` (as a constraint), and the API returns a list of available channels with their names and IDs:

    ```graphql
    {
      actor {
        account(id: YOUR_ACCOUNT_ID) {
          aiNotifications {
            suggestions(
              destinationId: YOUR_DESTINATION_ID,
              key: "channelId",
              channelType: MICROSOFT_TEAMS,
              constraints: [
                {
                  key: "teamId",
                  value: "YOUR_TEAM_ID"
                }
              ]
            ) {
              entities {
                displayValue
                value
              }
              errors {
                description
                details
                type
              }
            }
          }
        }
      }
    }
    ```

    The response will contain a list of channels within the specified team:

    ```json
    {
      "data": {
        "actor": {
          "account": {
            "aiNotifications": {
              "suggestions": {
                "entities": [
                  {
                    "displayValue": "General",
                    "value": "19:xxxxxxxxxxxxxxxxxxxxxxxx@thread.tacv2"
                  },
                  {
                    "displayValue": "Alerts",
                    "value": "19:yyyyyyyyyyyyyyyyyyyyyyyy@thread.tacv2"
                  }
                ],
                "errors": []
              }
            }
          }
        }
      }
    }
    ```

    > #### 💡 TIP
    >
    > Similar to Team IDs, you can filter channels by name using the `filter` parameter to search within the specified team.

    ### Step 3: Configure the New Relic notification channel

    After obtaining both the Team ID and Channel ID, configure the New Relic notification channel to send alerts to your Microsoft Teams channel.

    > #### ⚠️ IMPORTANT
    >
    > This mutation creates a New Relic notification channel object that connects to an **existing** Microsoft Teams channel. The Teams channel must already exist in your Microsoft Teams workspace. This API does not create new teams or channels within Microsoft Teams itself - it only configures New Relic to send notifications to your existing Teams channels.

    ```graphql
    mutation {
      aiNotificationsCreateChannel(accountId: YOUR_ACCOUNT_ID, channel: {
        type: MICROSOFT_TEAMS,
        name: "Channel Name",
        destinationId: YOUR_DESTINATION_ID,
        product: YOUR_PRODUCT,
        properties: [
          {
            key: "teamId",
            value: YOUR_TEAM_ID
          },
          {
            key: "channelId",
            value: YOUR_CHANNEL_ID
          }
        ]
      }) {
        channel {
          id
          name
        }
      }
    }
    ```

    The `product` parameter specifies the New Relic product generating the notification. Valid values include:


-   `IINT` - Applied Intelligence (Incident Intelligence)
-   `ALERTS`
-   `ERROR_TRACKING`
-   `APM` - Application Performance Monitoring
-   `CHANGE_TRACKING`
-   `SECURITY`
-   `PD` - Proactive Detection
-   Other values: `CSSP`, `DISCUSSIONS`, `NTFC`, `SHARING`

**Webhook**

The `payload` property is the payload that will be sent in the notification. It uses the handlebars syntax to dynamically insert information from the request.

````graphql
mutation {
  aiNotificationsCreateChannel(accountId: YOUR_ACCOUNT_ID, channel: {
    type: WEBHOOK,
    name: "Channel Name",
    destinationId: YOUR_DESTINATION_ID,
    product: YOUR_PRODUCT,
    properties: [
      {
      key:"payload",
      value: "{\"key\":\"value\"}"}
    ]
  }) {
    channel {
      id
      name
    }
  }
}
```

````

**Email**

````graphql
mutation {
  aiNotificationsCreateChannel(accountId: YOUR_ACCOUNT_ID, channel: {
    type: EMAIL,
    name: "Channel Name",
    destinationId: YOUR_DESTINATION_ID,
    product: YOUR_PRODUCT,
    properties: []
  }) {
    channel {
      id
      name
    }
  }
}
```

````

**AWS EventBridge**

The `eventSource` must be the full url for an existing event source.
The `eventContent` is the payload that will be sent in the body of the notification, as shown here:

````graphql
mutation {
  aiNotificationsCreateChannel(accountId: YOUR_ACCOUNT_ID, channel: {
    type: EVENT_BRIDGE,
    name: "Channel Name",
    destinationId: YOUR_DESTINATION_ID,
    product: YOUR_PRODUCT,
    properties: [
      {
        key: "eventSource",
        value:  YOUR_AWS_EVENT_SOURCE
      },
      {
        key: "eventContent",
        value:  YOUR_EVENT_CONTENT/var>
      }
    ]
  }) {
    channel {
      id
      name
    }
  }
}
```

````

**PagerDuty**

PagerDuty has two types of integrations, service level and account level. For more information see the [PagerDuty integration docs](https://docs.newrelic.com/docs/alerts-applied-intelligence/notifications/notification-integrations#pagerduty).

Service level:

````graphql
mutation {
  aiNotificationsCreateChannel(accountId: YOUR_ACCOUNT_ID, channel: {
    type: PAGERDUTY_SERVICE_INTEGRATION,
    name: "Channel Name",
    destinationId: YOUR_DESTINATION_ID,
    product: YOUR_PRODUCT,
    properties: [
      {
        key: "summary",
        value: YOUR_PAGE_SUMMARY
      }
    ]
  }) {
    channel {
      id
      name
    }
  }
}
```

Account level:

```graphql
mutation {
  aiNotificationsCreateChannel(accountId: YOUR_ACCOUNT_ID, channel: {
    type: PAGERDUTY_ACCOUNT_INTEGRATION,
    name: "Channel Name",
    destinationId: YOUR_DESTINATION_ID,
    product: YOUR_PRODUCT,
    properties: [
      {
        key: "summary",
        value: YOUR_PAGE_SUMMARY
      },
      {
        key: "email",
        value: EMAIL_OF_PD_USER
      },
      {
        key: "service",
        value: YOUR_PD_SERVICE_ID
      }
    ]
  }) {
    channel {
      id
      name
    }
  }
}
```

````

## Update a channel [#update-channel]

When you update a channel, note that you don't need to supply all of the attributes on the channel. For example, if you only want to update the name, that's the only attribute you need to update, as shown here:

```graphql
mutation {
  aiNotificationsUpdateChannel(accountId: YOUR_ACCOUNT_ID, channelId: YOUR_CHANNEL_ID, channel: {
    name: "Updated channel Name"
  }) {
    channel {
      id
      name
    }
  }
}
```

## Testing a channel [#test-channel]

You can test channels via the NerdGraph API. This can be done before or after creating the channel.

```graphql
mutation {
  aiNotificationsTestChannel(accountId: YOUR_ACCOUNT_ID, channel: {
    type: PAGERDUTY_SERVICE_INTEGRATION,
    name: "Channel Name",
    properties: [
      {
        key: "summary",
        value: YOUR_PAGE_SUMMARY
      }
    ]
  }) {
    error {
      details
    }
    details
    result
  }
}

```

```graphql
mutation {
  aiNotificationsTestChannelById(accountId: YOUR_ACCOUNT_ID, channelId: YOUR_CHANNEL_ID) {
    error {
      details
    }
    details
    result
  }
}
```

## Delete a channel [#delete-channel]

You can delete channels via the NerdGraph API.

```graphql
mutation {
  aiNotificationsDeleteChannel(accountId: YOUR_ACCOUNT_ID, channelId: YOUR_CHANNEL_ID) {
    ids
    error {
      details
    }
  }
}
```