Quickstart

This guide walks you through the three main stages of working with the Companion API: building an agent, deploying it, and monitoring it in production.

Before you start, you'll need an API key. You can generate one from the admin interface — see Authentication for details.

Your API key is a secret. Keep it private and only use it on the server side — never expose it in client-side code.

Build your agent

Start by choosing a companion. You can browse the catalog of existing companions or create your own.

Browse the companion catalog (API reference):

curl -X GET https://companion-api.napster.com/public/napster-companions \
  -H "X-Api-Key: $NAPSTER_API_KEY"

Or create a custom one (API reference):

curl -X POST https://companion-api.napster.com/public/companions \
  -H "X-Api-Key: $NAPSTER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "firstName": "Alex",
    "lastName": "Chen",
    "description": "A senior tech support specialist who has been helping customers for over a decade. Warm, patient, and detail-oriented. Explains technical concepts in plain language and always walks users through solutions step by step. Keeps a professional but approachable tone, occasionally uses light humor to put frustrated users at ease.",
    "pictureUrl": "https://example.com/images/alex-avatar.png"
  }'

You can also equip your agent with tools and knowledge to expand what it can do and what it knows.

Learn more about building your agent

Deploy your agent

Create a connection to bring your agent to life. This is where you specify which companion and tools to include in the session (API reference):

curl -X POST https://companion-api.napster.com/public/connections \
  -H "X-Api-Key: $NAPSTER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "companionId": "comp_abc123",
    "providerConfig": {
      "voiceId": "alloy",
      "settings": {}
    },
    "functions": ["func_abc123", "func_def456"]
  }'

The response returns a token and a connection object with an id. Use the token to initialize the Web SDK and embed the agent directly in your application. Store the connection id on your backend to retrieve session details later, such as transcripts or duration.

Install the Web SDK:

npm install @touchcastllc/napster-companion-api @reduxjs/toolkit

Then use it in your React app:

import React, { useEffect, useRef } from "react";
import { NapsterCompanionApiSdk } from "@touchcastllc/napster-companion-api";
import type { NapsterCompanionApiInstance } from "@touchcastllc/napster-companion-api";
import "@touchcastllc/napster-companion-api/styles";

export function CompanionWidget({ token }: { token: string }) {
  const containerRef = useRef<HTMLDivElement>(null);
  const instanceRef = useRef<NapsterCompanionApiInstance | null>(null);

  useEffect(() => {
    const initSDK = async () => {
      if (!containerRef.current) return;

      const result = await NapsterCompanionApiSdk.init(token, {
        mountContainer: containerRef.current,
        position: "bottom-right",
      });
      instanceRef.current = result;
    };

    initSDK();

    return () => {
      instanceRef.current?.destroy();
    };
  }, []);

  return <div ref={containerRef} style={{ width: "100%", height: "100%" }} />;
}

For examples in Vue, Angular, and vanilla JavaScript, see the WebRTC page.

Learn more about deploying your agent

Monitor your agent

Once your agent is live, track how it's performing. Review analytics, browse conversation logs, and use those insights to refine your agent over time.

Learn more about monitoring your agent

Quickstart

Build your agent

Deploy your agent

Monitor your agent

On this page