This guide covers migrating from RTVIClient to the new PipecatClient in a JavaScript application. The new client introduces simplified configuration and improved client-server messaging. For an overview of the changes, see the top-level RTVIClient Migration Guide.

​
Key Changes

​
1. Package and Class Names

Old 
import { RTVIClient } from '@pipecat-ai/client-js';
New 
// New
import { PipecatClient } from '@pipecat-ai/client-js';

​
2. Client and Transport Configuration

The core difference here is that the client no longer accepts a params field. The configuration that used to be provided here is no longer supported and hitting a /connect endpoint is now an explicit step and provided directly to either the startBot() or startBotAndConnect() method. Old 
const transport = new DailyTransport();
const client = new RTVIClient({
  transport,
  params: {
    baseUrl: 'http://localhost:7860',
    endpoints: {
      connect: '/connect'
    }
  }
});
New 
const client = new PipecatClient({
  transport: new DailyTransport(),
  // Connection params moved to startBotAndConnect() call
});

​
3. Connection Method

Previously, connect() was called on the client instance without parameters. Now, you provide connection parameters directly to the connect() method. This allows for more flexibility and customization of the connection process. For ease of use, we’ve also introduced a startBot() and startBotAndConnect() method where you can provide an API endpoint that returns the connection parameters. Old 
await client.connect();
New There are three options for connecting now. For migration purposes, you are likely to use option 3 (startBotAndConnect()):
  1. Direct Connection: Provide the connection details directly to connect().
const cxnDetails = {
  url: 'https://your-daily-room-url',
  token: 'your-daily-token'
};
await client.connect(cxnDetails);
  1. Using startBot(): Fetch connection details from an API endpoint and pass them to connect().
let cxnDetails = await client.startBot({
  endpoint: 'http://localhost:7860/connect',
  requestData: {
    // Any custom data your /connect endpoint requires
    llm_provider: 'openai',
    initial_prompt: "You are a pirate captain",
    // Any additional data
  }
});
cxnDetails = modifyCxnDetails(cxnDetails); // Modify if needed
await client.connect(cxnDetails);
  1. Using startBotAndConnect(): Fetch connection details and connect in one step.
await client.startBotAndConnect({
  endpoint: 'http://localhost:7860/connect',
  requestData: {
    // Any custom data your /connect endpoint requires
    llm_provider: 'openai',
    initial_prompt: "You are a pirate captain",
    // Any additional data
  }
});

​
4. Function Call Handling

Previously, you would use a helper class to handle function calls and provide a single callback to handle any/all function calls. Now, you can register a callback for each function call by name directly on the PipecatClient instance. Old 
let llmHelper = new LLMHelper({});
llmHelper.handleFunctionCall(async (data) => {
  return await this.handleFunctionCall(data.functionName, data.arguments);
});
client.registerHelper('openai', llmHelper);
New 
client.registerFunctionCallHandler('functionName', async (data) => {
  // Handle function call
  return result;
});

​
5. Pipeline Configuration Initialization

Previously, you could provide a pipeline configuration as part of the RTVIClient constructor and it was expected to be in a specific format. Now, if you would like to pass any initial pipeline configurations, you do so as requestData added to the endpoint you provide to connect(). In both cases, you would need server-side code to parse and apply these settings, but now you can define the structure and what pieces of configuration you want to send. Old 
const pipelineConfig = [{
  "service": "llm",
  "options": [
    {
      "name": "initial_messages",
      "value": [
        {
          "role": "system",
          "content": `You are a pirate captain.`
        }
      ]
    },
  ],
},
{
  "service": "tts",
  "options": [
    {
      "name": "language",
      "value": "en-US"
    }
  ]
}];

const rtviClient = new RTVIClient({
  ...
  params: {
    ...
    config: pipelineConfig
  },
});
rtviClient.connect();
New Check out this section of docs for an example, complete with server-side code showing how to initialize the pipeline configuration at connection time. 
try {
  pcClient.startBotAndConnect({
    endpoint: 'https://your-server/connect',
    requestData: {
      initial_prompt: "You are a pirate captain",
      preferred_language: 'en-US'
    }
  });
} catch (error) {
  console.error("Error connecting to server:", error);
}

​
6. Pipeline Configuration Updates

Previously, the client supported updating the pipeline configuration using a specific method that took a configuration object in a generic format. Dynamic and predifined configuration updates, however, are a security concern, allowing clients to override settings and potentially abuse API keys. For this reason, it has been removed and most configuration updates need to be handled custom by your application. To do so, you should take advantage of the client-server messaging system, which allows you to send messages to the server and handle responses. This way, you can implement your own logic for updating configurations securely. Old 
const updatedConfig = [{
  "service": "tts",
  "options": [
    {
      "name": "voice",
      "value": "Janice"
    }
  ]
}];
try {
  await rtviClient.updateConfig(
    updatedConfig as RTVIClientConfigOption[],
    true
  );
} catch (e) {
  console.error("Failed to update config", e);
}
New Check out this section of docs for a more complete example, along with an example on making a request (sendClientRequest()) to wait for a response. 
try {
  pcClient.sendClientMessage('set-voice', { voice: 'Janice' });
} catch (error) {
  console.error("Error sending message to server:", error);
}

​
7. LLM Context Updates

Previously, you would use a helper class to update the context. This could be a security concern for the same reasons as mentioned above and should now be done using the client-server messaging system. However, in the case where you simply wish to add to the user’s or assistant’s context, you can use the appendToContext() method on the PipecatClient instance. This allows for easy, built-in support for text-based context updates without needing to implement custom messaging. Old 
let llmHelper = new LLMHelper({});
client.registerHelper('llm', llmHelper);
await llmHelper.setContext(
  {
    messages: [
      {
        role: "user",
        content: "Tell me a joke.",
      },
    ],
  },
  true
);
New 
client.appendToContext({
  role: "user",\
  content: "Tell me a joke.",
  run_immediately: true
});

​
Breaking Changes

  1. Configuration Structure: Connection parameters are now passed to connect() instead of constructor
  2. Helper System: Removed in favor of direct PipecatClient member functions or client-server messaging.

​
Migration Steps

  1. Update package imports to use new names
  2. Move connection configuration from constructor to startBot()/startBotAndConnect()/connect() methods
  3. Replace any helper classes with corresponding PipecatClient methods or custom messaging
  4. Update any TypeScript types referencing old names