Set up HTTP callbacks
Chat supports HTTP callbacks (webhooks) for synchronization of messages on your own server or moderation of message content. After you set up HTTP callbacks for your Chat app, the Chat server sends notifications in the form of HTTP POST requests to your app server when specified events occur. According to whether the message delivery is intervened, the callbacks are divided in two categories:
- Pre-delivery callbacks: Mainly used for content moderation. When the Chat server receives a message from the client app, it sends a request to your app server and waits for a response that decides if the message delivery is passed or rejected. Pre-delivery callbacks only apply to messages sent from your client apps.
- Post-delivery callbacks: Mainly used for data synchronization. When certain events occur, for example, a user sends out a message or gets offline, the Chat server sends a request to your app server and does not validate the response content. Post-delivery callbacks apply to messages and other events sent from you client and server apps.
Understand the tech
Difference between pre-delivery and post-delivery callbacks
The following table summarizes the differences between the two categories of callbacks.
| Category | Pre-delivery callback | Post-delivery callback |
|---|---|---|
| Supported components | Client SDKs | Client SDKs and REST APIs |
| Supported scopes | Only messages | Messages and other events |
| Response required | Yes | No |
| Typical use case | Content moderation | Chat history synchronization |
Callback security
For pre-delivery and post-delivery callbacks, the Chat server sends HTTP/HTTPS POST requests with JSON payloads to your app server. The requests are encoded in UTF-8 and the message in each request is signed with an MD5 signature. In each request header, the Content-Type field is application/json.
For post-delivery callbacks, the message in requests is signed with an MD5 signature calculated with org.apache.commons.codec.digest.DigestUtils#md5Hex.
You can verify the signature to check whether the callbacks are sent from the Chat server.
-
Retrieve the following information:
-
The callback ID, which is the
callIdparameter in the request body of the callback. -
The secret assigned to the callback rule. You can find it on the callback rule list on the Callback page on the Agora console.
-
The callback timestamp, which is the timestamp parameter in the request body of the callback.
-
-
Calculate the MD5 value of the concatenated string of the callback ID, the secret, and the callback timestamp.
-
Check if the calculated value equals to the secret parameter in the request body. If yes, the callback is sent by Agora Chat.
Prerequisites
To use the HTTP callbacks, you must meet the following requirements:
- You have an Agora project with Chat enabled.
- You understand the API call frequency limit as described in Limitations.
- The HTTP callback feature is not enabled by default. To use this feature, you need to subscribe to the Pro or Enterprise pricing plan and enable it in Agora Console.
You must contact support@agora.io to disable this feature as this operation will delete all the relevant configurations.
Configure callback rules
To receive the HTTP callbacks, you need to configure rules for the pre- or post-delivery callbacks in Agora Console.
-
Log in to Agora Console and find your project on the Project Management page, then click the edit button.
-
Find Chat on the project editing page, and click Configure.
-
Choose Features > Callback and click Add Callback Address on the Callback page.
-
To add a rule for pre-delivery callbacks, fill the following fields under the Pre send tab and then click Save.
- Rule Name: Enter a name for the rule. Under one project, each rule must have a unique name.
- Chat Type: Select the types of chat this rule applies to.
- Message Type: Select the types of messages this rule applies to.
- Timeout: (Optional) Specify the time (in ms) that the Chat server should wait for the HTTP responses. The default value is 200 ms. If the response times out, the Chat server continues with the fallback action.
- Fallback Action: (Optional) Select the action of the Chat server when the HTTP response times out or an error is returned. The default value is Passed.
- Report Error: (Optional) Set whether to notify the message sender when their message is rejected. The default value is No, indicating that the sender is not notified of the message delivery failure.
- Status: Set whether to enable this rule. The default value is Enabled.
- Callback Address: Enter the URL of your app server for receiving the pre-delivery callbacks. Both HTTP and HTTPS URLs are allowed.
-
To add a rule for post-delivery callbacks, fill the following fields under the Post send tab and then click Save.
- Rule Name: Enter a name for the rule. Under one project, each rule must have a unique name.
- Callback Service: Select the types of chat or events this rule applies to.
- Message Status: Select whether this rule applies to chat or offline messages, or both.
- To synchronize the chat history on your own server, select chat messages. All messages sent by the users are chat messages, regardless of the online status of the message receiver.
- To push message notifications, select offline messages. Messages sent to an offline user are counted as offline messages.
- Status: Set whether to enable this rule. The default value is Disabled.
- Callback Address: Enter the URL of your app server for receiving the post-delivery callbacks. Both HTTP and HTTPS URLs are allowed.
The rules take effect immediately.
Note the following for the rule configurations:
- By default, you can add four rules for the pre- and post-delivery callbacks in total. To extend the limit, contact support@agora.io.
- The rule configuration only supports message events. To receive notifications of other events, contact support@agora.io.
Pre-delivery callbacks
The following figure shows how the pre-delivery callbacks work.
As shown in the figure, the workflow of pre-delivery callbacks is as follows:
- The Chat server receives a message from Client A.
- The Chat server sends an HTTP request that contains the information of the message to your app server.
- Your app server processes the received data and sends the processing result in the form of HTTP response to the Chat server.
- The Chat server receives the HTTP response and decides if the message delivery is passed.
- If the message delivery is passed, the Chat server delivers the message to Client B.
The Chat server determines whether to send the message according to the HTTP response received from your app server. If the HTTP status code is 200 in the response, the Chat server handles the message as specified in the matching pre-delivery callback rule. If a response error occurs, including the required field valid being absent or fields being of an incorrect type, the Chat server handles the message as specified by Fallback Action in the matching pre-delivery callback rule and custom internal error is reported on the client (only when Report Error on the Pre Send tab page is set to Yes on the Agora Console).
HTTP request and response
Request header
| Field | Description |
|---|---|
Content-Type | The parameter type. The value is application/json. |
Request body
| Field | Type | Description |
|---|---|---|
callId | String | The callback ID which is the unique identifier assigned to each callback. The callback ID is in the format of {appKey}_{uuid}, where the value of uuid is randomly generated. |
timestamp | Number | The Unix timestamp when the Chat server receives the message, in milliseconds. |
chat_type | String | The chat type:
|
group_id | String | The group or chat room where the message included in the request is to be sent. This parameter is valid only for group and room chats. |
from | String | The user ID of the message sender. |
to | String | The user ID of the message recipient. This parameter is valid only for one-to-one chats. |
msg_id | String | The ID of the message for which the callback request is sent. This ID is the same as the msg_id generated by the Chat server when the message is sent to the recipient. |
payload | JSON | The message content which matches the content of the payload parameter in historical messages retrieved with the REST API. |
securityVersion | String | The security check version which is 1.0.0. |
security | String | The signature used to identify whether the HTTP callback request is from the Chat server. The signature is an MD5 hash in the format of {callId}+{secret}+{timestamp}, where secret is generated by the Chat server to produce the signature and is displayed on the callback rule list on the Callback page on the Agora Console. |
Response body
The HTTP responses cannot exceed 1,000 characters; otherwise, the callbacks fail as the Chat server deems the responses as attack packets.
| Field | Type | Required | Description |
|---|---|---|---|
valid | Boolean | Yes | Controls whether the message is appropriate according to the rules specified on your app server：
|
code | String | No | Custom pre-delivery callback error description on the client. The value of the code field is displayed as the error on the client only when Report Error on the Pre Send tab page is set to Yes on the Agora Console. Callback errors are displayed as follows on the client:
|
payload | Object | No | The modified message content. Currently, only the text content is allowed. The modified content must be in the same format as the original message and cannot exceed 1 KB. If it is unnecessary to modify the message, ignore this field. |
Request example
Response example
Post-delivery callbacks
The workflow of post-delivery callbacks is as follows:
As shown in the figure, the workflow of post-delivery callbacks is as follows:
- The Chat server receives a message or other event from a client or server.
- The Chat server sends an HTTP request that contains the information of the message or event to your app server.
- Your app server sends an HTTP response to the Chat server to indicate that the callback is received.
For post-delivery callback request examples, see event callbacks.
The Chat server places full trust in callback responses received from your app server without verifying them. As long as the returned HTTP status code is 200, the Chat server regards that the callback succeeds.
Responses to the requests cannot exceed 1,000 characters; otherwise, the callbacks fail as the Chat server deems the responses as attack packets.
Retry logic
For post-delivery callbacks, the Chat server records a notification failure and tries resending the callback once again. If the second attempt fails, the Chat server stops trying.
If 90 notification failures occur in 30 seconds, the callback rules involving the app server will be temporarily disabled for 5 minutes.
Status codes
For details, see HTTP Status Codes.
FAQ
Q: Why is the message delivered to the intended recipient even though the value of the valid field is false in the pre-delivery callback response?
A: Maybe your server fails to return the pre-delivery callback response within the period specified with the Timeout parameter in the pre-delivery callback rule on the Pre Send page on the Agora Console. In this case, the message is delivered if Fallback Action on the Pre Send page page is set to Passed. To avoid this issue, you are advised to increase the value of the Timeout parameter (200 milliseconds by default), for example, to 1000 milliseconds.