tawk.to REST API v1.1.0
This summary is self-contained: every endpoint, scope, and schema referenced below is documented in this skill's own files (endpoints.md, knowledge-base.md, markdown-to-kb.md, reference-article.json). The original tawk.to documentation lives at https://docs.tawk.to; consult it directly for anything not covered here.
Core conventions
- Base URL:
https://api.tawk.to/v1/{method}. Methods are dotted, RPC-style names (e.g. knowledge-base.article.create).
- Every endpoint is
POST with a JSON body. There are no GET/PUT/DELETE verbs; "get", "list", "delete" are method-name suffixes.
- Headers:
Content-Type: application/json, Accept: application/json, plus an Authorization header.
- Property scoping: almost every body requires
propertyId. KB calls also require a siteId (a KB site is a per-language container). Get a propertyId from property.list.
Authentication (two schemes)
Most endpoints accept either scheme. Each endpoint declares the OAuth2 scope it needs (see endpoints.md).
API key (HTTP Basic Auth) - simplest for server-to-server scripts.
- Header:
Authorization: Basic <base64(apiKey + ":")> (API key as username, empty password).
- The API key comes from the tawk.to dashboard (REST API section).
OAuth2 - Bearer tokens, for apps acting on behalf of users.
- Header:
Authorization: Bearer {access-token}.
- Authorize endpoint:
https://oauth.tawk.to/oauth2/auth
- Token endpoint:
https://oauth.tawk.to/oauth2/token (code exchange and refresh)
- Flows: Authorization Code (
response_type=code) and Implicit Grant (response_type=token).
# API key example (note the trailing colon before base64-encoding)
curl -X POST https://api.tawk.to/v1/property.list \
-H 'Content-Type: application/json' \
-H "Authorization: Basic $(printf '%s:' "$TAWK_API_KEY" | base64)" \
-d '{}'
Response and error shape
- Success:
{ "ok": true, "data": { ... } } (some write endpoints return just { "ok": true }).
- Error:
{ "ok": false, "error": "<code>", "message": "<detail>" }.
| HTTP |
error value |
Meaning |
| 400 |
validation_error |
Bad body / invalid field |
| 403 |
forbidden (insufficient_scope) |
Token lacks the required scope |
| 404 |
not_found |
Resource missing |
| 409 |
conflict (resource_locked) |
Conflicting state / locked resource |
| 429 |
rate_limited |
Rate limit exceeded; back off and retry |
Always check ok before reading data. On 429, retry with exponential backoff.
Endpoint groups (full details in endpoints.md)
| Group |
Methods |
Primary scopes |
| Property |
property.create-site, property.info, property.list |
property_* |
| Widgets |
widgets.add/get/update/remove, widgets.cards.*, widgets.global-settings.*, widgets.api-key.list |
widgets_* |
| Members |
agent.info, agent.me, members.list, members.invite, members.*-invite, members.enable/disable, members.update-permissions, members.remove |
members_* |
| Chats |
chat.get, chat.list |
chat_history_read |
| Tickets |
ticket.get, ticket.list |
tickets_read |
| Tabs |
tabs.add/get/list/remove/update, tabs.available |
tabs_* |
| Knowledge-Base |
knowledge-base.article.*, .category.*, .site.*, .site-link.*, .settings.*, .create, .fonts.list, .language.list |
knowledgebase_* |
| Webhook |
webhooks.create/get/list/update/delete |
webhooks_* |
| Metrics |
metrics.chats, metrics.tickets-new/-reopened/-resolved/-responses |
metrics_read |
| Contacts |
contact.attribute.list-custom, contact.person.get |
contact_* |
Knowledge-Base: read this before building KB automation
The KB is the focus of this skill. Two facts drive the whole design:
- Article bodies are NOT markdown or HTML. They are an ordered array of typed content blocks (
header, paragraph, image, code, video, divider, table). To publish markdown you must parse it and emit these blocks.
- There is no file/asset upload endpoint. Image and banner blocks take a
url only. tawk.to does not host your images. You must upload images to your own public store (Cloudflare R2 or DigitalOcean Spaces), then put the public URL in the block.
Resource hierarchy: Property -> Knowledge Base -> Site (per language) -> Categories + Articles.
- Full content-block schemas, every KB request/response body, and category/site CRUD:
knowledge-base.md.
- The end-to-end "markdown file + image links -> published tawk article" workflow, including the R2/Spaces upload step and a markdown-to-blocks mapping table with a reference Node implementation:
markdown-to-kb.md.
- A complete ready-to-POST
article.create body exercising every block type (header, paragraph with inline HTML, unordered + ordered lists, blockquote, image, code, divider, table, video), with HTML shapes matching a live draft: reference-article.json.
Minimal create-article flow
1. property.list -> pick propertyId
2. knowledge-base.site.list -> pick siteId (or knowledge-base.site.create)
3. (optional) knowledge-base.category.create / .list -> category ids
4. Upload local images to R2/Spaces -> collect public URLs
5. Convert markdown -> contents[] blocks (swap local image paths for hosted URLs)
6. knowledge-base.article.create -> returns { data: { article: { id } } }
Working method
- Confirm which auth scheme and scopes the target endpoint needs (
endpoints.md).
- For KB writes, confirm the content-block JSON validates against the schema (
knowledge-base.md) before sending; the API rejects unknown block fields with validation_error.
- Prefer creating articles as
status: "draft" first, verify rendering in the dashboard, then knowledge-base.article.update to published.
- Treat the snapshot file as authoritative when this skill is ambiguous.
1---2name: "tawk-to-api-stinger"3license: AGPL-3.0-or-later4description: "Integrate the tawk.to REST API. Use for contacts, chats, tickets, webhooks, metrics, widgets, or knowledge-base articles."5metadata:6 source: https://skillmd.com/skills/legioncodeinc/tawk-to-api-stinger7---89# tawk.to REST API v1.1.01011This summary is self-contained: every endpoint, scope, and schema referenced below is documented in this skill's own files (`endpoints.md`, `knowledge-base.md`, `markdown-to-kb.md`, `reference-article.json`). The original tawk.to documentation lives at https://docs.tawk.to; consult it directly for anything not covered here.1213## Core conventions1415- **Base URL**: `https://api.tawk.to/v1/{method}`. Methods are dotted, RPC-style names (e.g. `knowledge-base.article.create`).16- **Every endpoint is `POST`** with a JSON body. There are no GET/PUT/DELETE verbs; "get", "list", "delete" are method-name suffixes.17- **Headers**: `Content-Type: application/json`, `Accept: application/json`, plus an `Authorization` header.18- **Property scoping**: almost every body requires `propertyId`. KB calls also require a `siteId` (a KB site is a per-language container). Get a `propertyId` from `property.list`.1920## Authentication (two schemes)2122Most endpoints accept either scheme. Each endpoint declares the OAuth2 scope it needs (see `endpoints.md`).23241. **API key (HTTP Basic Auth)** - simplest for server-to-server scripts.25 - Header: `Authorization: Basic <base64(apiKey + ":")>` (API key as username, empty password).26 - The API key comes from the tawk.to dashboard (REST API section).27282. **OAuth2** - Bearer tokens, for apps acting on behalf of users.29 - Header: `Authorization: Bearer {access-token}`.30 - Authorize endpoint: `https://oauth.tawk.to/oauth2/auth`31 - Token endpoint: `https://oauth.tawk.to/oauth2/token` (code exchange and refresh)32 - Flows: Authorization Code (`response_type=code`) and Implicit Grant (`response_type=token`).3334```bash35# API key example (note the trailing colon before base64-encoding)36curl -X POST https://api.tawk.to/v1/property.list \37 -H 'Content-Type: application/json' \38 -H "Authorization: Basic $(printf '%s:' "$TAWK_API_KEY" | base64)" \39 -d '{}'40```4142## Response and error shape4344- **Success**: `{ "ok": true, "data": { ... } }` (some write endpoints return just `{ "ok": true }`).45- **Error**: `{ "ok": false, "error": "<code>", "message": "<detail>" }`.4647| HTTP | `error` value | Meaning |48|------|---------------|---------|49| 400 | `validation_error` | Bad body / invalid field |50| 403 | `forbidden` (`insufficient_scope`) | Token lacks the required scope |51| 404 | `not_found` | Resource missing |52| 409 | `conflict` (`resource_locked`) | Conflicting state / locked resource |53| 429 | `rate_limited` | Rate limit exceeded; back off and retry |5455Always check `ok` before reading `data`. On 429, retry with exponential backoff.5657## Endpoint groups (full details in `endpoints.md`)5859| Group | Methods | Primary scopes |60|-------|---------|----------------|61| Property | `property.create-site`, `property.info`, `property.list` | `property_*` |62| Widgets | `widgets.add/get/update/remove`, `widgets.cards.*`, `widgets.global-settings.*`, `widgets.api-key.list` | `widgets_*` |63| Members | `agent.info`, `agent.me`, `members.list`, `members.invite`, `members.*-invite`, `members.enable/disable`, `members.update-permissions`, `members.remove` | `members_*` |64| Chats | `chat.get`, `chat.list` | `chat_history_read` |65| Tickets | `ticket.get`, `ticket.list` | `tickets_read` |66| Tabs | `tabs.add/get/list/remove/update`, `tabs.available` | `tabs_*` |67| **Knowledge-Base** | `knowledge-base.article.*`, `.category.*`, `.site.*`, `.site-link.*`, `.settings.*`, `.create`, `.fonts.list`, `.language.list` | `knowledgebase_*` |68| Webhook | `webhooks.create/get/list/update/delete` | `webhooks_*` |69| Metrics | `metrics.chats`, `metrics.tickets-new/-reopened/-resolved/-responses` | `metrics_read` |70| Contacts | `contact.attribute.list-custom`, `contact.person.get` | `contact_*` |7172## Knowledge-Base: read this before building KB automation7374The KB is the focus of this skill. Two facts drive the whole design:75761. **Article bodies are NOT markdown or HTML.** They are an ordered array of typed **content blocks** (`header`, `paragraph`, `image`, `code`, `video`, `divider`, `table`). To publish markdown you must parse it and emit these blocks.772. **There is no file/asset upload endpoint.** Image and banner blocks take a `url` only. tawk.to does not host your images. You must upload images to your own public store (Cloudflare R2 or DigitalOcean Spaces), then put the public URL in the block.7879Resource hierarchy: **Property -> Knowledge Base -> Site (per language) -> Categories + Articles**.8081- Full content-block schemas, every KB request/response body, and category/site CRUD: **`knowledge-base.md`**.82- The end-to-end "markdown file + image links -> published tawk article" workflow, including the R2/Spaces upload step and a markdown-to-blocks mapping table with a reference Node implementation: **`markdown-to-kb.md`**.83- A complete ready-to-POST `article.create` body exercising every block type (header, paragraph with inline HTML, unordered + ordered lists, blockquote, image, code, divider, table, video), with HTML shapes matching a live draft: **`reference-article.json`**.8485### Minimal create-article flow8687```881. property.list -> pick propertyId892. knowledge-base.site.list -> pick siteId (or knowledge-base.site.create)903. (optional) knowledge-base.category.create / .list -> category ids914. Upload local images to R2/Spaces -> collect public URLs925. Convert markdown -> contents[] blocks (swap local image paths for hosted URLs)936. knowledge-base.article.create -> returns { data: { article: { id } } }94```9596## Working method97981. Confirm which auth scheme and scopes the target endpoint needs (`endpoints.md`).992. For KB writes, confirm the content-block JSON validates against the schema (`knowledge-base.md`) before sending; the API rejects unknown block fields with `validation_error`.1003. Prefer creating articles as `status: "draft"` first, verify rendering in the dashboard, then `knowledge-base.article.update` to `published`.1014. Treat the snapshot file as authoritative when this skill is ambiguous.