# Introduction to Messaging and Event Push

When a Service Account user sends a message, or something happens, the WeChat platform needs to actively push the message to the developer's server so that the developer can automate some action.

# Configuration instructions

For more detailed message encryption and decryption instructions and debugging tool guidelines, see Message Encryption and Decryption Instructions

For more information on how to accept both regular messages and event pushes, see to receive regular messages and to accept event pushes

In addition to accepting messages, developers can use [to passively reply to the user who sent the message, or to send the customer service message interface, or to actively send the message

# Step 1: Fill in the server configuration

You can configure it at WeChat Developer Platform - My Business - Service Account - Messaging and Event Pushing."That is, fill in the address (URL), Token and EncodingAESKey, where the URL is the interface URL that the developer uses to receive WeChat messages and events.A token can be filled in by the developer and used as a generated signature (the token is compared to the token contained in the interface URL to verify security). EncodingAESKey is manually filled in or randomly generated by the developer and will be used as a message body encryption and decryption key.

Specific configuration instructions are as follows:

  • URL server address: The interface URL used by developers to receive WeChat messages and events must begin with http:// or https:// and support ports 80 and 443 respectively.
  • Token: Used for signature processing, which is described below.
  • EncodingAESKey: Will be used as the message body encryption and decryption key.
  • How to decrypt a message:
    • Text mode: No message decryption is used, text is sent, the security is low, and it is not recommended.
    • Compatibility mode: plain text, cipher text coexist, not recommended.
    • Security Mode: Use message decryption, plain ciphertext, high security coefficient, highly recommended.
  • Data format: The format of the message body, with support for XML only

Developers can choose a message decryption method: plaintext mode, compatibility mode, and security mode.

The selection of schemas and server configurations takes effect immediately after submission, so developers are encouraged to fill in and select with caution.

The default state of the decryption method is plaintext mode. The choice of compatibility mode and security mode requires that the relevant decryption code be configured in advance. More detailed message decryption instructions and guidance for debugging tools can be found in message decrypting instructions

# Step 2: Verify that the message is indeed from the WeChat server

After the developer submits the information, the WeChat server sends a GET request to the completed server address URL. The GET request carries parameters as shown in the table below:

parameter describe
signature WeChat cryptographic signature, the signature combines the token parameter filled by the developer and the timestamp parameter and nonce parameter in the request.
timestamp timestamp
nonce random number
echostr Random character string

The developer verifies the request by verifying the signature (see below).If you confirm the GET request from the WeChat server, please return the echostr parameter as it is, then access is effective, become a developer success, otherwise access failure.The encryption / verification process is as follows:

  1. Lexicographic sorting of token, timestamp, nonce
  2. Concatenate three argument character strings into a string for sha1 encryption
  3. The developer gets an encrypted character string that can be compared to signature, identifying the request as coming from WeChat.

PHP sample code to verify a signature:

private function checkSignature()
{
    $signature = $_GET["signature"];
    $timestamp = $_GET["timestamp"];
    $nonce = $_GET["nonce"];
	
    $token = TOKEN;
    $tmpArr = array($token, $timestamp, $nonce);
    sort($tmpArr, SORT_STRING);
    $tmpStr = implode( $tmpArr );
    $tmpStr = sha1( $tmpStr );
    
    if( $tmpStr == $signature ){
        return true;
    }else{
        return false;
    }
}

PHP sample code download: Download

To facilitate debugging by developers, we provide URL validation tool for developers to use.

Developers need to fill in AccessToken , URLAddress, Token, and click "Check parameters and initiate validation," the debugging tool will send a GET request to the server referred to by the URL and return relevant debugging information.

# Step 3: Implement business logic based on interface documentation

Access takes effect after successful validation of URL.Developers can apply for WeChat certification in the public platform website, and after the certification is successful, they will get more interface permissions to meet more business needs.

After successful access, each time the user sends a message to Service Account, or generates a custom menu,Or when a WeChat payment order is generated, the server configuration filled out by the developer will receive messages and events pushed by the WeChat server, and the developer can respond according to its business logic, such as replying to a message.

When a user sends a message to Service Account, the message sender received by the service provider is an OpenID, the result of encryption using the user's WeChat number, and each user has a unique OpenID for each service provider.

Developers can use [to invoke the WeChat API to implement their business.

# Note

When enabled, messages sent by the user are forwarded to that address, and automatic responses and custom menus set up in the site are disabled.