Hyphenate Docs

Start Chatting with Hyphenate!

Welcome to the Hyphenate docs portal. Here you'll find comprehensive guides and technical documentation to help you integrate Hyphenate In-App Chat.

Get Started

REST API Overview


Visit REST API Reference to interact with Hyphenate's REST APIs.

API Client Libraries

Client libraries allow you to make API service calls from your backend. They are available in multiple languages, i.e. Java, Node.js, Python, PHP, etc. Hyphenate client libraries are open source and available for download on GitHub, where you can find installation instructions and sample code:

or generate client library via Swagger hub

API Docs and Try out

REST API Reference

Swagger hub doc

Swagger and Postman API files

Base URL

All endpoints are relative to this base URL:



Hyphenate's REST API response is based on JSON format.


All Hyphenate REST API requests need to include the Accept and Content-Type headers, and most requests need to include the Authorization header unless otherwise specified.

Please include the HTTP Header values as follows:

Header Name Header Value
Accept application/json
Content-Type application/json
Authorization Bearer ${token}


Unless otherwise specified, all of the Hyphenate API endpoints are authenticated with a session token.

  • You can find parameters org_name, app_name, client_id, and client_secret from the Hyphenate developer console.
    org_name and app_name are part of your API Key separated by #, org_name#app_name.
  • Keep "grant_type": "client_credentials" in the request body.
  • client_id and client_secret can be found in the application details page of the Hyphenate console.
API key

API key

Request Authentication Token

Try it out! Authentication API

Get a token using curl:

curl -X POST --header "Content-Type: application/json" --header "Accept: application/json" -d "{
  \"grant_type\": \"client_credentials\",
  \"client_id\": \"YXA65VqmwJRAEeaQYDm4m8r7zw\",
  \"client_secret\": \"YXA6QVcnW-CSLVu7O8jrRBZX5oodpaA\"
}" "https://api.hyphenate.io/hyphenatedemo/fruitworld/token"

Success response:

key value
access_token The value of the token
expires_in Effective time, in seconds. The default is seven days. The token doesn't need to be obtained again in the period of validity
application The UUID value of the current app

Once you receive a token, you can include it in API calls with the Authorization HTTP header as the following:

Authorization : Bearer ${token}

Token Expiration

Session tokens will expire after a certain period of time, as specified in the expire_in field. However, the time period may vary slightly due to network delay. Request a new token if the token is no longer working or the HTTP response code is 401.

Remember to keep the request frequency as low as possible and only request a new token when required. If the app requests tokens too frequently for the same account, the account may be suspended.

Rate Limits

Each IP address is limited to 30 requests per second. Requests beyond this limit will receive a 429 or 503 error. If you received this error, please reduce the request frequency and try again.

If you would like to increase the limit to make more than 30 requests per second, please contact Hyphenate.


Hyphenate's backend REST API service is based on HTTPS protocol and authentication is based on the OAuth 2.0 standard and RBAC (role-based access control) permissions model.

You must make a request to obtain the token before using the backend service. The token varies according to the request initiator's role and access authority.

Next Section: User Account Management

Updated 2 years ago

REST API Overview

Suggested Edits are limited on API Reference Pages

You can only suggest edits to Markdown body content, but not to the API spec.