Core concepts
The handful of words the rest of these docs use, each explained once.
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.
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.
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, the 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.