On 3/1/23 OpenAI released an API for Chat-GPT. In this post, we’ll walk through putting together a full-stack chat app, and add some features. 

We’ll use React and Vite, though any React framework works. We’ll use <QuickConvex /> as the backend, where our server-side functions will run, and where we’ll store our app’s data. 

To see this in action, the code is [here](https://github.com/ianmacartney/convex-chat-gpt), and a running version is [here](https://convex-chat-gpt-f6rq.vercel.app/) (for now).

To run this yourself, you’ll need to make an [OpenAI account](https://platform.openai.com/signup) and [get an API key](https://platform.openai.com/account/api-keys).

If you’re familiar with Convex, you can skip ahead to step 2.

# 0. Bootstrap a Vite React app

If you don’t already have an app, we can make one:

```bash
npm create vite@latest
```

I picked `convex-chatgpt` as the project name, `React` as the framework, and `Javascript` as the variant.

At this point, if we run:

```bash
npm install
npm run dev
```

we have a locally running webapp.

Let’s change `src/App.jsx` to list messages and have a form to submit messages:

<details>
<summary>App.jsx</summary>
    
    ```tsx
    import {useState} from "react";
    import "./App.css";
    
    function App() {
      const messages = [
        {author: "user", body: "Hello, world"},
      ];
      const sendMessage = body =>
        console.log("Trying to send: " + body);
      const [newMessageText, setNewMessageText] =
        useState("");
    
      return (
        <div className="App">
          {messages.map((message, i) => (
            <p key={i}>
              <span>{message.author}: </span>
              <span style={{ whiteSpace: "pre-wrap" }}>
                {message.body ?? "..."}
              </span>
            </p>
          ))}
          <form onSubmit={(e) => {
            e.preventDefault();
            setNewMessageText("");
            sendMessage(newMessageText);
          }}>
            <input
              value={newMessageText}
              onChange={e => setNewMessageText(e.target.value)}
              placeholder="Write a message…"
            />
            <input type="submit" value="Send" disabled={!newMessageText} />
          </form>
        </div>
      );
    }
    
    export default App;
    ```
</details>    

At this point, we have an app that shows a static list of messages and logs to the console when trying to send a message.

# 1. Add Convex

This is similar to the Convex [quickstart](https://docs.convex.dev/quickstart). In a new terminal (leave the other one running `npm run dev`):

```bash
npm install convex
npx convex init
```

If you haven’t used convex before, you’ll be prompted to log in, create an account, etc. I picked `convex-chatgpt` as the project name.

Let’s add the ability to send messages and list messages. We will add functions that run in Convex (on a server) that will read and write to the database with a [query](https://docs.convex.dev/understanding/convex-fundamentals/functions#query-functions) and [mutation](https://docs.convex.dev/understanding/convex-fundamentals/functions#mutation-functions).

Add `convex/messages.ts`:

```jsx
import { query, mutation } from "./_generated/server";

export const list = query(async ({ db }) => {
  return await db.query("messages").take(100);
});

export const send = mutation(async ({ db }, body) => {
  await db.insert("messages", {
    body,
    author: "user",
  });
  const botMessageId = await db.insert("messages", {
    author: "assistant",
  });
});
```

In a separate terminal from the one running `npm run dev`, run `npx convex dev`. This will deploy these functions to your new Convex backend, and as you edit the functions, it will automatically re-deploy. This will ask you to save the deployment URL into your `.env` and `.env.local` files: these point at your convex backends for your production and development deployments. We’ll just be working with the development deployment.

To access Convex from inside React, you’ll need to add a `<ConvexProvider>` context at the top level of your app. Edit `main.jsx`:

```jsx
...
import { ConvexProvider, ConvexReactClient } from "convex/react";

const convex = new ConvexReactClient(import.meta.env.VITE_CONVEX_URL);

ReactDOM.createRoot(document.getElementById("root")).render(
  <React.StrictMode>
    <ConvexProvider client={convex}>
      <App />
    </ConvexProvider>
  </React.StrictMode>,
);
```

We can then use these functions from `App.jsx`:

```jsx
function App() {
  const messages = useQuery("messages:list") || [];
  const sendMessage = useMutation("messages:send");
	...
```

Great! Now we have messages being written to and from the database. Try it out! Those new to Convex will be surprised to see that adding new messages will automatically result in the `useQuery("messages:list")` hook returning new messages. This is part of the magic of Convex. Learn more about it [here](https://docs.convex.dev/understanding/convex-fundamentals/functions#reactivity). 

You can check out your data in the dashboard: `npx convex dashboard`. 

You may note that the query and mutation are named by the `filename:function`. See more about this [here](https://docs.convex.dev/using/writing-convex-functions#defining-convex-functions).

You’ll notice every time we send a message, there’s a “…” message from the assistant. Next let’s update that message from chatGPT. 

# 2. Send a message to the ChatGPT API

So far we’ve been working with a [query](https://docs.convex.dev/understanding/convex-fundamentals/functions#query-functions) and [mutation](https://docs.convex.dev/understanding/convex-fundamentals/functions#mutation-functions), which are Convex functions that interact with the database. In order to interact with external services, we need to do that in an “[action](https://docs.convex.dev/understanding/convex-fundamentals/functions#action-functions)” - which is a Convex function that isn’t inside a deterministic environment and isn’t part of a database transaction. This frees us to do things with side effects, such as making requests to OpenAI’s API. We’ll do this in a few steps.

## Fetching messages to send to ChatGPT

In our `send` mutation, we can grab the latest 10 messages to send to ChatGPT using a database query:

```jsx
export const send = mutation(async ({ db }, body) => {
  //... insert messages to the table
  const messages = await db
    .query("messages")
    .order("desc")
    .filter((q) => q.neq(q.field("body"), null))
    .take(21);
  messages.reverse();
  return { messages, botMessageId };
});
```

This orders messages in descending order (sorted by creation time unless you use a different [index](https://docs.convex.dev/using/indexes)), filters out messages with no body (for instance, the new placeholder system message), and takes the first 21 (which are the 21 most recent messages). It then reverses the list so it’s ordered in ascending time order. I picked 21 so that we’ll have 10 pairs of user/bot messages, followed by the latest prompt. It returns the messages to be used as input to the chat completion API, which we'll add next.

## Creating the action

We’ll use the `openai` npm package. You can install it with:

```bash
npm install openai
```

Make a new file: `convex/actions/openai.js`:

```jsx
import { Configuration, OpenAIApi } from "openai";
import { action } from "../_generated/server";

export const chat = action(async ({ runMutation }, body) => {
  const { messages, botMessageId } = await runMutation("messages:send", body);
  const fail = async (reason) => throw new Error(reason);
  // Grab the API key from environment variables
  // Specify this in your dashboard: `npx convex dashboard`
  const apiKey = process.env.OPENAI_API_KEY;
  if (!apiKey) {
    await fail("Add your OPENAI_API_KEY as an env variable");
  }
  const configuration = new Configuration({ apiKey });
  const openai = new OpenAIApi(configuration);

  const openaiResponse = await openai.createChatCompletion({
    model: "gpt-3.5-turbo",
    messages: [
      {
        role: "system",
        content: instructions,
      },
      ...messages.map(({ body, author }) => ({
        role: author,
        content: body,
      })),
    ],
  });
  if (openaiResponse.status !== 200) {
    await fail("OpenAI error: " + openaiResponse.statusText);
  }
  const body = openaiResponse.data.choices[0].message.content;
	console.log("Response: " + body);
});
```

This will first send the messages with the send mutation we modified, getting in return the list of messages and message ID to update with the bot’s message. It will then make a request to the `gpt-3.5-turbo` model, passing in one system message with instructions (hard-coded for now), followed by each message. We’re turning our body & author fields into “role” and “content”. See their docs [here](https://platform.openai.com/docs/guides/chat) for more details on the API.

## Add your API key to the dashboard

To authenticate requests to OpenAI, you’ll need to add your [API key](https://beta.openai.com/account/api-keys) to the Convex dashboard, so your action (which runs on Convex’s servers) has access to it. Go to your dashboard with `npx convex dashboard` and on the left panel go into Settings and add the key with the name `OPENAI_API_KEY`. While you’re there, you can add it as an env variable to both your production and development deployments by toggling the dropdown in the left panel.

![Dashboard side panel](https://cdn.sanity.io/images/ts10onj4/production/8aa4d6a158df734f3d64e1eb15333528e37c92e5-263x392.png?w=300)


## Triggering the action from the UI

We can change our call to `useQuery("messages:send")` to

```jsx
const sendMessage = useAction("actions/openai:chat");
```

Note the action is addressed by the path to the file (`actions/openai`) and the function (`chat`). The API is the same (taking one argument, `body`), so it’s a drop-in replacement!

At this point, if you run it, it will send a request to ChatGPT and console.log the response. Convex prints Convex function logs to the browser’s console, though you can also see them in the [dashboard](https://dashboard.convex.dev/), to prove to yourself it’s running in the cloud. Now let’s show them in the UI.

## Updating the message with the reply

In order to get the response into the chat message, we’ll want to update the empty placeholder message we added. Treat each call to a mutation as a transaction. Once we called our first mutation, the messages were committed to the database and the UI could show the new messages before doing the slow call to OpenAI. Once we get the response, we update the bot’s message and the UI will update automatically via the `messages:list` query. We’ll add a new mutation in the `convex/messages.js` file:

```jsx
export const update = mutation(async ({ db }, messageId, patch) => {
  await db.patch(messageId, patch);
});
```

This patches the specified message. You could pass in `{body: "hi"}` to change the message’s body to “hi,” for example. Since the first mutation returned the `botMessageId`, we can use that from the action in `convex/actions/openai.js`:

```jsx
export const chat = action(async ({ runMutation }, body) => {
  const { messages, botMessageId } = await runMutation("messages:send", body);

  // Call OpenAI

  await runMutation("messages:update", botMessageId, {
    body: openaiResponse.data.choices[0].message.content,
    // Track how many tokens we're using for various messages
    usage: openaiResponse.data.usage,
    updatedAt: Date.now(),
    // How long it took OpenAI
    ms: Number(openaiResponse.headers["openai-processing-ms"]),
  });
});
```

While we’re here, we can store a bunch of interesting data into the message along with the body. Convex’s database is flexible enough to store [strings, numbers, javascript objects, `Map`s, etc.](https://docs.convex.dev/using/types) while also letting you nail down a [schema](https://docs.convex.dev/using/schemas) later to get typescript types, autocomplete, etc. 

🎉 Now you have chatGPT replying to your messages!

# Summary

In this post, we made a full-stack web app to chat with OpenAI’s ChatGPT API. Let us know [in Discord](https://convex.dev/community) what you think, and if you’d like to see some extensions:

- [Customizing the identity you’re talking to.](https://stack.convex.dev/adding-personality-to-chatgpt-3)
- [Moderating the identities and messages to prevent harmful content.](https://stack.convex.dev/moderating-chatgpt-content-full-stack)
- Create new message threads. (See the [code](https://github.com/ianmacartney/convex-chat-gpt) for how it's done!)

Let's build a full-stack chat app to talk to ChatGPT on its new API!

Building a Full-Stack ChatGPT app

Trying to build an app on top of OpenAI’s Dall-E or ChatGPT? Avoid violating the OpenAI [Usage policies](https://platform.openai.com/docs/usage-policies/platform-policy) or showing inappropriate data to your users by leveraging their [Moderation API](https://platform.openai.com/docs/guides/moderation/overview). In this post, we’ll look at how to use it to flag messages before sending them to Chat-GPT. This will build on the [Building a full-stack ChatGPT app](https://stack.convex.dev/full-stack-chatgpt-app) post, but the approach is generally applicable.

New to Convex? [Convex](https://convex.dev/) is a backend application platform - we make I,t easy to build apps where you need to run code in the server and store data in a database. We run your functions, host your data, and much more. It’s a great fit for working with powerful APIs like OpenAI, as it allows you to build a whole application around powerful AI models without running any servers yourself.

Without further ado, let’s look at how to use OpenAI’s moderation endpoints. 

### **Initializing the API:**

The core piece of code is in the `convex/actions/openai.js` file. This takes less than a millisecond, so we can run it on each request.

```jsx
const apiKey = process.env.OPENAI_API_KEY;
if (!apiKey) {
  await fail(
    "Add your OPENAI_API_KEY as an env variable in the " +
      "[dashboard](https://dasboard.convex.dev)"
  );
}
const configuration = new Configuration({ apiKey });
const openai = new OpenAIApi(configuration);
```

### **Using the moderation API:**

```jsx
// Check if the message is offensive.
const modResponse = await openai.createModeration({
  input: body,
});
const modResult = modResponse.data.results[0];
```

### **Updating the user’s message if the message was flagged:**

```jsx
if (modResult.flagged) {
  await runMutation("messages:update", userMsgId, {
    error:
      "Your message was flagged: " +
      Object.entries(modResult.categories)
        .filter(([, flagged]) => flagged)
        .map(([category]) => category)
        .join(", "),
  });
  return;
}
```

As a reminder, this will call a mutation in `convex/messages.js` that will patch the message, adding an `error` field:

```jsx
export const update = mutation(async ({ db }, messageId, patch) => {
  await db.patch(messageId, patch);
});
```

### Why not check beforehand?

It’s a good point that we could do moderation before inserting the message into the database in the first place. In my case, I wanted to show results immediately and commit the *intent* to send a message. If I waited for moderation, it would take an extra 500ms+ before adding the message and appearing in the UI. For moderating identity creation (see [this post](https://stack.convex.dev/adding-personality-to-chatgpt-3) on adding identities), I moderate first for simplicity. I return an error when the user tries to create a lousy identity. If it felt too long, I could add a spinner while creating the identity. One nice thing about Convex mutations and actions is that you can `await` the results in the UI to know when they succeed/fail, even if you don’t care about their return value. For instance:

```jsx
setLoading(true);
setError(null);
const errorMsg = await addIdentity(
  newIdentityName,
  newIdentityInstructions
);
if (errorMsg) setError(errorMsg);
setLoading(false);
```

### ************************************************************************Refreshing the client’s copy of messages with the new field:************************************************************************

This happens automatically! One of the cool things about Convex is that queries are reactive by default. Here’s how it works:

1. We originally fetched a list of 100 recent messages in the UI with a query called `list` in `convex/messages.js`, which runs in Convex’s cloud. This result is cached automatically, thanks to guarantees provided by Convex’s [deterministic runtime](https://docs.convex.dev/understanding/convex-fundamentals/functions#determinism). 
2. When we sent a new message, we inserted a message into the “messages” table. 
3. Because the `list` query was for the most recent 100 messages, the results were automatically invalidated and re-executed. The new results get pushed to clients over a WebSocket,  triggering a React render for the component(s) that called `useQuery('messages:list')` with the new messages.
4. The same thing happens when we update a message to add an `error` field. As if by magic, the message with the `error` field shows up in the UI and we can render a different UI.

### **Rendering flagged messages in the UI:**

To avoid showing flagged messages, we can do some standard React gating:

```jsx
<span style={{ whiteSpace: "pre-wrap" }}>
  {message.error ? "⚠️ " + message.error : message.body ?? "..."}
</span>
```

Here we show an Error with ⚠️ pre-pended if there is one, otherwise a body if there is one, otherwise “…” for messages we haven’t updated with a bot’s response.

### Filtering flagged messages out of future bot input

We avoided sending the message to ChatGPT when we initially detected bad input. Still, when we send our next set of messages to the API, we don’t want to include the bad input in historical messages either. To do that, we can adjust our filter in `messages:send`:

```jsx
const messages = await db
      .query("messages")
      .filter((q) => q.eq(q.field("error"), null))
      .filter((q) => q.neq(q.field("body"), null))
      .take(21); // 10 pairs of prompt/response and our most recent message.
```

We avoid getting any messages with an “error” field and avoid all the messages without a body, for instance, bot messages that weren’t updated (such as when we bailed due to flagged input).

# Summary

In this post, we looked at how to moderate what content you send to ChatGPT, from the UI to the API calls. I hope it was helpful. Let us know [in Discord](https://convex.dev/community) what you think!

In this post, we’ll look at how to use the moderation API to flag messages before sending them to Chat-GPT, and patterns for handling these errors in a full-stack React app.

Moderating ChatGPT Content: Full-Stack

Building with OpenAI's APIs is fun. By leveraging [Convex](https://convex.dev) to store your data and run server-side functions, you can have a GPT-powered app in no time.

This is a follow-up to [Building a full-stack ChatGPT app](https://stack.convex.dev/full-stack-chatgpt-app), where we set up a Chat-GPT-like chat app using Convex as the backend. In that example, we used a fixed identity string. In this post we’ll look at how to store multiple personalities in the database and provide them in the chat, to enable changing personalities mid-conversation.

See the code [here](https://github.com/ianmacartney/convex-chat-gpt) and a working demo [here](https://convex-chat-gpt-f6rq.vercel.app/).

<BuildWithConvex />

To customize the identity you pass into ChatGPT, you can pass a “system” message to the OpenAI API. See more details on this API [here](https://platform.openai.com/docs/guides/chat). In our case, before having multiple identities, the code looks like this:

```js
const openaiResponse = await openai.createChatCompletion({
  model: "gpt-3.5-turbo",
  messages: [
    {
      role: "system",
      content: instructions,
    },
    ...messages.map(({ body, author }) => ({
      role: author,
      content: body,
    })),
  ],
});
```

Let’s store multiple identities in the Convex database and pick which one to use. 

### Adding and listing identities

Let’s make `convex/identity.js`:

```js
import { query, mutation } from "./_generated/server";

export const list = query(async ({ db }) => {
  const identities = await db.query("identities").collect();
  return identities.map((identity) => identity.name);
});

export const add = mutation(async ({ db }, name, instructions) => {
  const existing = await db
    .query("identities")
    .filter((q) => q.eq(q.field("name"), name))
    .unique();
  if (existing) {
    await db.patch(existing._id, { instructions });
  } else {
    await db.insert("identities", { name, instructions });
  }
});
```

This will run on the server and list the identity names or allow you to add one. Before it adds one, it will check if it already exists and, if so, update it, so there aren’t duplicate names. Because of Convex’s transaction isolation (which is the strictest kind, called “serializable isolation”), we’ll never have duplicate identities with the same name, simply because we queried for that name first. Read more about that [here](https://docs.convex.dev/understanding/deep-dive/occ).

Note that by only returning the identity names, we are hiding the instructions from the clients. This is a big difference between Convex and a platform like Firebase that gives you direct access to databases from the browser. By running code on the server, we can use code to limit what information is returned to clients.

### UI for adding identities

Adding a UI to add an identity is similar to sending messages with an `<AddIdentity />` component:

<details>
<summary>`AddIdentity` component </summary>
```jsx
function AddIdentity() {
  const addIdentity = useMutation("identity:add");
  const [newIdentityName, setNewIdentityName] = useState("");
  const [newIdentityInstructions, setNewIdentityInstructions] = useState("");

  return (
    <form
      onSubmit={async (e) => {
        e.preventDefault();
        await addIdentity(newIdentityName, newIdentityInstructions);
        setNewIdentityName("");
        setNewIdentityInstructions("");
      }}
    >
      <input
        value={newIdentityName}
        onChange={(event) => setNewIdentityName(event.target.value)}
        placeholder="Identity Name"
      />
      <textarea
        value={newIdentityInstructions}
        onChange={(event) => setNewIdentityInstructions(event.target.value)}
        placeholder="GPT3 Instructions"
        rows={2}
        cols={40}
      />
      <input
        type="submit"
        value="Add Identity"
        disabled={!newIdentityName || !newIdentityInstructions}
      />
    </form>
  );
}
```
</details>

Let’s add some identities. Some I like: 

**Rubber Duck**

> You are curious and respond with helpful one-sentence questions.
> 

**Supportive Friend**

> You are a supportive and curious best friend who validates feelings and experiences and will give advice only when asked for it. You give short responses and ask questions to learn more.
> 

**CS Coach**

> You are a highly technically trained coach with expertise in technology and best practices for developing software. Respond with concise, precise messages and ask clarifying questions when things are unclear.
> 

### Using an identity from the UI

To use an identity, we can add a `select` in our form to pick an identity, and pass that identity name in the `messages:send` mutation:

```jsx
function App() {
  const messages = useQuery("messages:list") || [];
  const sendMessage = useMutation("messages:send");
  const [newMessageText, setNewMessageText] = useState("");

  const identities = useQuery("identity:list") || [];
  const [identityName, setIdentityName] = useState("");
  //...
      <form
        onSubmit={(e) => {
          e.preventDefault();
          setNewMessageText("");
          sendMessage(newMessageText, identityName);
        }}
      >
        <select
          value={identityName}
          onChange={(e) => setIdentityName(e.target.value)}
        >
          <option value={""} disabled={identityName}>
            Select an identity
          </option>
          {identities.map((name) => (
            <option key={name} value={name}>
              {name}
            </option>
          ))}
        </select>
    //...
```

### Looking up the identity

In our `messages:send` function, which runs on the server, we can accept the new `identityName` and look up the identity’s instructions to pass to ChatGPT:

```js
export const send = mutation(async ({ db }, body, identityName) => {
  //...
  const identity = await db
    .query("identities")
    .filter((q) => q.eq(q.field("name"), identityName))
    .unique();
  if (!identity) throw new Error("Unknown identity: " + identityName);
  const botMessageId = await db.insert("messages", {
    author: "assistant",
    identityId: identity._id,
  });
  //...
  return { messages, botMessageId, instructions: identity.instructions };
```

Two things to note:

1. We search for the identity by name. If there were a lot of them, we’d use an [index](https://docs.convex.dev/using/indexes), but for small tables doing a filter is just fine.
2. We’re storing the `identityId` into the bot’s message, so we can later know which identity responded to each message.

We can also pass the instructions for each bot message, by looking up the instructions if there is an `identityId`:

```js
await Promise.all(
    messages.map(async (msg) => {
      if (msg.identityId) {
        msg.instructions = (await db.get(msg.identityId)).instructions;
      }
    })
  );
```

We look up each identity by doing `db.get` in a separate async function, and use `Promise.all` to wait for the result of each of the async functions.

<details>
<summary>All together, `send` now looks like:</summary>

```js
export const send = mutation(async ({ db }, body, identityName) => {
  await db.insert("messages", {
    body,
    author: "user",
  });
  const identity = await db
    .query("identities")
    .filter((q) => q.eq(q.field("name"), identityName))
    .unique();
  if (!identity) throw new Error("Unknown identity: " + identityName);
  const botMessageId = await db.insert("messages", {
    author: "assistant",
    identityId: identity._id,
  });
  const messages = await db
    .query("messages")
    .order("desc")
    .filter((q) => q.neq(q.field("body"), null))
    .take(10);
  messages.reverse();
  await Promise.all(
    messages.map(async (msg) => {
      if (msg.identityId) {
        msg.instructions = (await db.get(msg.identityId)).instructions;
      }
    })
  );
  return { messages, botMessageId, instructions: identity.instructions };
});
```
</details>

### Passing the identity to ChatGPT

In our `convex/actions/openai.js` `chat` function, we can now de-structure the `instructions` return instead of hard-coding it:

```js
export const chat = action(async ({ runMutation }, body, identityName) => {
  const { messages, botMessageId, instructions } = 
    await runMutation("messages:send", body, identityName);
  //...
```

Now the response will be a function of what messages have been sent, and what the identity’s instructions are.

To also give GPT context on what its identity was for previous messages, we can sprinkle system messages into the messages we pass to the API:

```js
const gptMessages = [];
let lastInstructions = null;
for (const { body, author, instructions } of messages) {
  if (instructions && instructions !== lastInstructions) {
    gptMessages.push({
      role: "system",
      content: instructions,
    });
    lastInstructions = instructions;
  }
  gptMessages.push({ role: author, content: body });
}
if (instructions !== lastInstructions) {
  gptMessages.push({
    role: "system",
    content: instructions,
  });
  lastInstructions = instructions;
}
const openaiResponse = await openai.createChatCompletion({
  model: "gpt-3.5-turbo",
  messages: gptMessages,
});
```

The goal here is to remind GPT what identity it had for each message it sent. This API is new, so I bet there’s a lot of tweaking we can do with the prompts here to make it work better. For instance, maybe we should be telling it “Ignore previous system instructions for the following messages. Now act like this: (new instructions)”. If you get something working in a better way, let me know [in Discord](https://convex.dev/community)!

### Showing the identity’s name instead of “assistant” in the UI

Currently, all the messages in the UI say “assistant” - let’s show the identity we named by looking up the identities dynamically. Convex supports [relationships](https://docs.convex.dev/using/document-ids#references-and-relationships) in this way.

When listing our messages, we can look up the identity’s name to return. In `convex/messages.ts`:

```js
export const list = query(async ({ db }) => {
  const messages = await db.query("messages").take(20);
  return Promise.all(
    messages.map(async (message) => {
      if (message.identityId) {
        const identity = await db.get(message.identityId);
        message.identityName = identity.name;
      }
      return message;
    })
  );
});
```

We look up each identity by doing `db.get` in a separate async function, and use `Promise.all` to return the result of each of the functions as an array. This is the common pattern for doing join-like behavior with Convex. This way you can execute the reads in parallel but do all your business logic and lookups in JavaScript.

On the client, we can now show the `identityName` if it’s defined instead of just the author in `App.jsx`:

```jsx
<span>{message.identityName ?? message.author}: </span>
```

And we can also default the chat identity to be the last-used identity message, when you load the page with a useEffect:

```jsx
useEffect(() => {
  if (identities.length && !identityName) {
    const lastMessage = messages[messages.length - 1];
    if (lastMessage && identities.indexOf(lastMessage.identityName) !== -1) {
      setIdentityName(lastMessage.identityName);
    } else {
      setIdentityName(identities[0]);
    }
  }
}, [messages, identities, identityName]);
```

### Summary

We’ve now added the ability to change the instructions to ChatGPT on how to respond, so we can have a conversation and be changing the identity mid-stream. See the code [here](https://github.com/ianmacartney/convex-chat-gpt) and a working demo [here](https://convex-chat-gpt-f6rq.vercel.app/). Note, that code & demo has some more features than just what we’ve done in this post.

How to store multiple personalities Convex and provide them to the chatGPT API, enabling changing personalities mid-conversation. This is a follow-up to Building a full-stack ChatGPT app. 

Adding Personality to ChatGPT-3

[Convex](https://convex.dev) supports [HTTP endpoints](https://docs.convex.dev/using/http-endpoints#defining-http-endpoints), meaning your backend can receive requests not only from Convex clients, such as the [ConvexReactClient](https://docs.convex.dev/using/project-setup#configure-the-convex-client), but also from third-party webhooks and other clients that want to communicate with a custom HTTP API. 

Currently, endpoints have a simple router. In this post, we’ll look at how to add more advanced endpoint features, such as:

- Dynamic routes or slug routes — e.g. `users/:userId`
- Middleware — e.g. check auth on all routes under `/api/*` or implementing CORS
- Helpers for validating an incoming Request’s query params or body
- Helpers for formatting a JSON response or text response
- Custom 404 (Not Found) responses

While it’s possible to build these yourself on top of Convex primitives, existing JS libraries already do a great job at this. In this post, we’re going to go through how you can leverage [Hono](https://hono.dev/) with Convex [HTTP endpoints](https://docs.convex.dev/using/http-endpoints#defining-http-endpoints). To use it yourself, you can grab  [`honoWithConvex.ts`](https://github.com/get-convex/convex-helpers/blob/main/convex/lib/honoWithConvex.ts) in the [convex-helpers repo](https://github.com/get-convex/convex-helpers). We’ll also look more generally at how to extend Convex HTTP endpoint behavior. 

Note: you don’t need to use TypeScript, but I will use it in my examples because both Hono and Convex offer slick TypeScript support! 

# Using Hono with Convex

To use Hono, you’ll need to:

1. `npm install hono` in your project. 
2. Copy [`honoWithConvex.ts`](https://github.com/get-convex/convex-helpers/blob/main/convex/lib/honoWithConvex.ts) into your `convex/` directory. I like to keep it in `convex/lib/` to separate it from my application logic.
3. In `convex/http.ts`, import `Hono`, `HonoWithConvex`, and `HttpRouterWithHono` and use them like so:

```jsx
import { Hono } from "hono";
import { HonoWithConvex, HttpRouterWithHono } from "./lib/honoWithConvex";

const app: HonoWithConvex = new Hono();

// Add your routes to `app`. See below 

export default new HttpRouterWithHono(app);
```

The `HonoWithConvex` is just a type that tells Hono to expect the Convex [HttpEndpointCtx](https://docs.convex.dev/api/modules/server#httpendpointctx) as its [env](https://hono.dev/api/context#env) binding. `HttpRouterWithHono` does the magic to connect Hono routes to Convex HTTP endpoints.

Let’s look at a few ways to use Hono:

## Slug routing and response formatting

For illustration, we’ll implement an endpoint from the [Convex demo for HTTP endpoints](https://github.com/get-convex/convex-demos/tree/main/http) to use Hono. Here’s an example handler showcasing several of Hono’s features:

```typescript
// See https://github.com/sshader/hono-convex/blob/main/convex/http.ts#L24
// Routing with slugs
app.get("/listMessages/:userId{[0-9]+}", async (c) => {
  // Extracting a token from the URL!
  const userId = c.req.param("userId");

  // Running a Convex query
  const messages = await c.env.runQuery("listMessages:byAuthor", userId);

  // Helpers for pretty JSON!
  c.pretty(true, 2);
  return c.json(messages);
});
```

…and an example response:

```bash
$ curl https://happy-animal-123.convex.site/listMessages/123
[
  {
    "_creationTime": 1677798437141.091,
    "_id": {
      "$id": "messages|lqMHm5kDS9m6fBsSnx5L2g"
    },
    "author": "User 123",
    "body": "Hello world"
  },
]
```

## Input validation

Here’s another handler with input validation:

```typescript
// See https://github.com/sshader/hono-convex/blob/main/convex/http.ts#L36
app.post(
  "/postMessage",
  // Body validation!
  zValidator(
    "json",
    z.object({
      author: z.string().startsWith("User "),
      body: z.string().max(100),
    })
  ),
  async (c) => {
    // With type safety!
    const { body, author } = c.req.valid("json");
    await c.env.runMutation("sendMessage", body, author);
    return c.text("Sent message!");
  }
);
```

…and an example response:

```bash
$ curl -d '{ "body": "Hello world", "author": "123" }'  https://happy-animal-123.convex.site/postMessage
{
  "success": false,
  "error": {
    "issues": [
      {
        "code": "invalid_string",
        "validation": {
          "startsWith": "User "
        },
        "message": "Invalid input: must start with \"User \"",
        "path": [
          "author"
        ]
      }
    ],
    "name": "ZodError"
  }
}
```

## Middleware: Adding CORS

Another example, copying from [Hono docs](https://hono.dev/middleware/builtin/cors). This adds CORS support to the `/api/*` and `/api2/*` routes with different configurations.

```typescript
import { cors } from 'hono/cors'
...
// See https://github.com/sshader/hono-convex/blob/main/convex/http.ts#L55
app.use('/api/*', cors())

app.use(
  '/api2/*',
  cors({
    origin: 'http://examplesite.com',
    allowHeaders: ['X-Custom-Header', 'Upgrade-Insecure-Requests'],
    allowMethods: ['POST', 'GET', 'OPTIONS'],
    exposeHeaders: ['Content-Length', 'X-Kuma-Revision'],
    maxAge: 600,
    credentials: true,
  })
)
```

The `.use` function registers a handler for all `/api/*` requests. As we’ll see below, you can use this for a variety of situations, including logging.

## Custom 404 responses

To set up a custom 404, we can do:

```typescript
// See https://github.com/sshader/hono-convex/blob/main/convex/http.ts#L12
// Custom 404
app.notFound(c => {
  return c.text("Oh no! Couldn't find a route for that", 404);
});
```

See [https://hono.dev/](https://hono.dev/) for more features.

<BuildWithConvex />

# Under the hood

Curious about how to extend Convex [HTTP endpoints](https://docs.convex.dev/using/http-endpoints#defining-http-endpoints) for your own purposes? Read on!

## Extending routes using the `/` prefix

If the routing options aren’t flexible enough for your use case, you can handle all HTTP requests with a single `httpEndpoint` and do complex routing there. For instance, instead of using `HttpRouterWithHono`, we could define a single route per HTTP method in `convex/http.ts`:

```typescript
import { httpRouter, ROUTABLE_HTTP_METHODS } from "convex/server";
import { httpEndpoint } from "./_generated/server";
import { HonoWithConvex } from "./lib/honoWithConvex";

const app: HonoWithConvex = new Hono();

// Add your routes to `app`.

const http = httpRouter();
for (const routableMethod of ROUTABLE_HTTP_METHODS) {
	http.route({
		pathPrefix: "/",
		method: routableMethod,
		handler: httpEndpoint(async (ctx, request: Request) => {
			return await app.fetch(request, ctx);
		}),
	})
}
export default http;
```

We could stop here — we can now use Hono and Convex together! But we could make a couple of additional improvements to leverage the [Convex dashboard](https://dashboard.convex.dev/).

## Using middleware to add per-route logging

Here’s what we see in the [Convex dashboard](https://dashboard.convex.dev/) under “Logs” given the approach of registering an `httpEndpoint` per method:

![Logs showing GET /*](https://cdn.sanity.io/images/ts10onj4/production/06c3e0c48a26da60a29a095e5c6f5e184d6ae2b0-1302x310.png?w=700)

All our GET requests will appear as `GET /*` even when we have multiple routes.

We can pretty easily get a little more information using one of Hono’s features — logging middleware:

```typescript
import { logger } from "hono/logger";
import stripAnsi from "strip-ansi";

app.use(
  "*",
  logger((...args) => {
    console.log(...args.map(stripAnsi));
  })
);
```

Now the [Convex dashboard](https://dashboard.convex.dev/) looks more like this:

![Logs with GET /listMessages/123](https://cdn.sanity.io/images/ts10onj4/production/e1ff98ab9fdcc7e5eee3b741eca5025b98c762e9-1350x524.png?w=700)

Note: these say `0ms` because they’re running in [Convex’s deterministic environment that provides a different `Date.now()`](https://docs.convex.dev/understanding/convex-fundamentals/functions#determinism).

## Subclassing `HttpRouter` (the `HttpRouterWithHono` approach)

If we want the fullest integration with the [Convex dashboard](https://dashboard.convex.dev/), we’d like to see something like this under “Logs”, where we show the routed path:

![Logs showing GET /listMessages/:userId](https://cdn.sanity.io/images/ts10onj4/production/212100c96760c3d1b86ec79a59ce3d5246a60ca3-1526x514.png?w=700)

And then see a corresponding entry with metrics under the “Functions” tab:

![Functions metrics for GET /listMesssages/:userId](https://cdn.sanity.io/images/ts10onj4/production/9527a4a514b8fb6aa98023e27da58b90fbdede3b-970x922.png?w=450)

The code needed for this behavior is in  [`honoWithConvex.ts`](https://github.com/get-convex/convex-helpers/blob/main/convex/lib/honoWithConvex.ts).

**How does it work?**

`HttpRouterWithHono` is a subclass of the Convex [`HttpRouter`](https://docs.convex.dev/api/classes/server.HttpRouter) which overrides two special methods:

- `getRoutes` returns a list of `[path, method, handler]`, which we use to populate the Functions page on the dashboard.
- `lookup(path, method)` returns `[handler, path, method]`. Convex will run `handler` when responding to the request and use the `path` and `method` for metrics and logging (so this should match a path + method combo from `getRoutes`)
    - As an example, I wanted `lookup("/listMessages/123", "GET")` to return `"/listMessages/:userId{[0-9]+}"` for the path and `"GET"` for the method.

The implementation I added is not optimal (it loops through all the routes), but it still works! The Convex router is very flexible, so there are many options for configuring how your HTTP endpoints get routed and show up in the dashboard. 

Now, we can use Convex with Hono and take advantage of most of the features provided in the Convex dashboard!

# Summary

In this post, we looked at how to use Hono with Convex, including how to extend Convex’s HTTP endpoints to add your own functionality. Let us know what you think in [our discord](https://convex.dev/community) and if you end up using Hono and Convex together! ❤️

Adding advanced HTTP Endpoint functionality by extending Convex with Hono.

Advanced HTTP Endpoints: Convex ❤️ Hono

This is part of a series of posts about [building a multiplayer game on Convex](https://stack.convex.dev/building-a-multiplayer-game). In this post, we’ll explore using Dall-E via the OpenAI API. The code is [here](https://github.com/get-convex/convex-demos/tree/main/dall-e-storage-action) if you want to play around with it. We will make a chat app where you can type in an image description as a slash command, and it will generate and insert that image into the chat. On the server, it will:

1. Configure an OpenAI client.
2. Check that the prompt is not offensive using their moderation API.
3. Get the short-lived image URL from Dall-E.
4. Download the image.
5. Upload the image into Convex [File Storage](https://docs.convex.dev/using/file-storage), getting a storage ID.
6. Insert the storage ID into a new message.
7. When serving the message to the client, we will generate a URL based on the storage ID, which they can put in an `<img>` tag directly.

This is now possible using [File Storage](https://docs.convex.dev/using/file-storage) and a Convex [Action](https://docs.convex.dev/using/actions), a serverless function that can have side-effects[^1], comparable to AWS lambda. Read below for how to use OpenAI with Convex, or check out the code [here](https://github.com/get-convex/convex-demos/tree/main/dall-e-storage-action).

# Using OpenAI in Convex

## Set up Convex

Create a Convex app by cloning [the demo](https://github.com/get-convex/convex-demos/tree/main/dall-e-storage-action) and running `npm i; npm run dev`. If you want a fresh project, see the [Tutorial](https://docs.convex.dev/tutorial/welcome-to-convex).

If you’re writing your app from scratch, create an `actions` directory in the `convex/` folder, and add a file. Mine is [`convex/actions/sendDallE.js`](https://github.com/get-convex/convex-demos/blob/main/dall-e-storage-action/convex/actions/sendDallE.js). 

## Configuring OpenAI

1. To use OpenAI, you need an API account. Sign up [here](https://beta.openai.com/signup).
2. Generate an API key [here](https://platform.openai.com/account/api-keys) by clicking “Create new secret key” and copying the text.
3. Store the API key Convex’s [Environment Variables](https://docs.convex.dev/using/environment-variables), where you can store secrets. Go to your project’s dashboard by running `npx convex dashboard` in your project directory or finding it on [dashboard.convex.dev](https://dashboard.convex.dev). Open the project settings on the left and enter it with the key `OPENAI_API_KEY`. I’d recommend saving it in both your Production and Development deployments unless you want the published version of your app to use a different key. There is a toggle to switch between them.
4. Configure the client in your [action](https://docs.convex.dev/using/actions). If you get type errors, `npm install openai`:
    
    ```jsx
    import { Configuration, OpenAIApi } from "openai";
    const configuration = new Configuration({
      apiKey: process.env.OPENAI_API_KEY,
    });
    const openai = new OpenAIApi(configuration);
    ```
    

## Using the Moderation API

The moderation API is useful for checking whether a prompt is obscene or will be rejected by OpenAI. For our purposes, we’ll check if it flags the message:

```jsx
const modResponse = await openai.createModeration({
  input: prompt,
});
const modResult = modResponse.data.results[0];
if (modResult.flagged) {
  throw new Error(
    `Your prompt was flagged: ${JSON.stringify(modResult.categories)}`
  );
}
```

The `categories` object can be used for more fine-grained moderation. It has a score per category. Consult the [moderation documentation](https://platform.openai.com/docs/guides/moderation/overview) for more details.

## Generating an image with Dall-E

You can consult the [image generation documentation](https://platform.openai.com/docs/guides/images) for more details, but for our purposes, the code is:

```jsx
const opanaiResponse = await openai.createImage({
  prompt,
  n: 1,
  size: "256x256",
});
const dallEImageUrl = opanaiResponse.data.data[0]["url"];
```

Now we have a URL to the image. However, this URL [only lasts for an hour](https://platform.openai.com/docs/guides/images/usage?lang=node.js#:~:text=URLs%20will%20expire%20after%20an%20hour). If we want to be able to see this image in the chat longer term, we need to store it.

## Downloading the image

To download the image, we use the [`node-fetch` NPM library](https://www.npmjs.com/package/node-fetch#common-usage). 

```jsx
const imageResponse = await fetch(dallEImageUrl);
const image = Buffer.from(await imageResponse.arrayBuffer());
```

Now we have the image in memory and can store it in Convex.

## Storing the image in Convex

Storing the image in Convex is a two-step process:

1. Generate an upload URL.
2. Upload to that URL, getting a storage ID in return.

### Generating an upload URL

[Upload URLs](https://docs.convex.dev/using/file-storage#uploading-files) are created in a [Convex mutation](https://docs.convex.dev/understanding/convex-fundamentals/functions#mutation-functions). This allows your application to authorize uploads, for instance, if you wanted only to allow certain users to upload. My mutation is very simple:

```jsx
// in convex/sendMessage.js
export const generateUploadUrl = mutation(async ({ storage }) => {
  return await storage.generateUploadUrl();
});
```

One thing to note is that this can’t live in the `convex/actions` directory. Actions are run in a different environment than queries and mutations. You can read more about that [here](https://docs.convex.dev/understanding/convex-fundamentals/functions#action-functions). I put mine in [`convex/sendMessage.js`](https://github.com/get-convex/convex-demos/blob/main/dall-e-storage-action/convex/sendMessage.js).

To use the `generateUploadUrl` from our action:

```jsx
// in sendDallE.js
const postUrl = await runMutation("sendMessage:generateUploadUrl");
```

### Upload to Convex File Storage

It might be counter-intuitive to upload from within a Convex function since that function is already “in” Convex. However, by providing this upload URL, you can have more control over how you upload. For instance, instead of downloading the whole image at once, you could have streamed the data in and streamed it to Convex file storage.

```jsx
const postImageResponse = await fetch(postUrl, {
  method: "POST",
  headers: { "Content-Type": imageResponse.headers.get("content-type") },
  body: image,
});
// Get the storageId for the upload.
const { storageId } = await postImageResponse.json();
```

## Store the storage ID in the database

The storage ID returned from the upload URL is now a permanent identifier of this data. You can store it in your database however you’d like. In our example, we store it in a new chat message.

```jsx
// in sendDallE.js action
await runMutation("sendMessage", storageId, author, "dall-e");
```

And the mutation that stores it, for completeness:

```jsx
// in sendMessage.js
export default mutation(async ({ db }, body, author, format) => {
  // A bit of a hack; we are storing the storage ID in the "body"
  await db.insert("messages", { body, author, format });
});
```

## Serving the image to the client

In Convex, clients subscribe to [queries](https://docs.convex.dev/using/database-queries). For instance, in our frontend React component, we can do:
```jsx
const messages = useQuery("listMessages") || [];
...
{messages.map(message => (
  <Message author={message.author} body={message.body} format={message.format} key={message._id.toString()} />
)};
```
That query maps to a serverless function: the default export of `convex/listMessages.js`. To return the image URL in messages we return to clients, we generate a URL from the storage ID. For our app, we will change each storage ID into a URL. In `convex/listMessages.js`:

```jsx
export default query(async ({ db, storage }) => {
  const messages = await db.query("messages").collect();
  for (const message of messages) {
    if (message.format === "dall-e") {
		  // Replace the storage ID with a URL in the "body"
      message.body = await storage.getUrl(message.body);
    }
  }
  return messages;
});
```
This URL won’t change on each request, so you don’t have to worry about caching the URL on the client. The HTTP response also has cache headers so you don't need to worry about client-side image caching either.

# Performance

One thing I discovered while building this is how slow the OpenAI API calls can be. In my testing, the moderation call took 500ms, and the image generation could take 5+ seconds, sometimes taking over 60s and timing out the request. To make this a good user experience, adding a loading indicator is important. On the client, I used this code:

```tsx
// In React jsx:
const [sending, setSending] = useState(false);
const sendDallE = useAction("actions/sendDallE");
...
setSending(true);
try {
  await sendDallE(prompt, name);
} finally {
  setSending(false);
}
```

# Summary

In this post, we used Convex to fetch an image from OpenAI’s image generation service based on a user-provided prompt. Read about [the game](https://whose-prompt-is-it-anyways.vercel.app/) I've developed on Convex using Dall-E APIs [here](https://stack.convex.dev/building-a-multiplayer-game) for more tips, or [read the code](https://github.com/get-convex/multiplayer-game-with-dall-e) to see how I added error handling and more.


[^1]: This differs from other Convex functions like `query` and `mutation`, which do not have side effects, allowing them to provide features like automatic retries, reactive updates, serializable transaction isolation, and more! Read more about it [here](https://docs.convex.dev/understanding/deep-dive/occ).

Use Convex to fetch an image from OpenAI’s image generation service based on a user-provided prompt.

Integration