# Channels and messages

```mermaid
---
Channel lifecycle
---
stateDiagram-v2
	[*] --> Active : POST /api/channels
	Active --> Deleted : DELETE /api/channels/C1234
	Active --> Deleted : Expiry
	Deleted --> [*] : Purge
```

```mermaid
---
Message lifecycle
---
stateDiagram-v2
	[*] --> Sent : POST /api/channels/C1234
	Sent --> Deleted : DELETE /api/messages/Mabcd
	Sent --> Deleted : Expiry
	Deleted --> [*] : Purge
```

Messages allow logins to communicate with one another. Channels are the conversations to which those messages are sent.

Every channel has a unique name, chosen when the channel is created.


## Expiry and purging

Both channels and messages expire after a time. Messages expire 90 days after being sent. Channels expire 90 days after the last message sent to them, or after creation if no messages are sent in that time.

Deleted channels and messages, including those that have expired, are temporarily retained by the service, to allow clients that are not connected to receive the corresponding deletion [events](./events.md). To limit storage growth, deleted channels and messages are purged from the service seven days after they were deleted.


## `POST /api/channels`

Creates a channel.

### Request

```json
{
	"name": "a unique channel name"
}
```

The request must have the following fields:

| Field  | Type   | Description |
|:-------|:-------|:--|
| `name` | string | The channel's name. |

### Success

This endpoint will respond with a status of `202 Accepted` when successful. The body of the response will be a JSON object describing the new channel:

```json
{
	"id": "C9876cyyz"
	"name": "a unique channel name",
}
```

The response will have the following fields:

| Field  | Type   | Description |
|:-------|:-------|:--|
| `id`   | string | A unique identifier for the channel. This can be used to associate the channel with events, or to make API calls targeting the channel. |
| `name` | string | The channel's name. |

When completed, the service will emit a [channel created](events.md#channel-created) event with the channel's ID.

### Duplicate channel name

This endpoint will respond with a status of `409 Conflict` if a channel with the requested name already exists.


## `POST /api/channels/:id`

Sends a message to a channel.

This endpoint requires the following path parameter:

| Parameter | Type   | Description |
|:----------|:-------|:--|
| `id`      | string | A channel ID. |

### Request

```json
{
	"body": "my amazing thoughts, by bob"
}
```

The request must have the following fields:

| Field  | Type   | Description |
|:-------|:-------|:--|
| `body` | string | The message to deliver to the channel. |

### Success

This endpoint will respond with a status of `202 Accepted` when successful. The body of the response will be a JSON object describing the newly-sent message:

```json
{
	"at": "2024-10-19T04:37:09.467325Z",
	"channel": "Cfqdn1234",
	"sender": "Labcd1234",
	"id": "Mgh98yp75",
	"body": "an elaborate example message"
}
```

The response will have the following fields:

| Field     | Type      | Description |
|:----------|:----------|:--|
| `at`      | timestamp | The moment the message was sent. |
| `channel` | string    | The ID of the channel the message was sent to. |
| `sender`  | string    | The ID of the login that sent the message. |
| `id`      | string    | A unique identifier for the message. This can be used to associate the message with events, or to make API calls targeting the message. |
| `body`    | string    | The message's body. |

When completed, the service will emit a [message sent](events.md#message-sent) event with the message's ID.

### Invalid channel ID

This endpoint will respond with a status of `404 Not Found` if the channel ID is not valid.


## `DELETE /api/channels/:id`

Deletes a channel.

Deleting a channel prevents it from receiving any further messages, and deletes the messages it contains at that point.

This endpoint requires the following path parameter:

| Parameter | Type   | Description |
|:----------|:-------|:--|
| `id`      | string | A channel ID. |

### Success

This endpoint will respond with a status of `202 Accepted` when successful. The response will not include a body.

When completed, the service will emit a [channel deleted](events.md#channel-deleted) event with the channel's ID. In addition, the service will emit a [message deleted](events.md#message-deleted) event for each message deleted.


### Invalid channel ID

This endpoint will respond with a status of `404 Not Found` if the channel ID is not valid.


## `DELETE /api/messages/:id`

Deletes a message.

This endpoint requires the following path parameter:

| Parameter | Type   | Description |
|:----------|:-------|:--|
| `id`      | string | A message ID. |

### Success

This endpoint will respond with a status of `202 Accepted` when successful. The response will not include a body.

When completed, the service will emit a [message deleted](events.md#message-deleted) event with the channel's ID.

### Invalid message ID

This endpoint will respond with a status of `404 Not Found` if the message ID is not valid.