Ponder Logo

Ponder

Docs

v0.0.19
Quickstart
API Reference

API Reference

PonderProvider and usePonder() hook reference.

See NPM package here: @ponderai/react

<PonderProvider />

proptypedefaultdescription
assistantIdstring–ID of the assistant configured on the server
hoststring–Base HTTP(S) URL running the Ponder Server
includePathsstring[][]Render the widget only on these routes (empty ⇒ everywhere)
headlessbooleanfalseHeadless mode: If true, the Ponder UI widget is not rendered in the bottom right corner. You can build your own custom UI and control Ponder via the usePonder hook.

usePonder()

const {
  setActions,
  setInstructions,
  togglePonder,
  connect,
  isListening,
  setOnSpeechStart,
  setOnSpeechEnd,
  setOnMessagesChange,
} = usePonder();
memberpurpose
setActions(list)Set the current list of callable functions (actions) available to the assistant
setInstructions(str)Set the instructions for the assistant (appended to system prompt)
togglePonder()Show or hide the Ponder component, does not apply in headless mode
connect()Programmatically start/stop a voice session (connects to the backend and starts listening). If a session is already active, this will stop it.
isListeningboolean – true while the mic is actively capturing user speech
setOnSpeechStart(callback)Register a callback to be called when the user starts speaking
setOnSpeechEnd(callback)Register a callback to be called when the user stops speaking
setOnMessagesChange(callback)Register a callback to be called whenever the messages list changes as the conversation progresses
Example:
const ponder = usePonder();

useEffect(() => {
  ponder.setActions([
    {
      name: "goToHome",
      description: "Navigate to the home page",
      arguments: [],
      function: () => router.push("/")
    }
  ]);
  ponder.setInstructions("You are a helpful assistant.");
  ponder.setOnSpeechStart(() => console.log("Speech started"));
  ponder.setOnSpeechEnd(() => console.log("Speech ended"));
  ponder.setOnMessagesChange((messages) => console.log("Messages changed", messages));
}, []);

Defining Actions with setActions

setActions expects an array of function definitions. Each function should follow this schema:

type PonderAction = {
  name: string; // Unique function name (used by the assistant)
  description: string; // When should the assistant call this function?
  arguments: Array<{
    name: string;
    description: string;
    type: "string" | "number" | "boolean";
    required?: boolean;
  }>;
  function: (...args: any[]) => any; // The actual JS function to call
};

Example usage:

const ponderActions = [
  {
    name: "goToPricingPage",
    description: "Call this function if the user asks about pricing",
    arguments: [],
    function: () => {
      window.location.href = "/pricing";
    }
  },
  {
    name: "searchDocs",
    description: "Call this function if the user wants to search the docs for something specific",
    arguments: [
      {
        name: "query",
        description: "The search query",
        type: "string",
        required: true
      }
    ],
    function: searchDocs
  },
];

ponder.setActions(ponderActions);

Setting Instructions with setInstructions

setInstructions lets you provide additional context or guidance to the assistant. This string is appended to the system prompt and can be changed at any time.

ponder.setInstructions(
  "This is the home page of Ponder. Help the user understand the product better. Ask them if they are a developer."
);

Tip: You can call setActions and setInstructions together to dynamically change the assistant's behavior based on the current page or user context.

Headless Mode

If you want to build your own custom UI and not render the default Ponder widget, use headless={true} on PonderProvider. You can then use the usePonder hook to control all aspects of the assistant.

In headless mode, you are responsible for providing your own UI and calling connect(), setActions(), setInstructions(), etc. as needed.