​
What you’ll learn

In this quickstart you’ll learn how to:

  1. Install the Outspeed SDK
  2. Set up a backend endpoint to create sessions
  3. Create a simple voice agent that can talk to users

​
Step 1: Install Outspeed

Install the React SDK using your preferred package manager:

npm install @outspeed/client @outspeed/react

​
Step 2: Set up backend endpoint

You need a backend endpoint to keep your API key secure and create sessions.

Create a /token endpoint on your backend:

app.use(express.json());

app.post("/token", async (req, res) => {
  try {
    const response = await fetch("https://api.outspeed.com/v1/realtime/sessions", {
      method: "POST",
      headers: {
        Authorization: `Bearer ${process.env.OUTSPEED_API_KEY}`,
        "Content-Type": "application/json",
      },
      body: JSON.stringify(req.body),
    });

    if (!response.ok) {
      const error = await response.text();
      console.error("failed to generate ephemeral key:", error);
      res.status(response.status).json({ error: "Failed to generate token" });
      return;
    }

    const data = await response.json();
    res.json(data);
  } catch (error) {
    console.error("failed to generate ephemeral key:", error);
    res.status(500).json({ error: "Internal server error" });
  }
});

​
Step 3: Create React component

Here’s a complete working example:

import { type SessionConfig } from "@outspeed/client";
import { useConversation } from "@outspeed/react";
import { useState } from "react";

// Change this to your backend URL
const SERVER_URL = "http://127.0.0.1:8000";

const getEphemeralKeyFromServer = async (config: SessionConfig) => {
  const tokenResponse = await fetch(`${SERVER_URL}/token`, {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify(config),
  });

  const data = await tokenResponse.json();
  if (!tokenResponse.ok) {
    throw new Error("Failed to get ephemeral key");
  }

  return data.client_secret.value;
};

const sessionConfig: SessionConfig = {
  model: "outspeed-v1",
  instructions: "You are a helpful assistant.",
  voice: "sophie", // see the voices page for all available voices
  temperature: 0.5,
  turn_detection: {
    type: "semantic_vad",
  },
  first_message: "Hello! How can I help you today?",
};

export default function App() {
  const [sessionCreated, setSessionCreated] = useState(false);

  const conversation = useConversation({
    onDisconnect: () => {
      console.log("Disconnected! cleaning up...");
      setSessionCreated(false);
    },
  });

  const startSession = async () => {
    try {
      const ephemeralKey = await getEphemeralKeyFromServer(sessionConfig);

      conversation.on("session.created", () => {
        setSessionCreated(true);
      });

      await conversation.startSession(ephemeralKey);
    } catch (error) {
      console.error("Error starting session", error);
    }
  };

  const endSession = async () => {
    try {
      await conversation.endSession();
    } catch (error) {
      console.error("Error ending session", error);
    } finally {
      setSessionCreated(false);
    }
  };

  if (sessionCreated) {
    return (
      <div>
        <h2>Voice session active!</h2>
        <p>Start talking to your AI assistant</p>
        <button onClick={endSession}>End Session</button>
      </div>
    );
  }

  return (
    <div>
      <h2>Voice AI Assistant</h2>
      <p>Click the button to start talking</p>
      <button onClick={startSession}>Start Session</button>
    </div>
  );
}
Want to use a different voice? See all available voices you can choose from.

​
That’s it!

You now have a working voice agent that can:

  • Start and end voice sessions
  • Talk to users with AI-powered responses
  • Handle voice activity detection automatically

​
More Examples

Want to see complete implementations with different frameworks? Check out our Examples Repository which includes:

  • React + Vite + FastAPI - Full-featured voice assistant with weather tools
  • React + Vite + Cloudflare Functions - Serverless voice assistant
  • Create React App + FastAPI - Simple React setup with Python backend
  • Next.js - complete Next.js voice assistant (also includes AI-to-AI chat)
  • Swift iOS - Native iOS voice bot with SwiftUI

For more advanced features like tools, context management, and system tools, check out the full documentation.