VoiceThere

Quickstart

This guide walks from zero to a live cloud voice session: authenticate the CLI, create and link a project, build an agent bundle, deploy to VoiceThere cloud, and connect with the browser client. For dashboard-only template seeding, see Agent templates.

1. Install packages

npm install -g @voicethere/cli
npm install @voicethere/agent

See npm packages for the full install matrix.

2. Log in

voicethere login

Browser device approval stores a personal API key. Details: CLI login.

3. Create and link a project

cd my-voice-agent
voicethere projects create "My voice agent" --slug my-voice-agent
# writes .voicethere/config.json with project id and dist/agent.js bundle path

Or pick an existing project: voicethere projects use <project-uuid>.

4. Write and build the agent

# Minimal agent (src/agent.ts)
import { defineAgent } from "@voicethere/agent";

export default defineAgent({
  async onUserSpeechFinal({ text, say }) {
    await say("You said: " + text);
  },
});

npx @voicethere/agent build --entry src/agent.ts --outfile dist/agent.js

5. Validate, upload, deploy

voicethere build validate
voicethere build upload -m "Initial quickstart build"
voicethere build list
voicethere build promote <build-uuid-from-list>
voicethere deploy --wait

deploy --wait rolls the active build to cloud session workers and blocks until rollout completes. If the wait times out, the CLI prints the last job status (queued, active, or none) so you can tell a backlog from a still-running rollout. voicethere build validate and dashboard upload accept webhook-only (onWebhook) and session-start-only (onSessionStart) bundles when you use @voicethere/agent 0.5.1+ — see Agent templates.

6. Optional: environment and secrets

voicethere projects environment create AGENT_GREETING "Hello from quickstart"
voicethere projects secrets create AGENT_OPENAI_API_KEY sk-...
voicethere deploy --wait

See Agent environment & secrets.

7. Connect a browser client

Create a client API key in the dashboard (vthc_…) — safe to embed in web apps. Then start a session and connect:

npm install @voicethere/client

# Start session (replace host, project id, and key)
curl -sS -X POST "https://sessions.voicethere.io/v1/sessions" \
  -H "Authorization: Bearer vthc_..." \
  -H "Content-Type: application/json" \
  -d '{"project_id":"<project-uuid>"}'

Use the returned join token and signaling URL with connectVoiceSession — see Browser client.

Next steps

← All documentation