# Push-to-Talk

> Gate the microphone with press-to-talk for deliberate voice turns.

Build an Agora Conversational AI web client where uplink audio publishes only while push-to-talk is engaged, using hold or toggle modes.

- Author: Therealratoshen
- Updated: 2026-08-02
- Difficulty: Intermediate
- Categories: voice-ai
- Platforms: TypeScript
- Use cases: Voice AI, Client UX
- Capabilities: Conversational AI, Voice Agent, Push to Talk
- [Recipe page](https://recipes.agora.io/recipes/push-to-talk)
- [Implementation repository](https://github.com/Therealratoshen/recipe-push-to-talk)
- [Source recipe](https://github.com/Therealratoshen/recipe-push-to-talk/blob/main/docs/ai/RECIPE.md)
- [Raw source Markdown](https://raw.githubusercontent.com/Therealratoshen/recipe-push-to-talk/main/docs/ai/RECIPE.md)
- [All recipes](https://recipes.agora.io/llms.txt)

## Implementation guide

# Push-to-Talk Voice Agent

> **Copyable prompt for coding agents**
>
> Build and run the Agora Conversational AI push-to-talk recipe in this repo. Read AGENTS.md and docs/ai/RECIPE.md fully. Copy .env.example to .env.local and fill Agora + LLM + TTS credentials. Run npm install --legacy-peer-deps && npm run dev. Open localhost:3000, start a conversation, and verify the agent only hears you while Push-to-Talk is engaged (hold or toggle). Do not remove the mic publish gate in lib/ptt.ts.

## What you build

A browser ConvoAI client where microphone uplink is gated by push-to-talk (hold-to-talk or latch toggle). Use this in noisy rooms or when deliberate turns beat full-duplex barge-in.

## Prerequisites

- Node.js 20+
- Agora App ID + App Certificate
- LLM API key + TTS vendor credentials (see `.env.example`)

## Run

```bash
cp .env.example .env.local
npm install --legacy-peer-deps
npm run dev
```

Open http://localhost:3000 → start conversation.

## Verification

1. Join/start agent with PTT idle — speaking should **not** elicit an agent reply.
2. Hold (or latch) Push-to-Talk, speak a short question — agent should answer.
3. Release PTT — further speech should not be heard by the agent.
4. `npm test` passes.

## Non-goals

- SIP / phone calling
- Multi-agent handoff (see Agora `agent-handoff` recipe instead)
- Custom LLM gateway unless required by your starter


## Recipe prompt

You are implementing the "Push-to-Talk" recipe in this project.

Read the recipe markdown first:
https://raw.githubusercontent.com/Therealratoshen/recipe-push-to-talk/main/docs/ai/RECIPE.md

Use the source repository for cross-reference:
https://github.com/Therealratoshen/recipe-push-to-talk

Build this recipe into the user's app using the markdown as the implementation guide. Inspect related source files through the repository links when the recipe points to them. Ask before installing new dependencies.