---
title: "Create a public chat token for the chat widget"
method: POST
path: "/chat-tokens"
tags: ["Chat widget"]
---

# Create a public chat token for the chat widget

`POST /chat-tokens`

## Request

- Base URL: `https://api.hypamoon.com/api/v1`
- URL: `https://api.hypamoon.com/api/v1/chat-tokens`
- Auth: one of:
  - HTTP bearer
  - OAuth 2 (authorization code, authorization URL `https://app.hypamoon.com/oauth/authorize`, token URL `https://api.hypamoon.com/oauth/token`, scopes: `chat:write`)

Creates a public chat token and returns it with embed_code, the script tag to paste on the website. The widget then chats with the project's assistant (set with PUT /assistant) directly from the visitor's browser, with no backend of your own. The token is not a secret: it is in the page source. It can only chat, only from allowed_origins (exact origins like https://www.example.com, no path and no wildcard), with a bot check and its own limits, and you can revoke it. Your API key stays on the server. A live token needs at least one https origin; a test key creates a test token (hm_pubtest_) that also works from localhost. At most 10 origins per token, and at most 1000 new conversations per day per token (default 200).

## Request body

- ChatTokenInput: A new public chat token for the website widget.
  - `name` string, required: A name for your own overview, like the website it is for.
  - `display_name` string, nullable: The name the assistant uses for the business in the chat window, like "Knip": in the greeting ("You are chatting with the digital assistant of Knip.") and in its answers. Leave it out or null to use the name of the site the widget is on, and otherwise the project name.
  - `allowed_origins` string[], required: The exact origins that may use this token, like https://www.example.com (scheme and host, no path, no wildcard), at most 10. A live token needs at least one https origin. A test token may always be used from localhost.
  - `turnstile` boolean: Ask for a bot check before a conversation starts. Default true.
  - `max_conversations_per_day` integer: New conversations per day through this token. Default 200, at most 1000.

## Response `201`

The token, with embed_code.

- ChatToken: A public chat token for the chat widget on a website.
  - `id` string, uuid, required: The id of the public chat token. Use it to change or revoke the token.
  - `name` string, required: Your name for the token, like the website it is for.
  - `display_name` string, nullable, required: The name the assistant uses for the business in the chat window and its greeting, or null: then the name of the site the widget is on, and otherwise the project name.
  - `token` string, required: The public chat token: hm_pub_ (live) or hm_pubtest_ (test project) plus 24 characters. Not a secret: it goes in the page source of your website.
  - `mode` 'live' | 'test', required: live or test, from the project the key belongs to.
  - `allowed_origins` string[], required: The exact origins that may use the token, like https://www.example.com. A test token also works from localhost.
  - `turnstile` boolean, required: Whether a visitor passes a bot check before a conversation starts.
  - `max_conversations_per_day` integer, required: New conversations per day through this token, counted until midnight, Europe/Amsterdam.
  - `revoked` boolean, required: true once the token is revoked: the widget stops working right away, also in open conversations.
  - `revoked_at` string, date-time, nullable, required: When the token was revoked.
  - `last_used_at` string, date-time, nullable, required: When a browser last used the token, to the minute.
  - `created_at` string, date-time, required: When the token was created.
  - `embed_code` string, required: The script tag for your website, with this token in it. Paste it before </body>.
  - `kind` 'chat' | 'form', required: chat: the chat widget, the cart, the checkout and forms. form: only forms that post to a collection with public_write (made by Hypamoon for a form on a site); it cannot chat.
  - `warnings` object[]: Only in the answer of POST /chat-tokens, and only when there is something to tell. The token is created either way.
    - `code` 'assistant_not_set', required: The project has no assistant yet, so the widget cannot answer visitors.
    - `message` string, required: What this means, in plain words.
    - `next_step` string, required: What to do next, with the tool or route to use.

## Other responses

- `400`: Bad Request: invalid_json.
- `401`: Unauthorized: unauthorized, missing_api_key, invalid_api_key, api_key_revoked, project_deleted.
- `403`: Forbidden: project_not_enabled, key_mode_mismatch, missing_scope, verification_required.
- `422`: Unprocessable Content: validation_failed.
- `429`: Too Many Requests: rate_limited.
- `500`: Internal Server Error: internal_error.
- `503`: Service Unavailable: service_unavailable.

---

[API](https://skmtc.dev/hypamoon/apis/hypamoon-api.md) · [All operations](https://skmtc.dev/hypamoon/apis/hypamoon-api/llms.txt) · [OpenAPI document](https://skmtc.dev/hypamoon/apis/hypamoon-api/revisions/9f0b90004c06?raw)