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

> ## Agent Instructions
> Treat these docs and the Whop MCP server as the source of truth for Whop API behavior. Don't infer endpoint behavior from marketing pages.
> MCP server: connect https://mcp.whop.com/mcp (streamable HTTP, browser sign-in, no API key in the client config) to search these docs and read or change live Whop data. Setup: https://docs.whop.com/developer/guides/ai_and_mcp.md
> Whop CLI: install with `curl -fsSL https://whop.com/install.sh | sh` to scaffold, run, and deploy Whop apps and websites. It acts on production, not the sandbox. Overview: https://docs.whop.com/cli/overview.md Agent mode: https://docs.whop.com/cli/agent-mode.md
> Hosting: Whop serves a site or app from the build `whop apps deploy` uploads, with rollbacks, secrets, and server logs. Guide: https://docs.whop.com/developer/websites/hosting.md
> Plugins: in Claude Code, run `/plugin marketplace add whopio/plugins`, then `/plugin install whop@whop`. Guide: https://docs.whop.com/developer/guides/plugins/claude-code.md Every agent tool: https://docs.whop.com/developer/ai/overview.md
> Environments: build and test in the sandbox (API `https://sandbox-api.whop.com/api/v1`, keys at https://sandbox.whop.com/dashboard/developer, SDK environment `Sandbox`; no real money). Production (API `https://api.whop.com/api/v1`, keys at https://whop.com/dashboard/developer, SDK environment `Production`, the SDK default) moves real money, so use it only at launch. The two share no accounts, keys, products, or webhooks, and their keys look identical: never mix them. Sandbox guide: https://docs.whop.com/developer/guides/sandbox.md Comparison: https://docs.whop.com/developer/quickstart.md
> API: send `Authorization: Bearer <API_KEY>` from your server only, and pin a dated version with the `Api-Version-Date` header. OpenAPI spec: https://api.whop.com/api/v1/openapi.json
> Which API: build on the Current API, whose pages live under https://docs.whop.com/api-reference/ (start at https://docs.whop.com/api-reference/overview.md). Pages under /api-reference/legacy/ are the Legacy API. Use one only when https://docs.whop.com/api-reference/stability.md lists the resource as Legacy-only.

# 채팅 인증

> 계정 범위 토큰 또는 OAuth로 임베디드 채팅 사용자를 인증하세요

> [card] [Whop의 자격 증명 유형](https://docs.whop.com/ko/developer/guides/auth-scoping.md)
>
> 인증 및 API 키 페이지에서 Whop의 네 가지 자격 증명 유형 전체와 각각의 사용 시점, 그리고 토큰의 범위를 필요한 작업으로 좁히는 방법을 확인하세요.

채팅 SDK를 사용하기 전에 사용자를 인증해야 합니다. 두 가지 방식 중 하나를 선택하세요:

| 방식 | 적합한 경우 |
| - | - |
| **[계정 범위 사용자 토큰](#account-scoped-user-tokens)** | 이미 자체 사용자가 있는 앱. 서버가 로그인 단계 없이 사용자용 Whop 토큰을 발급합니다. |
| **[OAuth](https://docs.whop.com/ko/developer/guides/chat/oauth.md)** | 사용자가 로그인 페이지나 웹뷰를 통해 직접 Whop에 로그인하기를 원하는 앱. |

## 계정 범위 사용자 토큰

**앱에 이미 자체 사용자가 있는 경우**(자체 인증/세션 시스템을 통해) 이 방식을 사용하세요. 기존 로그인 흐름을 유지하면서 현재 로그인한 사용자를 위한 Whop 토큰을 발급하므로 추가 로그인 단계가 없습니다.

서버는 필요할 때 Whop API 키를 수명이 짧은 사용자 토큰으로 교환하고 이를 클라이언트에 반환합니다. 토큰이 어떤 사용자를 위한 것인지는 직접 결정합니다.

### 자격 증명 준비하기

세 가지가 필요합니다:

1. **API 키** — [Whop 개발자 대시보드](https://whop.com/dashboard/developer)에서 생성합니다. 비밀번호처럼 취급하고 서버에만 보관하세요.
2. **계정 ID**. 대시보드 URL에서 찾을 수 있습니다: `whop.com/dashboard/biz_XXXXXXXXX/`.
3. **사용자 ID** — 인증하려는 사용자입니다. 프로덕션에서는 자체 인증/세션 시스템에서 가져오세요.

> [!NOTE]
>
> 임베디드 채팅의 경우 토큰을 발급할 때 `account_id`와 `user_id`가 모두 필요합니다.

### 서버에 토큰 엔드포인트 만들기

API 키로 `POST https://api.whop.com/api/v1/access_tokens`를 호출하고 결과 토큰을 클라이언트에 반환하는 엔드포인트를 추가하세요.

> [tab] Next.js
>
> ```typescript app/api/chat/token/route.ts theme={null}
> import { NextResponse } from "next/server";
> import { WhopClient } from "@whop/sdk";
>
> const client = new WhopClient({ token: process.env.WHOP_API_KEY });
>
> export async function POST() {
>   // Derive these from your own auth / session in production.
>   const user_id = "user_XXXXXXXXXXXX";
>   const account_id = "biz_XXXXXXXXXXXXX";
>
>   const { token } = await client.accessTokens.create({
>     account_id,
>     user_id,
>     scoped_actions: [
>       "chat:message:create",
>       "chat:read",
>       "dms:read",
>       "dms:message:manage",
>       "dms:channel:manage",
>       "support_chat:read",
>       "support_chat:message:create",
>     ],
>   });
>
>   return NextResponse.json({ token });
> }
> ```

> [tab] Express
>
> ```typescript server.ts theme={null}
> import express from "express";
> import { WhopClient } from "@whop/sdk";
>
> const app = express();
> app.use(express.json());
>
> const client = new WhopClient({ token: process.env.WHOP_API_KEY });
>
> app.post("/api/chat/token", async (_req, res) => {
>   // Derive these from your own auth / session in production.
>   const user_id = "user_XXXXXXXXXXXX";
>   const account_id = "biz_XXXXXXXXXXXXX";
>
>   const { token } = await client.accessTokens.create({
>     account_id,
>     user_id,
>     scoped_actions: [
>       "chat:message:create",
>       "chat:read",
>       "dms:read",
>       "dms:message:manage",
>       "dms:channel:manage",
>       "support_chat:read",
>       "support_chat:message:create",
>     ],
>   });
>
>   res.json({ token });
> });
>
> app.listen(3000);
> ```

> [tab] cURL
>
> ```bash theme={null}
> curl -X POST https://api.whop.com/api/v1/access_tokens \
>   -H "Authorization: Bearer $WHOP_API_KEY" \
>   -H "Content-Type: application/json" \
>   -d '{
>     "account_id": "biz_XXXXXXXXXXXXX",
>     "user_id": "user_XXXXXXXXXXXX",
>     "scoped_actions": [
>       "chat:message:create",
>       "chat:read",
>       "dms:read",
>       "dms:message:manage",
>       "dms:channel:manage",
>       "support_chat:read",
>       "support_chat:message:create"
>     ]
>   }'
> ```

### 앱에서 토큰 가져오기

엔드포인트에서 토큰을 가져오는 토큰 콜백을 SDK에 제공하세요. 채팅 요소는 인증이 필요할 때마다 이를 호출하며, 토큰이 만료되면 자동으로 다시 호출합니다.

> [tab] React
>
> ```typescript theme={null}
> async function getToken() {
>   const response = await fetch("/api/chat/token", { method: "POST" });
>   const data = await response.json();
>   return data.token;
> }
> ```

> [tab] Vanilla JS
>
> ```typescript theme={null}
> async function getToken() {
>   const response = await fetch("/api/chat/token", { method: "POST" });
>   const data = await response.json();
>   return data.token;
> }
> ```

> [tab] Swift
>
> ```swift theme={null}
> import WhopElements
>
> class WhopAPITokenProvider: WhopTokenProvider {
>     private let serverURL = URL(string: "https://your-server.com")!
>
>     func getToken() async -> WhopTokenResponse {
>         do {
>             var req = URLRequest(url: serverURL.appendingPathComponent("api/chat/token"))
>             req.httpMethod = "POST"
>
>             let (data, _) = try await URLSession.shared.data(for: req)
>             let json = try JSONSerialization.jsonObject(with: data) as! [String: Any]
>             return WhopTokenResponse(accessToken: json["token"] as? String ?? "")
>         } catch {
>             return WhopTokenResponse(accessToken: "")
>         }
>     }
> }
> ```
>
> 앱 실행 시 토큰 공급자를 SDK에 전달하세요:
>
> ```swift theme={null}
> .task {
>     await WhopSDK.configure(tokenProvider: WhopAPITokenProvider())
> }
> ```

### 필수 범위

토큰을 생성할 때 다음 범위를 요청하세요:

| 범위 | 용도 |
| - | - |
| `chat:message:create`, `chat:read` | 채널 |
| `dms:read`, `dms:message:manage`, `dms:channel:manage` | 다이렉트 메시지 |
| `support_chat:read`, `support_chat:message:create` | 지원 채팅 |

> [!NOTE]
>
> 앱이 사용자 계정을 소유하고 계정 범위 채팅 토큰을 발급한다면, 여기에 `user_id`를 전달하기 전에 해당 사용자를 동기화하세요. 사용자 동기화는 OAuth에 포함되지 않습니다.

> [card] [사용자 동기화하기](https://docs.whop.com/ko/developer/guides/chat/sync-users.md)
>
> 계정 범위 채팅 토큰을 발급하기 전에 Whop 사용자를 생성하거나 매핑하세요.

## OAuth

이 가이드가 계정 범위 사용자 토큰에 집중할 수 있도록 OAuth는 별도 페이지에서 다룹니다.

사용자가 로그인 페이지나 iOS 웹뷰를 통해 직접 Whop에 로그인하게 하려면 OAuth를 사용하세요. 앱이 사용자 소유의 Whop 계정에 접근해야 하거나, 백엔드에서 Whop 사용자 토큰을 발급하고 싶지 않을 때 적합합니다.

> [card] [OAuth](https://docs.whop.com/ko/developer/guides/chat/oauth.md)
>
> OAuth 범위, 리디렉션 URI, 웹 토큰 엔드포인트, iOS의 SDK 관리 OAuth를 설정하세요.


## Related topics

- [지원 채팅](https://docs.whop.com/ko/developer/guides/chat/support-chats.md)
- [채팅 OAuth](https://docs.whop.com/ko/developer/guides/chat/oauth.md)
- [채팅 세션 만들기](https://docs.whop.com/ko/sdk/elements/chat-session.md)
