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

# How Comms works

> Lines, keys, agents, and the Messages API — what each piece owns.

Comms has a small set of concepts. Understanding them once makes every API page obvious.

## Line

A **line** is the phone identity customers text — SMS and iMessage on the same number where available. Outbound API sends leave from that line. Inbound replies land on that line and show up in the inbox and Messages API.

## Messages API key

A **Messages API key** authenticates your server to Comms.

| It can                          | It cannot                      |
| ------------------------------- | ------------------------------ |
| Send and list messages          | Change billing or plan         |
| List conversations and contacts | Manage team members            |
| Register webhooks (with scope)  | Impersonate dashboard sessions |

Keys are minted under [Messages API](https://comms.osis.co/dashboard/settings/api-keys) in the dashboard. Default scopes are send + read.

## Conversation

A **conversation** is a thread between your line and a customer (usually keyed by their phone). You can:

* Start one by sending to a new `to` number.
* Continue one by passing `conversation_id` on send.
* List them via `GET /api/v1/comms/conversations`.

## Contact

A **contact** is a person you message — phone, optional name, email, tags. Listing is read-scoped; upsert currently expects a broader `write` scope when present on the key.

## Agent (optional)

An **agent** is the no-code path: instructions, knowledge, tools, and handoff rules running on the line. You do **not** need an agent to use the Messages API. Many teams use both:

* API for system-triggered texts (receipts, status, ops).
* Agent for free-form customer replies.
* Humans for handoff in the inbox.

## Delivery

When you `POST` a message, Comms accepts it (**202**), places it on the line, and tracks delivery attempts. Inspect attempts with [events](/messages-api/list-events) when something looks stuck.

## Mental model

```mermaid theme={null}
flowchart TB
  subgraph your_side [Your side]
    Code[Backend / worker]
    Key[COMMS_API_KEY]
  end
  subgraph comms [Comms]
    API[Messages API]
    Line[Line]
    Inbox[Inbox]
    Agent[Agent optional]
  end
  Customer[Customer phone]
  Code --> Key
  Key --> API
  API --> Line
  Line --> Customer
  Customer --> Line
  Line --> Inbox
  Agent -.-> Line
```