REST API
The tawk.to REST API allows developers to build integrations with third-party systems for automation and sync. This article covers what's possible, and how you can start using it.
You can find the REST API documentation at https://docs.tawk.to.
- list and export chat transcripts and tickets in bulk, filtered by date, status or tags
- create properties and manage property members
- get chat and ticket metrics, like missed chats and response times
- create and update contacts and organizations
- add widgets and change their settings
- manage Knowledge Base articles and categories
- manage webhooks
Note:
- REST API is currently in alpha. This means methods may change in ways that break existing integrations, and we don't offer any SLAs.
- Access to create REST API keys is currently only available on request.
Request access
Pick the auth model that fits what you're building:
- API key: your own scripts and integrations, running against your own properties. A key acts as your user, with your access. Request it through the REST API access request form. Once approved, Rest API Keys shows up in your profile settings.
- OAuth client: an app that other tawk.to users connect. Users authorize your app through standard OAuth2 and you get tokens limited to the scopes they approve. No API keys change hands. Chat with us to register your client: you get a client ID and secret, and we register your redirect URIs.
Create an API key
1. In your dashboard, click your profile image in the lower-left corner.

2. Click Edit Profile.

3. In the left menu, click Rest API Keys.

4. Click Create Key.

5. Your new key appears in the list.

Important: Keep your API key on your server, never in website code or a mobile app. Anyone who has it can call the API as you.
To delete a key, tick its checkbox and click the trash icon (Delete).

Authenticate your requests
Send every request over HTTPS. Plain HTTP requests are redirected, but by then your credentials have already been sent unencrypted.
- API key: use HTTP Basic Authentication, with your API key as the username and an empty password.
- OAuth client: send the access token in the Authorization header as a Bearer token.
Make your first request
Send a POST request to https://api.tawk.to/v1/ followed by the method name, with the arguments in a JSON body. For example, https://api.tawk.to/v1/agent.me returns the details of the user you are authenticated as.
Every response is JSON with a top-level ok field: true or false. When a request fails, the error field holds a short error code.
For every method and its arguments, please refer to the REST API documentation. Questions? Ask other developers in our developer community.
Every response is JSON with a top-level ok field: true or false. When a request fails, the error field holds a short error code.
For every method and its arguments, please refer to the REST API documentation. Questions? Ask other developers in our developer community.
Rate limits
Every request costs points from your user's budget. Your API keys and the OAuth apps you've authorized all share it, so creating more keys does not add capacity. For the current limits and what each request costs, see Rate limits and endpoint costs.
When a request is limited
The API answers with status 429 and a Retry-After header. Wait that many seconds, then retry.
Note: A 429 with a valid key can mean your IP address is blocked. This happens after repeated requests with a wrong or deleted key from that address. The block lifts by itself within 15 minutes, and we cannot lift it sooner. On a shared IP address, like an office network or an integration platform, it affects everyone behind it.
Note: A 429 with a valid key can mean your IP address is blocked. This happens after repeated requests with a wrong or deleted key from that address. The block lifts by itself within 15 minutes, and we cannot lift it sooner. On a shared IP address, like an office network or an integration platform, it affects everyone behind it.
Use webhooks instead of polling
Webhooks tell your system the moment something happens, like Chat Start, Chat End, New Chat Transcript or New ticket. They are not API requests, so they cost no points. See Creating and managing Webhooks.
If you do poll, keep the interval long. Checking for changes every few seconds uses up your budget fast.
If you do poll, keep the interval long. Checking for changes every few seconds uses up your budget fast.
Need higher limits?
Chat with us and include:
- the email address of the user whose keys you use, or your OAuth app's client ID
- what your integration does and which methods it calls
- how often it runs, or the volume you expect
- the X-Request-Id header from a limited response, and roughly when it happened
Important considerations
- Rotating keys: create a new key, switch your integration to it, then delete the old one. A deleted key that is still in use can get your IP address blocked.
- Widget only: if you only need to customize the widget on your site, the JavaScript API is simpler.
Related guides
Have a question we haven't covered or need support?
- Chat with us (live chat is available 24/7)
- Visit our Feedback page
- Schedule a call with us
