> ## Documentation Index
> Fetch the complete documentation index at: https://docs.pipecat.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Custom Messaging

> Send and receive arbitrary messages between your client and Pipecat bot.

**React**

You are currently viewing the React version of this page. Use the dropdown
to the right to customize this page for your client framework.

**JavaScript**

You are currently viewing the JavaScript version of this page. Use the
dropdown to the right to customize this page for your client framework.

**React Native**

You are currently viewing the React Native version of this page. Use the
dropdown to the right to customize this page for your client framework.

**iOS**

You are currently viewing the iOS version of this page. Use the dropdown to
the right to customize this page for your client framework.

**Android**

You are currently viewing the Android version of this page. Use the dropdown
to the right to customize this page for your client framework.

The Pipecat client can send and receive arbitrary messages to and from the server running the bot. This is useful for passing configuration at startup, triggering actions mid-session, querying server state, and receiving notifications from the bot.

## Connection-time configuration

Often you need to pass configuration to the server when starting the bot — a system prompt, preferred language, user preferences, or any other data the server needs before the pipeline runs. Pass it via `requestData` in `startBotAndConnect()`.

**React**

```tsx theme={null}
import { usePipecatClient } from "@pipecat-ai/client-react";

function MyComponent() {
  const client = usePipecatClient();

  const handleStart = async () => {
    try {
      await client.startBotAndConnect({
        endpoint: "/api/start",
        requestData: {
          initial_prompt: "You are a pirate captain",
          preferred_language: "en-US",
        },
      });
    } catch (error) {
      console.error("Error starting the bot:", error);
    }
  };
}
```

**JavaScript**

```ts theme={null}
try {
  await client.startBotAndConnect({
    endpoint: "/api/start",
    requestData: {
      initial_prompt: "You are a pirate captain",
      preferred_language: "en-US",
    },
  });
} catch (error) {
  console.error("Error starting the bot:", error);
}
```

**React Native**

```tsx theme={null}
try {
  await client.startBotAndConnect({
    endpoint: "/api/start",
    requestData: {
      initial_prompt: "You are a pirate captain",
      preferred_language: "en-US",
    },
  });
} catch (error) {
  console.error("Error starting the bot:", error);
}
```

**iOS**

Pass data via the `requestData` field of `APIRequest`:

```swift theme={null}
let startParams = APIRequest.init(
  endpoint: URL(string: "https://your-server.com/api/start")!,
  requestData: .object([
    "initial_prompt": .string("You are a pirate captain"),
    "preferred_language": .string("en-US"),
  ])
)

client.startBotAndConnect(startBotParams: startParams) { (result: Result<SmallWebRTCStartBotResult, AsyncExecutionError>) in
  switch result {
  case .failure(let error):
    print("Error starting the bot: \(error)")
  case .success:
    break
  }
}
```

**Android**

Pass data via the `requestData` field of `APIRequest`:

```kotlin theme={null}
client.startBotAndConnect(
    APIRequest(
        endpoint = "https://your-server.com/api/start",
        requestData = Value.Object(
            mapOf(
                "initial_prompt" to Value.Str("You are a pirate captain"),
                "preferred_language" to Value.Str("en-US"),
            )
        )
    )
)
```

On the server, your endpoint receives this data as the request body and can forward relevant values to the bot process or use them to configure the pipeline:

```python FastAPI endpoint theme={null}
import os
import subprocess

@app.post("/api/start")
async def start(request: Request) -> Dict[Any, Any]:
    body = await request.json()
    prompt = body.get("initial_prompt", "You are a pirate captain")
    lang = body.get("preferred_language", "en-US")

    room_url, token = await create_room_and_token()

    proc = subprocess.Popen(
        [f"python3 -m bot -u {room_url} -t {token} -p {prompt} -l {lang}"],
        shell=True,
        cwd=os.path.dirname(os.path.abspath(__file__)),
    )
    bot_procs[proc.pid] = (proc, room_url)

    return {"url": room_url, "token": token}

```

```python bot theme={null}
def extract_arguments():
    parser = argparse.ArgumentParser()
    parser.add_argument("-u", "--room-url", type=str)
    parser.add_argument("-t", "--token", type=str)
    parser.add_argument("-p", "--prompt", type=str, default="You are a pirate captain")
    parser.add_argument("-l", "--language", type=str, default="en-US")
    return parser.parse_args()

async def main():
    args = extract_arguments()

    llm = GeminiLiveLLMService(
        api_key=os.getenv("GOOGLE_API_KEY"),
        settings=GeminiLiveLLMService.Settings(
            system_instruction=args.prompt,
            language=args.language,
        ),
    )
```

***

## Sending messages to the server

Use `sendClientMessage()` to send a fire-and-forget message to the bot. The server handles it and is not expected to send a direct response.

**React**

```tsx theme={null}
const client = usePipecatClient();

client.sendClientMessage("set-language", { language: "en-US" });
```

**JavaScript**

```ts theme={null}
client.sendClientMessage("set-language", { language: "en-US" });
```

**React Native**

```tsx theme={null}
client.sendClientMessage("set-language", { language: "en-US" });
```

**iOS**

```swift theme={null}
try client.sendClientMessage(
  msgType: "set-language",
  data: .object(["language": .string("en-US")])
)
```

**Android**

```kotlin theme={null}
client.sendClientMessage(
    "set-language",
    Value.Object(mapOf("language" to Value.Str("en-US")))
)
```

On the server, handle it via the `on_client_message` event handler or from inside a `FrameProcessor`:

```python event handler theme={null}
from pipecat.services.settings import STTSettings

@rtvi.event_handler("on_client_message")
async def on_client_message(rtvi, msg):
    if msg.type == "set-language":
        language = msg.data.get("language", "en-US")
        await worker.queue_frames(
            [STTUpdateSettingsFrame(delta=STTSettings(language=language))]
        )
```

```python FrameProcessor theme={null}
from pipecat.services.settings import STTSettings

class CustomFrameProcessor(FrameProcessor):
    async def process_frame(self, frame: Frame, direction: FrameDirection):
        await super().process_frame(frame, direction)
        if isinstance(frame, RTVIClientMessageFrame):
            if frame.type == "set-language":
                language = frame.data.get("language", "en-US")
                await self.push_frame(
                    STTUpdateSettingsFrame(delta=STTSettings(language=language))
                )
                return
        await self.push_frame(frame, direction)
```

***

## Requesting data from the server

Use `sendClientRequest()` to send a message and wait for a response. Useful for querying server state or triggering an action that needs to confirm success or failure.

**React**

```tsx theme={null}
const client = usePipecatClient();

try {
  const response = await client.sendClientRequest("get-language", {});
  console.log("Current language:", response.language);
} catch (error) {
  console.error("Request failed:", error);
}
```

**JavaScript**

```ts theme={null}
try {
  const response = await client.sendClientRequest("get-language", {});
  console.log("Current language:", response.language);
} catch (error) {
  console.error("Request failed:", error);
}
```

**React Native**

```tsx theme={null}
try {
  const response = await client.sendClientRequest("get-language", {});
  console.log("Current language:", response.language);
} catch (error) {
  console.error("Request failed:", error);
}
```

**iOS**

```swift theme={null}
Task {
  do {
    let response = try await client.sendClientRequest(msgType: "get-language")
    if let language = response.d?.asObject?["language"]?.asString {
      print("Current language: \(language)")
    }
  } catch {
    print("Request failed: \(error)")
  }
}
```

**Android**

```kotlin theme={null}
client.sendClientRequest("get-language", Value.Object())
    .withCallback { result ->
        // The response data arrives as a JsonElement
        val response = result.valueOrNull
        val language = response?.data?.jsonObject
            ?.get("language")?.jsonPrimitive?.content
        Log.d("Bot", "Current language: $language")
    }
```

On the server, respond from the `on_client_message` event handler with `send_server_response()` or `send_error_response()`, or from a `FrameProcessor` by pushing an `RTVIServerResponseFrame` that carries the request's `RTVIClientMessageFrame`. Set `error` instead of `data` to send an error response:

```python event handler theme={null}
@rtvi.event_handler("on_client_message")
async def on_client_message(rtvi, msg):
    if msg.type == "get-language":
        await rtvi.send_server_response(msg, {"language": get_current_language()})
    else:
        await rtvi.send_error_response(msg, "Unknown request type")
```

```python FrameProcessor theme={null}
class CustomFrameProcessor(FrameProcessor):
    async def process_frame(self, frame: Frame, direction: FrameDirection):
        await super().process_frame(frame, direction)
        if isinstance(frame, RTVIClientMessageFrame):
            if frame.type == "get-language":
                await self.push_frame(
                    RTVIServerResponseFrame(
                        client_msg=frame,
                        data={"language": get_current_language()},
                    )
                )
                return
            else:
                await self.push_frame(
                    RTVIServerResponseFrame(
                        client_msg=frame,
                        error="Unknown request type",
                    )
                )
        await self.push_frame(frame, direction)
```

***

## Receiving messages from the server

The server can push unsolicited messages to the client at any time — for example, to notify the client that a setting has changed.

**React**

Use `useRTVIClientEvent` to subscribe to `ServerMessage` within a component:

```tsx theme={null}
import { RTVIEvent, RTVIMessage } from "@pipecat-ai/client-js";
import { useRTVIClientEvent } from "@pipecat-ai/client-react";

type LanguageData = {
  msg: string;
  language: string;
};

function LanguageListener() {
  useRTVIClientEvent(
    RTVIEvent.ServerMessage,
    useCallback((message: RTVIMessage) => {
      const data: LanguageData = message.data as LanguageData;
      if (data.msg === "language-updated") {
        console.log("Language updated to:", data.language);
      }
    }, []),
  );
}
```

**JavaScript**

Listen for the `ServerMessage` event on the client, or pass `onServerMessage` as a constructor callback:

```ts theme={null}
client.on(RTVIEvent.ServerMessage, (message) => {
  if (message.data.msg === "language-updated") {
    console.log("Language updated to:", message.data.language);
  }
});
```

**React Native**

Listen for the `ServerMessage` event using `useEffect` with cleanup:

```tsx theme={null}
import { RTVIEvent } from "@pipecat-ai/client-js";
import { useEffect } from "react";

function LanguageListener() {
  useEffect(() => {
    const handler = (message) => {
      if (message.data.msg === "language-updated") {
        console.log("Language updated to:", message.data.language);
      }
    };
    client.on(RTVIEvent.ServerMessage, handler);
    return () => client.off(RTVIEvent.ServerMessage, handler);
  }, []);
}
```

**iOS**

Implement `onServerMessage` in your `PipecatClientDelegate` to receive unsolicited server messages. The SDK decodes the message payload and passes it as a `Value`:

```swift theme={null}
func onServerMessage(data: Any) {
  Task { @MainActor in
    guard let value = data as? Value else { return }
    let obj = value.asObject
    guard obj["msg"]?.asString == "language-updated",
          let language = obj["language"]?.asString else { return }
    print("Language updated to: \(language)")
  }
}
```

**Android**

Override `onServerMessage` in your `PipecatEventCallbacks` to receive unsolicited server messages:

```kotlin theme={null}
override fun onServerMessage(data: Value) {
    val obj = data as? Value.Object ?: return
    val msg = (obj.value["msg"] as? Value.Str)?.value
    if (msg == "language-updated") {
        val language = (obj.value["language"] as? Value.Str)?.value
        Log.d("Bot", "Language updated to: $language")
    }
}
```

On the server, send messages by pushing an `RTVIServerMessageFrame`:

```python theme={null}
from pipecat.utils.types import is_given

class CustomFrameProcessor(FrameProcessor):
    async def process_frame(self, frame: Frame, direction: FrameDirection):
        await super().process_frame(frame, direction)
        if isinstance(frame, STTUpdateSettingsFrame) and frame.delta:
            if is_given(frame.delta.language):
                await self.push_frame(
                    RTVIServerMessageFrame(
                        data={"msg": "language-updated", "language": frame.delta.language}
                    )
                )
        await self.push_frame(frame, direction)
```

From outside the pipeline, such as an event handler, queue it on the worker instead: `await worker.queue_frame(RTVIServerMessageFrame(data={...}))`.

***

## API reference

> [card] [Client Methods](https://docs.pipecat.ai/api-reference/client/js/client-methods.md#messages)
>
> `sendClientMessage`, `sendClientRequest`, `registerFunctionCallHandler`

> [card] [Callbacks & Events](https://docs.pipecat.ai/api-reference/client/js/callbacks.md#messages-and-errors)
>
> `onServerMessage`, `onMessageError`, and related events


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.