2

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.

The REST API can be used for a variety of tasks:
    • 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.
          Most HTTP clients and programming languages support both out of the box.

          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.

          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.

          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.

          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
          If your integration checks for changes on a timer, webhooks or a longer interval usually help more than a higher limit.

          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?

          Was this article helpful?

          89 out of 127 liked this article

          Still need help? Message Us