Skip to content

Add Configure to onboarding ​

This is the Quickstart inside an onboarding step, a settings row or a first-run screen. The chip and the redirect work as in Quickstart steps 2 and 3. What changes is the return (step 5): it shows the user what they brought, then starts them on something of their own. Everything else in the Quickstart still applies: credentials, the webhook, the commit and the tools. The screenshots show an app builder signed in as Nova Sandbrook, the sandbox user.

The page uses profileFor and refreshContext, the same helpers as the Quickstart:

ts
import { Configure } from "configure";

export const configure = new Configure({ apiKey: process.env.CONFIGURE_API_KEY, agent: process.env.CONFIGURE_AGENT });
export const profileFor = (userId: string) => configure.profile({ externalId: userId });   // one handle per user, keyed by your id

// Run on the return, and by the webhook whenever the profile changes (Quickstart step 6).
// Returns null until the user has connected.
export async function refreshContext(userId: string) {
  const read = await profileFor(userId).read({ sections: ["identity", "preferences", "summary", "integrations"] });
  const text = read.profile.linked ? read.profile.format() : null;
  await store.set(userId, { text, refreshedAt: Date.now() });   // `store` is your database: { text, refreshedAt } per user
  return text;
}

The chip and the return ​

The onboarding step has a chip that links to a route on your server. That route sends the user to Configure's page with a returnUrl. When they finish, Configure sends them back to that URL.

An onboarding screen titled Your AI already knows how you work, with the marks of four AI assistants joined to the app's mark, a Bring my context button and a Not now link

The onboarding step. Bring my context opens Configure's page.

The return route reads what the user brought, stores their context (Quickstart, step 6) and shows a welcome.

ts
const RETURN_URL = "https://yourapp.com/onboarding/return";   // a constant, never from the request
const APPS: Record<string, string> = { gmail: "Gmail", calendar: "Google Calendar", drive: "Google Drive", notion: "Notion", sheets: "Google Sheets", outlook: "Outlook" };

// The onboarding step's chip links here.
app.get("/onboarding/connect", async (req, res) => {
  const connect = await profileFor(req.user.id).connect({ returnUrl: RETURN_URL });
  res.redirect(connect.connect_url!);   // always set on a minted link; Configure's page, then back to RETURN_URL
});

// Configure sends the user here when they finish.
app.get("/onboarding/return", async (req, res) => {
  const { profile } = await profileFor(req.user.id).read({
    sections: ["identity", "imports", "integrations"],
  });
  if (!profile.linked) return res.redirect("/onboarding?step=2&notice=not-connected");   // they closed Configure's page early

  const brought = [
    ...Object.values(profile.imports)
      .filter((source) => source.memory_count)
      .map((source) => `${source.memory_count} memories from ${source.name}`),
    ...Object.entries(profile.integrations)
      .filter(([, app]) => app.connected)
      .map(([id]) => `${APPS[id] ?? id} connected`),
  ];

  await refreshContext(req.user.id);   // their first chat starts with their context
  res.render("welcome", { name: profile.identity.given_name, brought, next: "/onboarding?step=3" });
});

imports is keyed by assistant, such as { chatgpt: { name: "ChatGPT", memory_count: 9 } }. integrations is keyed by app, such as { gmail: { connected: true } }. For Nova, brought is ["9 memories from ChatGPT", "Gmail connected", "Google Calendar connected"].

A screen titled Your Configure account is connected, listing 9 memories from ChatGPT, Gmail and Google Calendar as connected, Google Drive and Notion with Connect buttons, and a Continue button

Back from Configure. Each checked row is an item in the brought list: 9 memories from ChatGPT, Gmail and Google Calendar.

The Connect buttons are the app's own. Each one connects a single app with connect({ returnUrl: RETURN_URL, app: "drive" }).

Two rules for the return route:

  • returnUrl must be https, even while you develop. It is a constant, never built from the request. Configure redirects there automatically when the Referer origin matches the returnUrl origin (browsers send the origin by default), or when the returnUrl host is in allowed_return_hosts on your developer account. Otherwise the user sees a button that names the host. That list is separate from npx configure add origin, which registers an OAuth callback and has no effect here.
  • Trust the user's context, not the URL. Anyone can type the return address into a browser. The route reads profile.linked and decides from that.

A new import can take a few minutes to process, so a short list on the first return is normal.

Start them on something that is theirs ​

After the welcome, don't drop the user on a blank screen. Read the summary and pitch one thing to build first, with a picture of it. Personalization shows how, along with other ideas.

A screen headed From your Configure context, Here's your first app, showing a phone with an app named Albatross Boat Log listing restoration tasks, a Build this app button and a Not now link

The next screen. The app comes from Nova's summary: she is restoring a sailboat and learning TIG welding.

What the user's context gives you, from read({ sections: ["identity", "summary", "integrations"] }):

FieldWhat it is
identity.given_name and identity.emailThe account the user signed in with. identity.email_verified says whether Configure verified the email.
identity.occupation and identity.locationInferred from the user's memories, so treat them as guesses. Each is left out when the context has too little to go on. identity.role is a copy of occupation.
integrations.<app>.connectedWhether the user connected that app, such as Gmail or Notion. Show connected apps as already on.
summaryA few sentences to several paragraphs on who the user is, what they are working on and how they like to work, depending on what Configure knows.

Then the home page shows suggestions based on the user's Configure context:

An app's home reading Let's make something new, Nova, with three suggestions under the composer, the first one starting with Continue Albatross Restoration, and the line From your Configure context

Suggestions based on Nova's Configure context, under the composer.

Keep their context current ​

An app that uses Configure only in onboarding still needs the webhook from Quickstart, step 6. Their context keeps growing as the user works in other apps, so a copy saved on sign-up day goes stale. The webhook runs the same refreshContext again.

ts
// Mount before express.json(): the handler checks the signature on the raw body.
app.post("/configure/webhook", configure.webhooks.handler(process.env.CONFIGURE_WEBHOOK_SECRET!, async (event) => {
  await refreshContext(event.data.user.external_id);   // your user id, the externalId you passed to profileFor
}));

Next ​

  • The chat version, and the rest of the loop: Quickstart.
  • What to do with the user's context once you have it: Personalization.
  • People who skipped this step, or signed up before you added it: Existing users.
  • Configure's own buttons for this step: Components.

Infrastructure to connect agents, apps, and chats