# Core concepts

> The handful of words the rest of these docs use, each explained once.

Source: https://docs.vlayers.ai/get-started/concepts

Kind: Concept

VoiceLayer is a communications layer for your code and your AI agents. You send and receive messages on many channels through one API. These are the terms the docs use for its parts.

## Workspace

Your account's container: its numbers, connected channels, agents, conversations, keys and billing. Every API request acts on one workspace, the one its key belongs to.

## API key

The secret your server sends with every request (`Authorization: Bearer …`). A key belongs to one workspace and one environment, test or live. See [Authentication and API keys](https://docs.vlayers.ai/get-started/authentication).

## Channel

A way to reach people: `sms`, `mms`, `whatsapp`, `telegram`, `discord` or `email`. Each channel has its own rules, such as WhatsApp's 24-hour reply window or the length of a text. `GET /v1/channels` lists the channels your workspace can use and what each can do.

## Sender

What a message leaves from, and what people write to. It depends on the channel:

- a **phone number** for SMS and MMS;
- a **Binding** for WhatsApp, Telegram and Discord;
- a **mailbox** for email.

When you have one sender on a channel, the API uses it. When you have several, you name one in `from`.

## Line

Your agent's identity across channels: the thing people actually talk to. A Line keeps its identity when you change the model or the code behind it, and it can have several senders, for example a phone number and a WhatsApp account.

## Binding

One connected account on an app channel, attached to a Line: a WhatsApp business number, a Telegram bot or a Discord bot. You connect Bindings in the dashboard under **Channels**. In the API, a Binding is a sender you name with `{ "bindingId": "…" }`.

## Conversation

The thread between one of your Lines and one person. Every message belongs to exactly one conversation. A conversation has an `id`, a channel, the person's address (`peer`), and a `controller`. On WhatsApp it also has a `window` that says whether you may still reply.

## Controller

Who answers a conversation's incoming messages:

| Controller | Who replies |
|---|---|
| `agent` | Your VoiceLayer agent replies on its own. |
| `api` | Your code replies through the API; the agent stays quiet. |
| `human` | A person replies from the dashboard. |

A new conversation starts with the agent when its Line has an agent that answers messages, and with `api` otherwise. You change it with `PATCH /v1/conversations/{id}`. See [Conversations and handoff](https://docs.vlayers.ai/developers/handoff).

## Message

One text, media message or email in a conversation. A message is `inbound` (a person wrote to you) or `outbound` (you sent it). Its `status` moves from `queued` to `sent`, `delivered` or `read`, or to `failed`. Inbound messages have the status `received`.

## Event

A record that something happened, such as `message.received` or `conversation.controller_changed`. You get events three ways: [webhooks](https://docs.vlayers.ai/developers/receive/webhooks), the [event stream](https://docs.vlayers.ai/developers/receive/event-stream), or by pulling `GET /v1/events`. An event has the same `id` on every transport, so you can deduplicate on it.

## Test mode and live mode

A **test key** (`vl_test_…`) runs every check the API makes but delivers to a simulated carrier, at no cost, and only to reserved test addresses. A **live key** reaches real people. Events from test conversations carry `"livemode": false`. See [Test mode](https://docs.vlayers.ai/developers/test-mode).