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

# API Reference

> Reference documentation for Ponder

## `PonderProvider`

You can integrate Ponder into your application by wrapping your app in the `PonderProvider`. This is usually done in the `_app.js` file, but depends on your react framework.

### Params

<ParamField path="assistantId" type="string" required>
  ID of the assistant you created on Ponder dashboard
</ParamField>

<ParamField path="host" type="string" required>
  address of Ponder's backend server
</ParamField>

<ParamField path="includePaths" type="string">
  a list of paths where the Ponder widget should be rendered. If not provided then render everywhere
</ParamField>

<ParamField path="headingText" type="string" default="Need help?">
  text to display as heading
</ParamField>

<ParamField path="subHeadingText" type="string" default="Talk to us">
  text to display as sub heading
</ParamField>

<ParamField path="primaryColor" type="string" default="#3b3b3b">
  main background color of the widget
</ParamField>

<ParamField path="secondaryColor" type="string" default="#f1f1f1">
  text and accent color of the widget
</ParamField>

<ParamField path="logo" type="string">
  path to the image file of the company logo
</ParamField>

<ParamField path="headless" type="boolean" default="false">
  if true then the Ponder widget will NOT be rendered and its upto you to build a custom UI for the agent using the usePonder hooks
</ParamField>

```javascript _app.js example
import { PonderProvider } from '@ponderai/react';

function App({ Component, pageProps }) {
      return (
        <PonderProvider assistantId="YOUR_ASSISTANT_ID" host={"https://api.useponder.ai"} includePaths={["/"]}>
          <Component {...pageProps} />
        </PonderProvider>
      );
}

export default App;
```

## `usePonder`

The `usePonder` hook exposes the core functionality of Ponder. You can access it on any component that is a child of the `PonderProvider`

```javascript example
const {
  setActions,
  setInstructions,
  togglePonder,
  connect,
  disconnect,
  onConnected,
  onDisconnected,
  onSpeechStart,
  onSpeechEnd,
  onMessage,
  onFunctionCall
} = usePonder();
```

### Returns

<ResponseField name="togglePonder" type="function">
  show / hide the Ponder widget on the bottom right, not applicable in headless mode
</ResponseField>

<ResponseField name="connect" type="function">
  starts a web call
</ResponseField>

<ResponseField name="disconnect" type="function">
  stops a web call
</ResponseField>

<ResponseField name="onConnected" type="callback">
  callback function called when the call is connected and the agent is listening
</ResponseField>

<ResponseField name="onDisconnected" type="callback">
  callback function called when the call is disconnected and the agent is no longer listening
</ResponseField>

<ResponseField name="setInstructions" type="function">
  lets you set the instructions and context of the agent dynamically

  <Expandable title="params">
    <ResponseField name="instructions" type="string">
      The instructions to set for the agent
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="setActions" type="function">
  lets you set the functions that the agent can call

  <Expandable title="params">
    <ResponseField name="actions" type="list[Action]">
      The actions along with description and js functions. The schema for an action is:

      ```javascript action 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;
      }>;
      };
      ```
    </ResponseField>
  </Expandable>

  ```javascript example [expandable]
  setActions([
    {
      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
        }
      ],
    },
  ])
  ```
</ResponseField>

<ResponseField name="onSpeechStart" type="function">
  callback function for whenever user speech start is detected<br />
  does not have any arguments

  ```javascript example
  onSpeechStart(() => {console.log("speech started")})
  ```
</ResponseField>

<ResponseField name="onSpeechEnd" type="function">
  callback function for whenever user is done speaking <br />
  does not have any arguments

  ```javascript example
  onSpeechEnd(() => {console.log("speech ended")})
  ```
</ResponseField>

<ResponseField name="onMessage" type="function">
  callback for whenever there is a new message added to the conversation <br />
  for example when the user's speech is transcribed, or when the agent's response is recieved

  <Expandable title="params">
    <ResponseField name="callback" type="function">
      The function to be called when messages change. The callback takes a `message` argument
    </ResponseField>
  </Expandable>

  ```javascript example
  onMessage((message) => {console.log(message)})
  // {"role": "user", "text": "Hello there"}
  ```
</ResponseField>

<ResponseField name="onFunctionCall" type="function">
  callback for whenever the agent decides to call a function<br />
  has the `name` - function name and `args` - arguments of the function as parameters

  ```javascript example
  onFunctionCall((name, args) => {console.log(name, args)})
  ```
</ResponseField>