Chat widget

Create a public chat token for the chat widget

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).

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)

Request body

namestring required

A name for your own overview, like the website it is for.

display_namestring 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_originsstring[] 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.

turnstileboolean

Ask for a bot check before a conversation starts. Default true.

max_conversations_per_dayinteger

New conversations per day through this token. Default 200, at most 1000.

Response

The token, with embed_code.

idstring uuid required

The id of the public chat token. Use it to change or revoke the token.

namestring required

Your name for the token, like the website it is for.

display_namestring 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.

tokenstring 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_originsstring[] required

The exact origins that may use the token, like https://www.example.com. A test token also works from localhost.

turnstileboolean required

Whether a visitor passes a bot check before a conversation starts.

max_conversations_per_dayinteger required

New conversations per day through this token, counted until midnight, Europe/Amsterdam.

revokedboolean required

true once the token is revoked: the widget stops working right away, also in open conversations.

revoked_atstring date-time nullable required

When the token was revoked.

last_used_atstring date-time nullable required

When a browser last used the token, to the minute.

created_atstring date-time required

When the token was created.

embed_codestring 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.

Changes

No recorded changes to this operation across all 1 revision of this API.