---
title: NerdGraph tutorial: Alert notification channels (deprecated)
source: https://docs.newrelic.com/docs/apis/nerdgraph/examples/nerdgraph-api-alert-notification-channels
---

For New Relic alerting, you can manage your [alert notification channels](https://docs.newrelic.com/docs/alerts-applied-intelligence/new-relic-alerts/alert-notifications/notification-channels-control-where-send-alerts) using our NerdGraph API. For how to manage alert notifications, see the [NerdGraph tutorial on destinations](https://docs.newrelic.com/docs/apis/nerdgraph/examples/nerdgraph-api-notifications-destinations).

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

## Get notification channels [#get-channels]

The `notificationChannels` query allows you to paginate through all of your [alerting notification channels](https://docs.newrelic.com/docs/alerts-applied-intelligence/new-relic-alerts/alert-notifications/notification-channels-control-where-send-alerts) per account. You can also use the `notificationChannel` query to get a specific notification channel by its ID.

> #### 💡 TIP
>
> Note that certain secret fields (for example, passwords or API keys) are obfuscated in the returned fields.

**List all notification channels for an account**

This example returns every field for every notification channel on the supplied account ID, up to the page limit of 200. Note how we use [inline fragments][inline-fragments] to refer to the specific fields on the concrete types implementing the `AlertsNotificationChannel` interface.

````graphql
{
  actor {
    account(id: YOUR_ACCOUNT_ID) {
      alerts {
        notificationChannels {
          channels {
            id
            name
            type
            ... on AlertsXMattersNotificationChannel {
              config {
                integrationUrl
              }
            }
            ... on AlertsWebhookNotificationChannel {
              config {
                baseUrl
                basicAuth {
                  password
                  username
                }
                customHttpHeaders {
                  name
                  value
                }
                customPayloadBody
                customPayloadType
              }
            }
            ... on AlertsVictorOpsNotificationChannel {
              config {
                key
                routeKey
              }
            }
            ... on AlertsUserNotificationChannel {
              config {
                userId
              }
            }
            ... on AlertsSlackNotificationChannel {
              config {
                teamChannel
                url
              }
            }
            ... on AlertsPagerDutyNotificationChannel {
              config {
                apiKey
              }
            }
            ... on AlertsOpsGenieNotificationChannel {
              config {
                apiKey
                dataCenterRegion
                recipients
                tags
                teams
              }
            }
            ... on AlertsHipChatNotificationChannel {
              config {
                authToken
                baseUrl
                roomId
              }
            }
            ... on AlertsEmailNotificationChannel {
              config {
                emails
                includeJson
              }
            }
            ... on AlertsCampfireNotificationChannel {
              config {
                room
                subdomain
                token
              }
            }
          }
          totalCount
          nextCursor
        }
      }
    }
  }
}
```

````

**Paginate through notification channels with cursor pagination**

If a given account's list of notification channels exceeds the 200 channel page limit, you can use the pagination cursor to retrieve additional pages.

With cursor pagination, you continue to request additional pages using the `nextCursor` until that field returns empty in the response. An empty `nextCursor` signals that you have reached the end of the result set.

Here's an example:

````graphql
{
  actor {
    account(id: YOUR_ACCOUNT_ID) {
      alerts {
        notificationChannels {
          channels {
            id
            name
            type
          }
          totalCount
          nextCursor
        }
      }
    }
  }
}
```

The code above returns a set of results like this:

```json
{
  "data": {
    "actor": {
      "account": {
        "alerts": {
          "notificationChannels": {
            "channels": [
              {
                "id": "250",
                "name": "Channel 1",
                "type": "SLACK"
              },
              {
                "id": "713",
                "name": "Channel 2",
                "type": "WEBHOOK"
              },
              // ... +198 more notification channels in reality
            ],
            "nextCursor": "Wh4LK9JYzfACVlNkyvf7Rg==:I5VbSEpgx3UWNA5AOVsUPv4=",
            "totalCount": 268
          }
        }
      }
    }
  }
}
```

In your next request, provide the cursor like so, updating each subsequent request to return the updated cursor, until the cursor is empty:

```graphql
{
  actor {
    account(id: YOUR_ACCOUNT_ID) {
      alerts {
        notificationChannels(cursor: "Wh4LK9JYzfACVlNkyvf7Rg==:I5VbSEpgx3UWNA5AOVsUPv4=") {
          channels {
            id
            name
            type
          }
          totalCount
          nextCursor
        }
      }
    }
  }
}
```

````

**Find a specific notification channel by id**

If you have a specific notification channel's ID, the API allows you to look it up directly. Note that because the specific channel is a concrete type implementing the `AlertsNotificationChannel` interface, you may need to specify certain fields using the `... on` syntax for [inline fragments][inline-fragments].

In this example, we are retrieving a Slack channel:

````graphql
{
  actor {
    account(id: YOUR_ACCOUNT_ID) {
      alerts {
        notificationChannel(id: YOUR_CHANNEL_ID) {
          id
          name
          type
          ... on AlertsSlackNotificationChannel {
            config {
              teamChannel
              url
            }
          }
        }
      }
    }
  }
}
```

````

**List notification channels with their associated policies**

This example returns the ID, name, and type for every notification channel on the supplied account ID, as well as a list of every policy that is associated with that channel.

````graphql
{
  actor {
    account(id: YOUR_ACCOUNT_ID) {
      alerts {
        notificationChannels {
          channels {
            id
            name
            type
            associatedPolicies {
              policies {
                id
                name
              }
              totalCount
            }
          }
          nextCursor
          totalCount
        }
      }
    }
  }
}
```

````

## Create a notification channel [#create-channel]

In order to create an alert notification channel, you need to know the specific type of notification channel you want to create (for example email, Slack, etc.), as well as the details necessary to configure it (which will depend on the channel type). Once a notification channel has been created, it can be associated with one or more [alert policies][alert-policies]. Once associated, those channels will receive notifications from those policies when conditions are breached.

> #### ⚠️ CAUTION
>
> While you can query for any existing notification channel type, you can only create a subset of them. Specifically, the **user** channel type has no editable fields, and the **Campfire** and **HipChat** channel types are both deprecated.

**Create an email notification channel**

An example create mutation for an email notification channel:

````graphql
mutation {
  alertsNotificationChannelCreate(accountId: YOUR_ACCOUNT_ID, notificationChannel: {
    email: {
      emails: [ "email@example.com" ],
      includeJson: true,
      name: "Some Name <email@example.com>"
    }
  }) {
    notificationChannel {
      ... on AlertsEmailNotificationChannel {
        id
        name
        type
        config {
          emails
          includeJson
        }
      }
    }
    error {
      description
      errorType
    }
  }
}
```

````

**Create an OpsGenie notification channel**

An example create mutation for an OpsGenie notification channel:

````graphql
mutation {
  alertsNotificationChannelCreate(accountId: YOUR_ACCOUNT_ID, notificationChannel: {
    opsGenie: {
      apiKey: "api-key-from-opsgenie",
      dataCenterRegion: US,
      name: "OpsGenie notification channel name",
      recipients: [ "user@example.com" ],
      tags: [ "tag1", "tag2" ],
      teams: [ "team1", "team2" ]
    }
  }) {
    notificationChannel {
      ... on AlertsOpsGenieNotificationChannel {
        id
        name
        type
        config {
          apiKey
          teams
          tags
          recipients
          dataCenterRegion
        }
      }
    }
    error {
      description
      errorType
    }
  }
}
```

````

**Create a PagerDuty notification channel**

An example create mutation for a PagerDuty notification channel:

````graphql
mutation {
  alertsNotificationChannelCreate(accountId: YOUR_ACCOUNT_ID, notificationChannel: {
    pagerDuty: {
      name: "PagerDuty notification channel name",
      apiKey: "api-key-from-pagerduty"
    }
  }) {
    notificationChannel {
      ... on AlertsPagerDutyNotificationChannel {
        id
        name
        type
        config {
          apiKey
        }
      }
    }
    error {
      description
      errorType
    }
  }
}
```

````

**Create a Slack notification channel**

An example create mutation for a Slack notification channel:

````graphql
mutation {
  alertsNotificationChannelCreate(accountId: YOUR_ACCOUNT_ID, notificationChannel: {
    slack: {
      name: "Slack notification channel name",
      teamChannel: "#team-channel",
      url: "https://hooks.slack.com/services/FAKE/MOREFAKE/IMAGINARYEXAMPLEURLCHUNK"
    }
  }) {
    notificationChannel {
      ... on AlertsSlackNotificationChannel {
        id
        name
        type
        config {
          teamChannel
          url
        }
      }
    }
    error {
      description
      errorType
    }
  }
}
```

````

**Create a VictorOps notification channel**

An example create mutation for a VictorOps notification channel:

````graphql
mutation {
  alertsNotificationChannelCreate(accountId: YOUR_ACCOUNT_ID, notificationChannel: {
    victorOps: {
      key: "example-api-key-from-victorops",
      name: "VictorOps notification channel name",
      routeKey: "example-route-key"
    }
  }) {
    notificationChannel {
      ... on AlertsVictorOpsNotificationChannel {
        id
        name
        type
        config {
          key
          routeKey
        }
      }
    }
    error {
      description
      errorType
    }
  }
}
```

````

**Create a Webhook notification channel**

An example create mutation for a Webhook notification channel:

````graphql
mutation {
  alertsNotificationChannelCreate(
    accountId: YOUR_ACCOUNT_ID
    notificationChannel: {
      webhook: {
        baseUrl: "https://example.com/webhook"
        basicAuth: {
          password: "t0t4lly-s3cr3t-p455w0rd"
          username: "webhook-user"
        }
        customHttpHeaders: [
          { name: "X-Api-Key", value: "100%-real-api-key" }
          { name: "X-Calling-Service", value: "New Relic Alerts" }
        ]
        customPayloadBody: "{ \"account_id\": \"$ACCOUNT_ID\", \"account_name\": \"$ACCOUNT_NAME\", \"closed_violations_count_critical\": \"$CLOSED_VIOLATIONS_COUNT_CRITICAL\", \"closed_violations_count_warning\": \"$CLOSED_VIOLATIONS_COUNT_WARNING\", \"condition_description\": \"$DESCRIPTION\", \"condition_family_id\": \"$CONDITION_FAMILY_ID\", \"condition_name\": \"$CONDITION_NAME\", \"current_state\": \"$EVENT_STATE\", \"details\": \"$EVENT_DETAILS\", \"duration\": \"$DURATION\", \"event_type\": \"$EVENT_TYPE\", \"incident_acknowledge_url\": \"$INCIDENT_ACKNOWLEDGE_URL\", \"incident_id\": \"$INCIDENT_ID\", \"incident_url\": \"$INCIDENT_URL\", \"metadata\": \"$METADATA\", \"open_violations_count_critical\": \"$OPEN_VIOLATIONS_COUNT_CRITICAL\", \"open_violations_count_warning\": \"$OPEN_VIOLATIONS_COUNT_WARNING\", \"owner\": \"$EVENT_OWNER\", \"policy_name\": \"$POLICY_NAME\", \"policy_url\": \"$POLICY_URL\", \"runbook_url\": \"$RUNBOOK_URL\", \"severity\": \"$SEVERITY\", \"targets\": \"$TARGETS\", \"timestamp\": \"$TIMESTAMP\", \"timestamp_utc_string\": \"$TIMESTAMP_UTC_STRING\", \"violation_callback_url\": \"$VIOLATION_CALLBACK_URL\", \"violation_chart_url\": \"$VIOLATION_CHART_URL\" }"
        customPayloadType: JSON
        name: "Webhook notification channel name"
      }
    }
  ) {
    notificationChannel {
      ... on AlertsWebhookNotificationChannel {
        id
        name
        type
        config {
          customPayloadType
          customPayloadBody
          customHttpHeaders {
            value
            name
          }
          basicAuth {
            password
            username
          }
          baseUrl
        }
      }
    }
    error {
      description
      errorType
    }
  }
}
```

````

**Create an xMatters notification channel**

An example create mutation for an xMatters notification channel:

````graphql
mutation {
  alertsNotificationChannelCreate(accountId: YOUR_ACCOUNT_ID, notificationChannel: {
    xMatters: {
      integrationUrl: "https://company.instance.xmatters.com/api/xm/v<version>/...",
      name: "xMatters notification channel name"
    }
  }) {
    notificationChannel {
      ... on AlertsXMattersNotificationChannel {
        id
        name
        type
        config {
          integrationUrl
        }
      }
    }
    error {
      description
      errorType
    }
  }
}
```

````

## Update a notification channel [#update-channel]

In order to update an alert notification channel, you need to know the specific type of notification channel you want to change (for example email, Slack, etc.), as well as the details necessary to configure it (which will depend on the channel type). Consistent with other GraphQL APIs, you can update a single field on the channel without knowing anything other than the channel's ID.

> #### ⚠️ CAUTION
>
> While you can query for any existing notification channel type, you can only update a subset of them. Specifically, the **user** channel type has no editable fields, and the **Campfire** and **HipChat** channel types are both deprecated.

**Update an email notification channel**

An example update mutation for an email notification channel where we're updating only the name:

````graphql
mutation {
  alertsNotificationChannelUpdate(accountId: YOUR_ACCOUNT_ID, id: YOUR_CHANNEL_ID, notificationChannel: {
    email: {
      name: "Updated Name <email@example.com>"
    }
  }) {
    notificationChannel {
      ... on AlertsEmailNotificationChannel {
        id
        name
        type
      }
    }
    error {
      description
      errorType
      notificationChannelId
    }
  }
}
```

````

**Update an OpsGenie notification channel**

An example update mutation for an OpsGenie notification channel where we're updating only the name:

````graphql
mutation {
  alertsNotificationChannelUpdate(accountId: YOUR_ACCOUNT_ID, id: YOUR_CHANNEL_ID, notificationChannel: {
    opsGenie: {
      name: "OpsGenie updated channel name"
    }
  }) {
    notificationChannel {
      ... on AlertsOpsGenieNotificationChannel {
        id
        name
        type
      }
    }
    error {
      description
      errorType
      notificationChannelId
    }
  }
}
```

````

**Update a PagerDuty notification channel**

An example update mutation for a PagerDuty notification channel where we're updating only the name:

````graphql
mutation {
  alertsNotificationChannelUpdate(accountId: YOUR_ACCOUNT_ID, id: YOUR_CHANNEL_ID, notificationChannel: {
    pagerDuty: {
      name: "PagerDuty updated channel name"
    }
  }) {
    notificationChannel {
      ... on AlertsPagerDutyNotificationChannel {
        id
        name
        type
      }
    }
    error {
      description
      errorType
      notificationChannelId
    }
  }
}
```

````

**Update a Slack notification channel**

An example update mutation for a Slack notification channel where we're updating only the name:

````graphql
mutation {
  alertsNotificationChannelUpdate(accountId: YOUR_ACCOUNT_ID, id: YOUR_CHANNEL_ID, notificationChannel: {
    slack: {
      name: "Slack updated channel name"
    }
  }) {
    notificationChannel {
      ... on AlertsSlackNotificationChannel {
        id
        name
        type
      }
    }
    error {
      description
      errorType
      notificationChannelId
    }
  }
}
```

````

**Update a VictorOps notification channel**

An example update mutation for a VictorOps notification channel where we're updating only the name:

````graphql
mutation {
  alertsNotificationChannelUpdate(accountId: YOUR_ACCOUNT_ID, id: YOUR_CHANNEL_ID, id: YOUR_CHANNEL_ID, notificationChannel: {
    victorOps: {
      name: "VictorOps updated channel name"
    }
  }) {
    notificationChannel {
      ... on AlertsVictorOpsNotificationChannel {
        id
        name
        type
      }
    }
    error {
      description
      errorType
      notificationChannelId
    }
  }
}
```

````

**Update a Webhook notification channel**

An example update mutation for a Webhook notification channel where we're updating only the name:

````graphql
mutation {
  alertsNotificationChannelUpdate(accountId: YOUR_ACCOUNT_ID, id: YOUR_CHANNEL_ID, notificationChannel: {
    webhook: {
      name: "Webhook updated channel name"
    }
  }) {
    notificationChannel {
      ... on AlertsWebhookNotificationChannel {
        id
        name
        type
      }
    }
    error {
      description
      errorType
      notificationChannelId
    }
  }
}
```

````

**Update an xMatters notification channel**

An example update mutation for an xMatters notification channel where we're updating only the name:

````graphql
mutation {
  alertsNotificationChannelUpdate(accountId: YOUR_ACCOUNT_ID, id: YOUR_CHANNEL_ID, notificationChannel: {
    xMatters: {
      name: "xMatters updated channel name"
    }
  }) {
    notificationChannel {
      ... on AlertsXMattersNotificationChannel {
        id
        name
        type
      }
    }
    error {
      description
      errorType
      notificationChannelId
    }
  }
}
```

````

## Delete a notification channel [#delete-channel]

You can delete a notification channel with only the account ID and the channel ID. Note that deleting a channel dissociates it from all policies, meaning that no further notifications will be sent to that channel.

```graphql
mutation {
  alertsNotificationChannelDelete(
    accountId: YOUR_ACCOUNT_ID,
    id: YOUR_CHANNEL_ID
  ) {
    id
    error {
      description
      errorType
      notificationChannelId
    }
  }
}
```

## Associate channels to a policy [#associate-channel]

Creating an alert notification channel is not enough: Once the channel has been created, it needs to be associated to one or more [policies][alert-policies]. Once associated to a policy, the channel can receive alert notifications when conditions on that policy exceed the threshold.

In this example, we associate two channels with a policy:

```graphql
mutation {
  alertsNotificationChannelsAddToPolicy(
    accountId: YOUR_ACCOUNT_ID,
    notificationChannelIds: [ FIRST_CHANNEL_ID, SECOND_CHANNEL_ID ],
    policyId: YOUR_POLICY_ID
  ) {
    notificationChannels {
      id
    }
    policyId
    errors {
      description
      errorType
      notificationChannelId
    }
  }
}
```

## Dissociate a channel from a policy [#dissociate-channel]

In those instances where a notification channel has outlived its usefulness (for example, an email list that has been retired), the time has come to dissociate that channel from the [policy][alert-policies] (or policies) that are sending alert notifications to it. This API call leaves the channel itself intact, but removes it from the specified policy.

In this example, we are removing two channels from a policy (leaving any others in place), and getting back confirmation that those two channel IDs have been removed:

```graphql
mutation {
  alertsNotificationChannelsRemoveFromPolicy(
    accountId: YOUR_ACCOUNT_ID,
    notificationChannelIds: [ FIRST_CHANNEL_ID, SECOND_CHANNEL_ID ],
    policyId: YOUR_POLICY_ID
  ) {
    notificationChannels {
      id
    }
    policyId
    errors {
      description
      errorType
      notificationChannelId
    }
  }
}
```

> #### 💡 TIP
>
> Removing an alert notification channel from a policy **does not** delete the channel because it might be used by other policies. On the other hand, deleting a channel will cause all associated policies to stop sending alert notifications to that channel.