# Get a notification channel

`GET /api/v1/notification-channels/{channel}`

Retrieve one channel and what it still needs.

Read needs_destination and requires_proof against destination and is_proven to work out what is left to do before is_enabled can be set.

This endpoint also answers QUERY, with the same parameters sent in the request body. [How QUERY works](https://my.monicahq.com/docs/api/query-method).

## Path parameters

- `channel` (string, required): Which channel: in_app, email, telegram or sms. Anything else answers 404.

## Returns

One channel. A channel name the product does not know answers 404.

- `data` (object): The channel.
- `data.type` (string): Always notification_channel. It names the kind of record, so a caller holding several kinds can tell them apart without looking at where they came from.
- `data.id` (string): The id of this record, as a string even when it reads as a number. It is what every endpoint naming this record takes.
- `data.attributes` (object): Everything the record holds.
- `data.attributes.channel` (string): Which channel this is: in_app, email, telegram or sms. It also stands for the id of the record, so this is what goes in the path.
- `data.attributes.label` (string): What the channel is called, in the language you asked in.
- `data.attributes.is_enabled` (boolean): Whether the account wants anything to go out this way. A channel can be switched on only once everything below is satisfied.
- `data.attributes.destination` (string): Where messages go: the room, the conversation or the number, up to 255 characters, or null when the channel asks for none or none has been given.
- `data.attributes.needs_destination` (boolean): Whether this channel has to be told where to send. Email does not, because the address is already on you.
- `data.attributes.discovers_destination` (boolean): Whether the service hands us the destination rather than the account typing it. True for Telegram, where the account opens a conversation with the bot and the bot tells us which one it is. A destination sent for such a channel is refused.
- `data.attributes.requires_proof` (boolean): Whether the destination has to be proved before the channel may be switched on. True only for channels that accept a wrong destination without complaint, which today means text messages.
- `data.attributes.is_proven` (boolean): Whether it has been proved. Always true for a channel with nothing to prove.
- `data.attributes.is_configured_on_the_instance` (boolean): Whether this particular server has been set up to send on the channel. False only for a channel whose provider account belongs to the instance, which today means Telegram and the text message. Switching on a channel that is false here answers 422.
- `data.attributes.disabled_reason` (string): Why the product switched the channel off itself, up to 255 characters, or null when it did not. Set when a channel refuses everything sent to it several times in a row.
- `data.attributes.can_send_proof_code` (boolean): Whether a code may be sent to the destination right now. False on a channel with nothing to prove, inside the wait after a send, and once every code allowed has been sent.
- `data.attributes.proof_code_refusal` (string): Why no code may be sent right now, in the words the settings screen prints, or null when one may.
- `data.links` (object): Where to find this record.
- `data.links.self` (string): The absolute address this record is read from.

## Rate limit

Sixty requests per minute, per user, shared by every key and device. Every answer carries the budget left in `X-RateLimit-Remaining`.

## Request

```sh
curl https://my.monicahq.com/api/v1/notification-channels/telegram \
  -H "Authorization: Bearer $MONICA_TOKEN"
```

```javascript
const response = await fetch('https://my.monicahq.com/api/v1/notification-channels/telegram', {
  headers: { Authorization: `Bearer ${token}` },
})
const data = await response.json()
```

```php
$response = Http::withToken($token)->get('https://my.monicahq.com/api/v1/notification-channels/telegram');
```

## Response

`200`

```json
{
    "data": {
        "type": "notification_channel",
        "id": "telegram",
        "attributes": {
            "channel": "telegram",
            "label": "Telegram",
            "is_enabled": true,
            "destination": "918273645",
            "needs_destination": true,
            "discovers_destination": true,
            "requires_proof": false,
            "is_proven": true,
            "is_configured_on_the_instance": true,
            "disabled_reason": null,
            "can_send_proof_code": false,
            "proof_code_refusal": "This channel says for itself whether a destination is wrong, so it has nothing to prove."
        },
        "links": {
            "self": "https://my.monicahq.com/api/v1/notification-channels/telegram"
        }
    }
}
```
