Documentation Updates for RTVI version 1.0.0 and corresponding client-js and client-react libraries.

client/introduction.mdx

@@ -3,6 +3,10 @@ title: "Client SDKs"
 description: "Client libraries for building real-time AI applications with Pipecat"
 ---
 
+<Warning>
+  The Client SDKs are currently in transition to a new, simpler API design. The js and react libraries have already been deployed with these changes. Their corresponding documentation along with this top-level documentation has been updated to reflect the latest changes. For transitioning to the new API, please refer to the [migration guide](/client/migration-guide). Note that React Native, iOS, and Android SDKs are still in the process of being updated and their documentation will be updated once the new versions are released. If you have any questions or need assistance, please reach out to us on [Discord](https://discord.gg/pipecat).
+</Warning>
+
 Pipecat provides client SDKs for multiple platforms, all implementing the RTVI (Real-Time Voice and Video Inference) standard. These SDKs make it easy to build real-time AI applications that can handle voice, video, and text interactions.
 
 <CardGroup cols={3}>
@@ -63,40 +67,43 @@ All Pipecat client SDKs provide:
   <Card title="Bot Integration" icon="robot">
     Configure and communicate with your Pipecat bot
   </Card>
-  <Card title="Action Handling" icon="bolt">
-    Send actions and process bot responses
-  </Card>
   <Card title="Session Management" icon="arrows-rotate">
     Manage connection state and error handling
   </Card>
 </CardGroup>
 
-## Interaction Modes
+## Core Types
+
+### PipecatClient
+The main class for interacting with Pipecat bots. It is the primary type you will interact with.
+
+### Transport
+The `PipecatClient` wraps a Transport, which defines and provides the underlying connection mechanism (e.g., WebSocket, WebRTC). Your Pipecat pipeline will contain a corresponding transport.
+
+### RTVIMessage
+Represents a message sent to or received from a Pipecat bot.
+
+## Simple Usage Examples
 
 <Tabs>
-  <Tab title="Real-time Streaming">
+  <Tab title="Connecting to a Bot">
     Establish ongoing connections via WebSocket or WebRTC for:
     - Live voice conversations
     - Real-time video processing
     - Continuous interactions
 
-    ```javascript
+    <CodeGroup>
+
+    ```javascript javascript
     // Example: Establishing a real-time connection
-    import { RTVIEvent, RTVIMessage, RTVIClient } from "realtime-ai";
+    import { RTVIEvent, RTVIMessage, PipecatClient } from "@pipecat-ai/client-js";
     import { DailyTransport } from "@pipecat-ai/daily-transport";
 
-    const rtviClient = new RTVIClient({
+    const pcClient = new PipecatClient({
       transport: new DailyTransport(),
-      params: {
-        baseUrl: "https://your-connect-end-point-here",
-        endpoint: {
-          connect: "/connect",
-        }
-      }
       enableMic: true,
       enableCam: false,
       enableScreenShare: false,
-      timeout: 15 * 1000,
       callbacks: {
         onBotConnected: () => {
           console.log("[CALLBACK] Bot connected");
@@ -111,66 +118,148 @@ All Pipecat client SDKs provide:
     });
 
     try {
-      await rtviClient.connect();
+      // Below, we use a REST endpoint to fetch connection credentials for our
+      // Daily Transport. Alternatively, you could provide those credentials
+      // directly to `connect()`.
+      await pcClient.connect({
+        endpoint: "https://your-connect-end-point-here/connect",
+      });
     } catch (e) {
       console.error(e.message);
     }
 
-    // Events
-    rtviClient.on(RTVIEvent.Connected, () => {
+    // Events (alternative approach to constructor-provided callbacks)
+    pcClient.on(RTVIEvent.Connected, () => {
       console.log("[EVENT] User connected");
     });
-    rtviClient.on(RTVIEvent.Disconnected, () => {
+    pcClient.on(RTVIEvent.Disconnected, () => {
       console.log("[EVENT] User disconnected");
     });
     ```
 
+    ```jsx react
+    // Example: Using PipecatClient in a React component
+    import { PipecatClient } from "@pipecat-ai/client-js";
+    import {
+      PipecatClientProvider,
+      PipecatClientAudio,
+      usePipecatClient,
+      useRTVIClientEvent,
+    } from "@pipecat-ai/client-react";
+    import { DailyTransport } from "@pipecat-ai/daily-transport";
+
+    // Create the client instance
+    const client = new PipecatClient({
+      transport: new DailyTransport(),
+      enableMic: true,
+    });
+
+    // Root component wraps the app with the provider
+    function App() {
+      return (
+        <PipecatClientProvider client={client}>
+          <VoiceBot />
+          <PipecatClientAudio />
+        </PipecatClientProvider>
+      );
+    }
+
+    // Component using the client
+    function VoiceBot() {
+      const client = usePipecatClient();
+
+      const handleClick = async () => {
+        await client.connect({
+          endpoint: `${process.env.PIPECAT_API_URL || "/api"}/connect`
+        });
+      };
+
+      return (
+        <button onClick={handleClick}>Start Conversation</button>;
+      );
+    }
+
+    function EventListener() {
+      useRTVIClientEvent(
+        RTVIEvent.Connected,
+        useCallback(() => {
+          console.log("[EVENT] User connected");
+        }, [])
+      );
+    }
+    ```
+
+    </CodeGroup>
+
 </Tab>
-<Tab title="Single-turn Actions">
-  Send individual actions for:
-  - Text-to-text chat
-  - One-off image processing
-  - Batch operations
-
-```javascript
-// Example: Sending a single action
-import { RTVIClient } from "realtime-ai";
-
-const rtviClient = new RTVIClient({
-  params: {
-    baseUrl: "https://your-connect-end-point-here",
-    endpoint: {
-      connect: "/connect",
-      action: "/action",
-    },
-  },
-  callbacks: {
-    onBotText: (text: BotLLMTextData) => {
-      console.log("Text response:", text);
-    },
-  },
-});
-
-try {
-  await rtviClient.action({
-    service: "llm",
-    action: "append_to_messages",
-    arguments: [
-      {
-        name: "messages",
-        value: [
-          {
-            role: "user",
-            content: "tell me a joke",
-          },
-        ],
+<Tab title="Custom Messaging">
+  Send custom messages and handle responses from your bot. This is useful for:
+  - Running server-side functionality
+  - Triggering specific bot actions
+  - Querying the server
+  - Responding to server requests
+
+  <CodeGroup>
+
+  ```javascript javascript
+  import { PipecatClient } from "@pipecat-ai/client-js";
+
+  const pcClient = new PipecatClient({
+    transport: new DailyTransport(),
+    callbacks: {
+      onBotConnected: () => {
+        pcClient.sendClientRequest('get-language')
+          .then((response) => {
+            console.log("[CALLBACK] Bot using language:", response);
+            if (response !== preferredLanguage) {
+              pcClient.sendClientMessage('set-language', {language: preferredLanguage});
+            }
+          })
+          .catch((error) => {
+            console.error("[CALLBACK] Error getting language:", error);
+          });
       },
-    ],
+      onServerMessage: (message) => {
+        console.log("[CALLBACK] Received message from server:", message);
+      },
+    },
   });
-} catch (e) {
-  console.error(e.message);
-}
-```
+  await pcClient.connect({url: "https://your-daily-room-url", token: "your-daily-token"});
+  ```
+
+  ```jsx react
+  // Example: Messaging in a React application
+  import { useCallback } from "react";
+  import { RTVIEvent, TransportState } from "@pipecat-ai/client-js";
+  import { usePipecatClient, useRTVIClientEvent } from "@pipecat-ai/client-react";
+
+  function EventListener() {
+    const pcClient = usePipecatClient();
+    useRTVIClientEvent(
+      RTVIEvent.BotConnected,
+      useCallback(() => {
+        pcClient.sendClientRequest('get-language')
+          .then((response) => {
+            console.log("[CALLBACK] Bot using language:", response);
+            if (response !== preferredLanguage) {
+              pcClient.sendClientMessage('set-language', {language: preferredLanguage});
+            }
+          })
+          .catch((error) => {
+            console.error("[CALLBACK] Error getting language:", error);
+          });
+      }, [])
+    );
+    useRTVIClientEvent(
+      RTVIEvent.ServerMessage,
+      useCallback((data) => {
+        console.log("[CALLBACK] Received message from server:", data);
+      }, [])
+    );
+  }
+  ```
+
+  </CodeGroup>
 
 </Tab>
 </Tabs>
@@ -183,12 +272,6 @@ Pipecat's client SDKs implement the RTVI (Real-Time Voice and Video Inference) s
 - You get battle-tested tooling for real-time multimedia handling
 - You can easily set up development and testing environments
 
-<Note>
-  For production deployments, we recommend setting up your own authentication
-  endpoints rather than exposing service credentials directly in client
-  applications.
-</Note>
-
 ## Next Steps
 
 Get started by trying out examples:
@@ -200,7 +283,7 @@ Get started by trying out examples:
     href="https://github.com/pipecat-ai/pipecat/tree/main/examples/simple-chatbot"
   >
     Complete client-server example with both bot backend (Python) and frontend
-    implementation (JS, React).
+    implementation (JS, React, React Native, iOS, and Android).
   </Card>
   <Card
     title="More Examples"