# Channel

URL: /business/nouns/channel · Id: `noun:channel`

> A Channel is a place Messages flow, such as a chat channel, a Mailbox, or an SMS number.

A Channel is a place [Messages](/business/nouns/message) flow, such as a chat channel, a [Mailbox](/business/nouns/mailbox), or an SMS number.

## Properties
| Property | Type | Required | Description |
| --- | --- | --- | --- |
| `medium` | `string` | Yes | The platform type, such as `email`, `sms`, or `chat`. |
| `organization` | [Organization](/business/nouns/organization) | No | The outside Organization the Channel is shared with; its new Messages open Conversations for that Customer. |
| `external` | `boolean` | No | True when people from another Organization post in it, as in a channel two companies share. |
| `areaCode` | `string` | No | For an `sms` Channel, the phone area code its number is drawn from, such as `512`. |
| `number` | `string` | No | For an `sms` Channel, its phone number in international form, assigned when it is created. |

## Object
```json
{
  "$id": "https://api.sb/routewise.dev/channels/channel_1",
  "$type": "Channel",
  "medium": "email",
  "organization": "organization_1",
  "external": true,
  "areaCode": "Example area code",
  "number": "Example number"
}
```

## Relationships
- <a id="rel-hosts"></a>A Channel **hosts** many [Threads](/business/nouns/thread): a Channel holds [Threads](/business/nouns/thread). `hosts`, inverse [`hostedIn`](/business/nouns/thread#rel-hosted-in).
- <a id="rel-messages"></a>A Channel **has** many [Messages](/business/nouns/message): every [Message](/business/nouns/message) flows through one Channel. `messages`, inverse [`postedIn`](/business/nouns/message#rel-posted-in).

## Verbs
| Verb | Description | Subject | Event | Class |
| --- | --- | --- | --- | --- |
| <a id="create"></a>[Channel.create](/business/nouns/channel/create) | Creates a Channel. Inherited from [Noun](/business/nouns/noun). | None. | `Channel.created` | Two-way: `try`, `send`, `do` |
| <a id="get"></a>[Channel.get](/business/nouns/channel/get) | Returns one Channel by id. Inherited from [Noun](/business/nouns/noun). | None. | None. | Read: `try`, `do` |
| <a id="list"></a>[Channel.list](/business/nouns/channel/list) | Returns Channels, newest first, one page at a time. Inherited from [Noun](/business/nouns/noun). | None. | None. | Read: `try`, `do` |
| <a id="update"></a>[Channel.update](/business/nouns/channel/update) | Changes the given properties of a Channel. Inherited from [Noun](/business/nouns/noun). | None. | `Channel.updated` | Two-way: `try`, `send`, `do` |
| <a id="delete"></a>[Channel.delete](/business/nouns/channel/delete) | Deletes a Channel; its history is kept. Inherited from [Noun](/business/nouns/noun). | None. | `Channel.deleted` | One-way: `send`, `do` |

## Permissions
Which Access level may call each Verb. One-way Verbs wait their delay window.

| Operation | `owner` | `admin` | `member` | `viewer` |
| --- | --- | --- | --- | --- |
| `Channel.create` | Yes | Yes | Yes | No |
| `Channel.get` | Yes | Yes | Yes | Yes |
| `Channel.list` | Yes | Yes | Yes | Yes |
| `Channel.update` | Yes | Yes | Yes | No |
| `Channel.delete` | Yes | Yes | Yes | No |

## Call it

**Ask**

```text
Add a channel to LedgerLark.
```

**API**

```bash
curl -X POST https://api.sb/ledgerlark.com/channels \
  -H "Authorization: Bearer $STARTUP_BUILDER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"medium":"email"}'
```

```json
{
  "api": "https://api.sb/ledgerlark.com",
  "channel": {
    "$id": "https://api.sb/ledgerlark.com/channels/channel_1",
    "$type": "Channel",
    "medium": "email"
  },
  "action": {
    "$id": "https://api.sb/ledgerlark.com/actions/action_1",
    "operation": "Channel.create",
    "status": "done"
  },
  "links": {
    "self": "https://api.sb/ledgerlark.com/actions/action_1"
  }
}
```

**SDK**

```ts
import { $ } from 'startup-builder'

const channel = await $.Channel.create({ medium: 'email' })
```

**CLI**

```bash
npx startup-builder do Channel.create --json '{"medium":"email"}'
```

**MCP**

```json
{
  "name": "do",
  "arguments": {
    "code": "return await $.Channel.create({ medium: 'email' })"
  }
}
```

## Example
A tutoring marketplace runs three Channels: the `help@` [Mailbox](/business/nouns/mailbox), one chat channel per family and its tutor, and an SMS number for session reminders.