Surfaces

Surfaces are the communication channels through which users interact with agents. Lantern supports 7 built-in surfaces, all two-way — agents reply in the same channel you messaged from.

Available surfaces

WhatsApp

Lantern supports two modes for WhatsApp:

• Personal (via bridge) -- connects to your personal WhatsApp account using the multi-device bridge. Messages to your agent appear as regular WhatsApp conversations. No WhatsApp Business account required.
• Business API -- for teams and companies that need a dedicated phone number and the official WhatsApp Business Cloud API. Supports templates, rich messages, and higher throughput.

To set up personal WhatsApp:

1. Navigate to Settings > Surfaces > WhatsApp
2. Select Personal (bridge)
3. Scan the QR code with your WhatsApp app
4. The bridge connects and your agent is now reachable via WhatsApp

Bridge tenant env var

Set LANTERN_TENANT_ID to the tenant UUID the bridge should operate under. The fallback LANTERN_DEFAULT_TENANT_ID is still accepted for backwards compatibility, but LANTERN_TENANT_ID is the canonical name going forward. Both the iMessage bridge and the bridge-core shared library read the same variable in this order.

Slack

Create a Slack app and connect it to Lantern:

1. Navigate to Settings > Surfaces > Slack
2. Click Connect to Slack and authorize the Lantern bot in your workspace
3. Choose which channels the agent should listen to, or enable DM mode

Agents respond in threads by default. Mention @lantern in a channel or send a direct message to trigger a run.

Discord

Similar to Slack, add the Lantern bot to your Discord server:

1. Navigate to Settings > Surfaces > Discord
2. Click the invite link to add the bot to your server
3. Configure which channels the agent monitors

Telegram

Connect a Telegram bot to an agent:

1. Create a bot via @BotFather on Telegram
2. Copy the bot token to Settings > Surfaces > Telegram
3. Assign the surface to an agent

Voice (Twilio + LiveKit)

Phone numbers route inbound calls to a Lantern agent. Two providers are supported:

• Twilio -- TwiML webhooks for inbound PSTN calls. The control-plane verifies Twilio's webhook signature and replies with TwiML. SMS is also available on the same Twilio connector.
• LiveKit -- realtime audio; the control-plane mints a short-lived join token and the audio loop runs in a separately-deployed LiveKit Agents worker (media last-mile).

Budget gating

Voice spend counts against the same agent_budgets as runs. A Twilio inbound call over a hard-fail budget is declined with <Reject> (no carrier cost). A LiveKit join token is refused with HTTP 402 (no token means no media). A flat cost estimate is recorded on connect; the provider's status callback at POST /v1/voice/calls/status/{provider} reconciles to actual duration cost when the call ends.

Voice API

Env vars

Email

Agents can receive and send emails. Configure an email surface with:

1. A dedicated email address (e.g., agent@yourdomain.com)
2. IMAP/SMTP credentials or a connected Gmail connector

Incoming emails trigger the agent; the response is sent as a reply to the same thread.

Web Chat

Embed a chat widget on any website:

<!-- widget.js is served from the same origin as the control-plane -->
<script src="http://localhost:8080/widget.js"
  data-agent="your-agent-name"
  data-tenant="your-tenant-id">
</script>

The widget renders a chat interface that streams agent responses in real time.

CLI

Interact with agents directly from your terminal:

lantern chat my-agent

This opens an interactive session with streaming output.

REST API

Every agent is accessible via the REST API. See the API Reference for full details.

curl -X POST http://localhost:8080/v1/runs \
  -H "Authorization: Bearer $LANTERN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"agentName": "my-agent", "input": {"topic": "quantum computing"}}'

Assigning surfaces to agents

Surfaces are configured at the account level and then assigned per agent, similar to connectors:

1. Set up the surface in Settings > Surfaces
2. On the agent's Configuration tab, enable the surfaces this agent should be reachable on

Two-way communication

All surfaces are two-way. When a user sends a message:

1. The surface gateway receives the message
2. It routes to the correct agent based on the surface configuration
3. The agent runs with the message as input
4. The response streams back through the same surface, in the same conversation or thread