Third-Party Callback Overview

Overview

To give you refined control over app features, IM provides you with powerful callbacks free of charge. The callbacks use persistent connection mode by default. A callback means that the IM backend sends a request to the app backend server before or after an event occurs. This allows the app backend to synchronize data if necessary or intervene in the subsequent event processing. For more information about the callbacks currently supported by IM, see the Callback Command List.

A third-party callback is sent to the app backend server using an HTTP/HTTPS request, and the app backend server must process the IM callback request and provide a response as soon as possible. Take the callback before delivering a group message as an example. Before the message is sent, the IM backend sends a callback request to the app backend server and determines whether the message should be sent based on the callback result. Based on the callback, the app can synchronize the message or perform content filtering on the message to be sent. The following figure shows the callback process.

Callback Classification

Callbacks can be classified into four types according to their functions:

• Online status callbacks
• Profile and relationship chain callbacks
• One-to-one message callbacks
• Group system callbacks

Callbacks can be classified into two types by process:

• Callback before an event occurs: the purpose of this type of callback is to allow the app backend to intervene in the processing logic of the event. IM will determine the subsequent processing flow based on the return code of the callback. For example, the callback before a group message is sent is this type of callback.
• Callback after an event occurs: the purpose of this type of callback is to allow the app backend to implement essential data synchronization. IM ignores the return codes of such callbacks. For example, the callback after a member quits a group is this type of callback.

Callback Protocol

Third-party callbacks are based on HTTP/HTTPS protocols. The app backend must provide a callback URL to IM, and IM uses a POST request to initiate a callback request to the app backend. When initiating a callback request, IM adds the following parameters at the end of the URL provided by the app backend:

The specific callback content is included in the HTTP request packet. For details, see the following callback examples.

Callback Examples

Callback request example:

POST /?SdkAppid=888888&CallbackCommand=Group.CallbackAfterNewMemberJoin&contenttype=json&ClientIP=$ClientIP&OptPlatform=$OptPlatform HTTP/1.1
Host: www.example.com
Content-Length: 337
{
    "CallbackCommand": "Group.CallbackAfterNewMemberJoin", 
    "GroupId": "@TGS#2J4SZEAEL", 
    "Type": "Public", 
    "JoinType": "Apply", 
    "Operator_Account": "leckie", 
    "NewMemberList": [
        {
            "Member_Account": "jared"
        }, 
        {
            "Member_Account": "tommy"
        }
    ]
}

Callback response example:

HTTP/1.1 200 OK
Server: nginx/1.7.10
Date: Fri, 09 Oct 2015 02:59:55 GMT
Content-Length: 75
{
    "ActionStatus": "OK", 
    "ErrorInfo": "", 
    "ErrorCode": 0
}

Callback Timeout Period

The timeout period for IM callbacks to the app backend is 2 seconds, after which the callback is not retried. If the callback times out, the subsequent processing logic is the same as if the callback was not configured. For example, if the callback before a group message is sent times out, the message is sent normally.

To ensure a high callback success rate, third-party apps need to process callbacks quickly. For example, the app can send a callback response and then process the specific business logic.

Security Considerations

IM supports three types of callbacks:

1. HTTP callback
2. HTTPS callback. The WebServer of the app backend is configured with a certificate issued by a CA or a certificate issued by IM free of charge.
3. HTTPS mutual authentication callback. The WebServer of the app backend is configured with a certificate issued by a CA or a certificate issued by IM free of charge, and mutual authentication is enabled.

To obtain a free certificate issued by IM, you need to submit a ticket using the ticket template for HTTPS certificate issuance in order to provide IM with the domain name of the developer backend.

The first type of callback has the lowest security level, and the last type has the highest security level.

1. HTTP callbacks have two defects. One is that data transmitted in plain text is prone to interception, and the second is that a third-party app cannot determine whether the callback request really comes from IM.
2. For an HTTPS callback, if mutual authentication is disabled, the data encryption issue can be resolved, but the app still cannot ensure that the callback request comes from IM.
3. Only the combination of HTTPS callback and mutual authentication can ensure the security of third-party callbacks.

We strongly recommend that apps use the third type of callback. In addition, the certificate issued by IM is completely free of charge.

Callback Configuration

Currently, the IM console allows you to configure callbacks, including configuring the callback URL and the types of callback enabled. For details on the configuration methods, see Configuration of Third-Party Callbacks.

The IM console allows you to configure only HTTP and HTTPS callbacks. If you need to enable the HTTPS mutual authentication callback, which has the highest security level, perform the following steps:

1. On the IM console, configure the callback URL (which must be an HTTPS domain name) and enable the callback.
2. Submit a requirement ticket to IM. IM will issue the certificate required for mutual authentication to the app. The following information must be specified in the ticket:
   1. SDKAppID
   2. App name
   3. Callback URL, which must be consistent with that in the self-service configuration on the console
3. After receiving the certificate, configure HTTPS mutual authentication based on the two guides below:
   1. Configuring HTTPS Mutual Authentication on an Apache Server
   2. Configuring HTTPS Mutual Authentication on an Nginx Server

Common Reasons for Callback Failures

If a callback failure occurs, check whether the configured callback service has a problem according to the following checklist: