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

What is a Webhook?

A webhook is an event callback, which allows you to receive or monitor specific events by pushing real time data to your server from the Hyphenate IM backend via HTTP requests.

If you don't need real time messages pushed to your backend server via Webhooks, you can use REST APIs to get chat history via Chat History.

Use Cases

  • Subscribe to users' chat history or undelivered offline messages in real time
  • Real time language translation
  • Chatbot integration

Event Types by Hyphenate

Event Description
chat Get messages sent by users
chat_offline Get undelivered messages queued in the Hyphenate server if the receiving users are offline

Enable Webhooks

Enable Webhook Service

Webhooks is an add-on service, please contact Hyphenate to enable the service [email protected]

To enable the Webhooks service, please send us the following prerequisites in order for us to send HTTP requests with relevant data to your server.

  • Hyphenate API key: Full API key you created from the Hyphenate console, {org_name}#{app_name}.
  • Webhook URL: The URL (i.e. https://example.com/hyphenate/webhook) that you want to receive Webhooks events at.
  • Secret key: A self-defined key used to authenticate requests between Hyphenate and your server. If you do not provide a key, Hyphenate will generate a pair of keys for outgoing and incoming connections. Authentication is required in order to receive the callback events.

Respond to Event Callbacks

  1. Process the HTTP POST from Hyphenate.
  2. Hyphenate determines the success/failure based on the status code that you respond with. If the Webhooks callback event is valid, return HTTP 200 OK code. Responding with any other code may cause the Hyphenate platform to trigger the connection timeout error.

Response Format

    "callId" : "",       // Same as the callId from Hyphenate messages
    "accept" : "true",   // acknowledgement of receiving.
    "reason" : "",       // (Optional) only needed if "accept" field is set to false
    "security" : ""      // signature, the format is: md5(callId+Security Key+"true"), default Security Key generated by Hyphenate

Best Practices

  • Webhooks may be disabled if exceed 90 errors within 30 seconds.
  • Full response (header + body) should NOT exceed 1000 characters.
  • There is no specific time limit on your response, but the best practice is to respond immediately.
  • To ensure valid security, always confirm the signature of the callback event for key security in response.
  • Please make webhook handler idempotent, because it is possible (though unusual) that the same callback event could be sent multiple times. In other words, your backend must be able to handle the same event multiple times without affecting the outcome. One way to handle this potential issue is by tracking the IDs of callback events and ignoring duplicate events.

Webhooks Parameters

Callback Receiving & Error Handling

Messages will be discarded and the Webhooks service may be disabled if one of the conditions above is not satisfied. Make sure the receiving server always has enough capacity to receive the callback and handle the error code 504 correctly.

  • Support HTTP POST with JSON payload in UTF-8.
  • Both the payload and the response from the target server will be signed by MD5. Hyphenate uses org.apache.commons.codec.digest.DigestUtils#md5Hex for the MD5 signing.

Callback data of the Webhook

Parameter Type Description
eventType string Event Type
callId string Event ID
timestamp long Timestamp of event
from string Sender's ID
to string Receiver's ID
msg_id string Message ID
group_id string Only available message of group chat
securityVersion string Security version, currently v1.0.0
security string Signature, the format is: md5(callId+Security Key+timestamp), Default security key generated by Hyphenate
payload Message content. Please refer to the payload data format below

Payload Data Format

For details, refer to Post messages.

     "bodies": [                     // message bodies
         "msg": "hhhhhh",            // message content
         "type": "txt"               // content type, txt: text message, img: picture, loc: location message, audio: audio clip, video: video clip.
         "length": 3,                // clip length, in seconds, only available for audio or video messages
         "url": "",                  // url for media files, i.e. picture, audio clips
         "filename": "22.png",       // file name for pictures, audio clips, etc.
         "secret": "pCY80PdfEeO4Jh9URCOfMQWU9QYsJytynu4n-yhtvAhmt1g9",    //secret to get files, i.e. picture, audio clips
         "lat": 39.983805,           // latitude, only for location message
         "lng": 116.307417,          // longitude, only for location message
         "addr": "San Francisco, CA" // address, only for location message
     "ext": {                        // customized extension
         "key1": "value1",           // key and values

Next Section: HTTP Error Codes

Updated 2 years ago


Suggested Edits are limited on API Reference Pages

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