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

Chat History

Get Message History

Hyphenate offers two options for message retention duration, 3 months or 6 months, on monthly basis. So instead of default 3 and 7 days of message storage, you can extend the message storage rolling up to 3 or 6 months with a monthly premium plan, which also allows you to expand the time duration of message roaming as the same as your message storage plan. Please contact Hyphenate

This REST API only support getting hourly based message package.

To get real-time messages, please see Webhooks which Hyphenate chat server will push real-time message to your developer server directly.


Parameters Description
time 10 digits format (YYYYMMDDHH) in UTC time. Ex. Pass 2017071907 as query to get messages from 7:00 to 8:00 am on 07/19/2017, including 7:00am

Response body

The API will respond with a URL to download message history files. The link is valid for 30 min.
Please allow some time, a few hours, for message history to be generated before you call the API to get the message history. i.e., You can download message history for 07/19/2017 7:00~8:00 am after 07/19/2017 9:00 am.

Get Files (image, video, audio, binary, etc)

  1. Use the REST API get message history to obtain the list of messages.
  2. Parse the messages to obtain downloading URL.
  3. Download via the downloading URL and store the files to your backend database.

HTTP error codes

HTTP Status Code Description
429 or 503 Request beyond given request rate limit. see Rate Limit
400 - Bad Request Message history expired or an attempt to get message history that is not ready yet
401 - Unauthorized Request requires authentication. Servers may return this response upon the interfaces that need "token".


    "uri" : "https://api.hyphenate.io/hyphenatedemo/fruitworld/chatmessages/2017071814",
    "data" : [ {
    "url" : "https://api.hyphenate.io/history/1D/hyphenatedemo/fruitworld/2017071814.gz?Expires=1481532888&OSSAccessKeyId=LTAIlKPZStPokdA8&Signature=Zzt%2ByJ7tj%2Bgq3zxLVK4QrbFutto%3D"  // return file downloading path

curl example

curl -H "Authorization: Bearer YWMtKE9FxsAVEeaakDV5WXc9dQAAAAAAAAAAAAAAAAAAAAF8W6hAc0gR5oUiCYHCfur3AgMAAAFY8Ox2UgBPGgA6gtMo9E-nU8uaqRLXcs63EZi6Iu0QBpw6vta5E8Ix-g" -X GET "https://api.hyphenate.io/hyphenatedemo/fruitworld/chatmessages/2017071814"

Deprecation Warning

The following API service will be terminated by mid-August. Use the API provided above.


Example: Get messages based on timestamp

Add query parameters, for example:

ql=select * where timestamp>1403164734226
ql=select * where timestamp<1403164734226

  1. If you need to export chat records, you can query the required chat logs with cursor paging. The data returned by the chat query interface has been sorted in ascending order according to the timestamp attribute.
  2. The query will fail if it contains “and” as well as “or” logic.


curl -X GET -i -H "Authorization: Bearer YWMtxc6K0L1aEeKf9LWFzT9xEAAAAT7MNR_9OcNq-GwPsKwj_TruuxZfFSC2eIQ" "https://api.hyphenate.io/hyphenatedemo/fruitworld/chatmessages?ql=select+*+where+timestamp>1403164734226"

Example: Get messages with pagination

limit: batch max number of returning objects.

cursor: obtained from the previous GET messages call if total objects on the database are exceeding the limit of batch number.


curl -X GET -i -H "Authorization: Bearer YWMtxc6K0L1aEeKf9LWFzT9xEAAAAT7MNR_9OcNq-GwPsKwj_TruuxZfFSC2eIQ" "https://api.hyphenate.io/hyphenatedemo/fruitworld/chatmessages?limit=10&cursor=MTYxOTcyOTYyNDpnR2tBQVFNQWdHa0FCZ0ZHczFuSG93Q0FkUUFROW94S0lQZVBFZU9mTEQxQWVMdHEyQUNBZFFBUTlvd2pFUGVQRWVPaHFWa1l0ZjA2dEFB"

Next Section: Contact Management

Chat History

Suggested Edits are limited on API Reference Pages

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