> ## Documentation Index
> Fetch the complete documentation index at: https://docs.impellabs.tech/llms.txt
> Use this file to discover all available pages before exploring further.

# Channels

> Where customers talk to agents, and who can read each channel.

A channel is one place where customers write to the business: a website chat, a mailbox, a phone number or a messaging account. A business connects each channel with its own account. See the [channels API](https://docs.impellabs.tech/api/channels.md).

## Kinds of channel

Each channel has a `kind`. Read the kinds on your server, what each supports and what its connect step needs with `GET /api/v1/channels/kinds`.

```bash theme={null}
curl https://api.impellabs.tech/api/v1/channels/kinds \
  -H "Authorization: Bearer YOUR_API_KEY"
```

Each entry has `kind`, `label`, `supports`, `window_hours`, `available` and `connect`.

## Connect a channel

The member who connects a channel owns it. They connect it with `POST /api/v1/channels/connect/{kind}`. The body depends on the kind. Some kinds ask for one more value, and then the answer is `409` with the `field` that is missing and a `pending_id`. Send `pending_id` and the value within 15 minutes to finish.

Credentials go in and never come back in a response.

## One agent answers

A channel has one agent that answers on it. Set it with `PATCH`:

```bash theme={null}
curl -X PATCH https://api.impellabs.tech/api/v1/channels/CHANNEL_ID \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"agent_id": "AGENT_ID"}'
```

Send `null` to unbind. With no agent, nobody answers yet.

## Who the agent answers

The `settings` of a channel say who the agent answers and how its replies feel. Send `PATCH` with a `settings` object. Only the keys you send change.

| Key | Meaning |
| - | - |
| `who` | `all`, `selected` (only the test addresses) or `rollout` (test addresses and `percent` of the others). |
| `test` | Customer addresses the agent always answers. Phone channels use E.164. |
| `percent` | 0 to 100. Used by `rollout`. The same customer always falls on the same side. |
| `reply_wait` | Seconds to wait for more lines before the agent answers. |
| `read_receipts`, `typing`, `rich` | On or off, where the channel supports them. |
| `keep_team`, `keep_team_days` | Keep customers the team wrote to before the agent went live with the team. |

A change to `who`, `test` or `percent` applies to new conversations.

## Who can read a channel

A channel is private to the member who connected it until they share it. Share it with chosen members, with departments or with everyone. Sharing sets who reads the conversations. It does not change who the agent answers.

```bash theme={null}
curl -X PATCH https://api.impellabs.tech/api/v1/channels/CHANNEL_ID \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"settings": {"sharing": {"mode": "people", "members": ["MEMBER_ID"], "departments": []}}}'
```

`mode` is `private`, `people` or `everyone`.

* Only the owner of the channel shares it with more people. A person who manages channels can narrow or stop sharing.
* A channel that was connected before sharing existed has no `sharing` value. Owners and admins can read it, as before.
* People who read a channel see the replies of the agent and its name. They do not see its instructions unless the agent is shared with them too. The channel response has `agent_hidden` for its owner when this is the case.

## Health

`GET /api/v1/channels/{channel_id}` returns `status`, `problem`, `health` and `checked_at`. Ask the provider again with `POST /api/v1/channels/{channel_id}/verify`. A `channel.status_changed` [event](https://docs.impellabs.tech/api/events.md) tells your systems when a channel is switched on, paused, fails or is removed.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.