# Tutorial: Next.js

# Building a chat application with Sensay API in Next.js

This tutorial will guide you through building a modern chat application using Sensay API with Next.js and TypeScript. You'll learn how to integrate the API, handle authentication, manage users and replicas, and implement a fully functional chat interface.

## Demo

[![How to build a Sensay API in a Next.js app](https://i.ytimg.com/vi_webp/3At7jHmHWOs/mqdefault.webp)](https://www.youtube.com/watch?v=3At7jHmHWOs)

Find the source code at [https://github.com/sensay-io/chat-client-sample](https://github.com/sensay-io/chat-client-sample)

You can see a deployed version of the tutorial application at [https://sensay-api-chat-tutorial-sensay.vercel.app/](https://sensay-api-chat-tutorial-sensay.vercel.app/)

## Prerequisites

Before you begin, make sure you have:

- Node.js 18+ installed (we recommend using [fnm](https://github.com/Schniz/fnm) for version management)
- A Sensay API key (either an invitation code or an active API key)
- Basic knowledge of React, TypeScript, and Next.js
- Git installed to clone the sample repository

> info
> If you don't have an API key yet, you can request one by filling out the form at [Request API Key](https://docs.google.com/forms/d/11ExevrfKClc7IfQf7kjEpIiLqHtHE_E42Y752KV7mYY/) or redeem an invitation code if you have one.

## Getting started

### Clone the sample repository

Start by cloning the sample repository which contains all the necessary code to run a fully functional chat application:

```bash
git clone https://github.com/sensay-io/chat-client-sample.git
cd chat-client-sample
```

### Install dependencies

Once you've cloned the repository, install the required dependencies:

```bash
npm install
```

### Set up your environment

You can set up your environment in two ways:

#### Option 1: Using .env.local (Recommended for development)

Create a `.env.local` file in the root directory with your API key:

```
NEXT_PUBLIC_SENSAY_API_KEY=your_api_key_here
```

#### Option 2: In-app configuration

Alternatively, you can paste your API key directly in the application interface when prompted.

### Run the application

Start the development server:

```bash
npm run dev
```

This will start the application on `http://localhost:3000`. Open this URL in your browser to access the chat application.

## Understanding the application architecture

The sample application demonstrates a complete integration with Sensay API, handling:

- Organization authentication
- User creation and management
- Replica creation and retrieval
- Chat functionality

### Key components

- **SDK Generation**: The application uses [openapi-typescript-codegen](https://github.com/ferdikoomen/openapi-typescript-codegen) to generate a fully typed client from the Sensay API OpenAPI specification.
- **Authentication Flow**: Demonstrates both organization-level and user-level authentication.
- **Chat Interface**: A responsive UI built with React and Tailwind CSS.

### Application initialization flow

When you first start the application, it performs the following steps:

1. Initializes a client using your provided API key
2. Checks if a sample user exists, creating one if necessary
3. Checks for existing replicas, creating a default one if none exists
4. Sets up the authenticated chat session

This flow mirrors the steps you would typically take when integrating Sensay API into your own applications.

## Key implementation patterns

Let's examine the core patterns used in the application that you can adapt for your own projects.

### Client initialization

The application initializes the Sensay client in two different ways:

```typescript
// Organization-level authentication (admin access)
const organizationClient = new Client({
  BASE: 'https://api.sensay.io',
  HEADERS: {
    'X-ORGANIZATION-SECRET': apiKey,
    'Content-Type': 'application/json',
  },
});

// User-level authentication
const userClient = new Client({
  BASE: 'https://api.sensay.io',
  HEADERS: {
    'X-ORGANIZATION-SECRET': apiKey,
    'X-USER-ID': userId,
    'Content-Type': 'application/json',
  },
});
```

### User management

The application demonstrates how to create users and check if they exist:

```typescript
// Check if user exists
try {
  const user = await organizationClient.users.getUsersGet({
    id: userId,
  });
  console.log('User exists:', user);
  return user;
} catch (error) {
  if (error.status === 404) {
    // Create user if not found
    const newUser = await organizationClient.users.createUsersPost({
      id: userId,
    });
    console.log('Created new user:', newUser);
    return newUser;
  }
  throw error;
}
```

### Replica management

Similarly, the application shows how to list and create replicas:

```typescript
// List replicas for the user
const replicas = await userClient.replicas.listReplicasGet();

if (replicas.items.length === 0) {
  // Create a new replica if none exists
  const newReplica = await userClient.replicas.createReplicaPost({
    name: `Sample Replica ${Date.now()}`,
    shortDescription: 'A helpful assistant for demonstration purposes',
    greeting: 'Hello! I am a sample replica. How can I help you today?',
    ownerID: userId,
    private: false,
    slug: `sample-replica-${Date.now()}`,
    llm: {
      provider: 'openai',
      model: 'gpt-4o',
    },
  });
  return newReplica.uuid;
}

// Use the first available replica
return replicas.items[0].uuid;
```

### Chat interaction

The chat completion functionality demonstrates how to send messages and receive responses:

```typescript
// Send a chat message and get a response
const response = await userClient.replicaChatCompletions.createChatCompletionPost({
  replicaUuid: replicaId,
  content: message,
});

if (response.success) {
  // Process and display the response
  setMessages((prev) => [
    ...prev,
    { role: 'assistant', content: response.content },
  ]);
}
```

## Regenerating the SDK

One of the key features of this integration approach is the ability to quickly adapt to API changes by regenerating the SDK. The Sensay API evolves frequently, and regenerating your SDK ensures you always have access to the latest features.

To regenerate the SDK:

```bash
npm run generate-sdk
```

This script fetches the latest OpenAPI specification and generates updated TypeScript client code in the `src/sdk` directory.

> info
> We recommend regenerating your SDK regularly to stay current with the API. The script uses [openapi-typescript-codegen](https://github.com/ferdikoomen/openapi-typescript-codegen), which provides type-safe access to all endpoints.

## Troubleshooting common issues

### Authentication errors

If you encounter authentication errors:

- Verify your API key is correct and not expired
- Check that you're including the proper headers for your requests
- Ensure you're using the correct user ID when authenticating as a user

### "User not found" errors

This typically means the user ID you're using doesn't exist in your organization:

- Verify the user has been created
- Check that you're using the correct organization API key
- Ensure you're not mixing user IDs between different organizations

### SDK type errors

If you encounter TypeScript errors after regenerating the SDK:

- Make sure your code is updated to match any breaking changes in the API
- Check the [Versioning documentation](/topic/topic-versioning) for information about API changes
- Join the [Sensay API Telegram Channel](https://t.me/sensay_api) for announcements about breaking changes

## Next steps

Now that you have a working chat application, consider:

1. **Customizing the UI**: Adapt the interface to match your brand and requirements
2. **Adding Training**: Use the [Training API](/topic/topic-getting-deeper-knowledge-base) to make your replicas more knowledgeable
3. **Implementing Additional Features**: Explore features like voice integration or multiple replica support
4. **Deploying Your Application**: Deploy to services like Vercel, Netlify, or your own infrastructure

## Additional resources

- [Video tutorial](https://www.youtube.com/watch?v=3At7jHmHWOs)
- [GitHub repository](https://github.com/sensay-io/chat-client-sample)
- [Live demo](https://sensay-api-chat-tutorial-sensay.vercel.app/)
- [Sensay documentation](https://docs.sensay.io)
- [Sensay API Telegram channel](https://t.me/sensay_api)
- [OpenAPI tools](https://tools.openapis.org)