Messages Data API
Back

From WeChat Official Account Admin Platform
Jump to: navigation, search

Through these data APIs, developers can obtain data similar to but more flexible than data provided on the WeChat Official Account Admin Platform web site and then perform additional advanced processing as required.

The Data APIs are only available to developers with a certified official account.

Notes:

1. Official account data provided from the data APIs only includes data after December 1, 2014. Any data provided from  before this date will likely be inaccurate.
2. In order to speed up subsequent user access and reduce API calling time, we suggest developers store data obtained through API calls in their own databases.

Messages data APIs contain API calls used to obtain data on messages sent by followers to the official account from data statistical modules on the WeChat Official Account Admin Platform. The provided APIs are as follows (messages keyword data APIs are not yet available):

API Name Maximum Time Span API Calling URL (https Required)
Obtain user-sent messages profile data (getupstreammsg) 7 https://api.weixin.qq.com/datacube/getupstreammsg?access_token=ACCESS_TOKEN
Obtain user-sent messages data by hour (getupstreammsghour) 1 https://api.weixin.qq.com/datacube/getupstreammsghour?access_token=ACCESS_TOKEN
Obtain user-sent messages data by week (getupstreammsgweek) 30 https://api.weixin.qq.com/datacube/getupstreammsgweek?access_token=ACCESS_TOKEN
Obtain user-sent messages data by month (getupstreammsgmonth) 30 https://api.weixin.qq.com/datacube/getupstreammsgmonth?access_token=ACCESS_TOKEN
Obtain user-sent messages distribution data (getupstreammsgdist) 15 https://api.weixin.qq.com/datacube/getupstreammsgdist?access_token=ACCESS_TOKEN
Obtain user-sent messages distribution data by week (getupstreammsgdistweek) 30 https://api.weixin.qq.com/datacube/getupstreammsgdistweek?access_token=ACCESS_TOKEN
Obtain user-sent messages distribution data by month (getupstreammsgdistmonth) 30 https://api.weixin.qq.com/datacube/getupstreammsgdistmonth?access_token=ACCESS_TOKEN

The maximum time span indicates the maximum time range for obtaining data during one API calling event. For example, if the maximum time span is 7, data from up to 7 days can be obtained once. Please obtain the actual value of access_token through "Obtain access_token".

Please note that the weekly/monthly data is marked with the first day of the week/month (1st of each month or Monday, respectively). The weekly/monthly data can be obtained by calling the corresponding API after that week/month has finished. For example, you can call the API for obtaining monthly data on December 1st with November 1st and November 5th as the begin_date and end_date to obtain the monthly data of November 1st (i.e., monthly data of November).

Request Description

User-sent Messages data APIs (including all APIs in the list) should use the HTTP POST method to send parameters to the corresponding API calling URL. A sample set of parameters is provided below:

{ 
    "begin_date": "2014-12-07", 
    "end_date": "2014-12-08"
}

Calling Parameter Description

Parameter Required Description
access_token Yes Access token providing authorization to the calling API
begin_date Yes Start date for queried data. The difference between begin_date and end_date should be less than the maximum time span (for example, if the maximum time span is 1, begin_date and end_date should be identical); otherwise, an error will be reported.
end_date Yes End date for queried data, yesterday’s date as the maximum possible value

Return Description

An example of a successful JSON response from the getupstreammsg API is provided below:

{ 
   "list": [ 
       { 
           "ref_date": "2014-12-07", 
           "msg_type": 1, 
           "msg_user": 282, 
           "msg_count": 817
       }
	// Below would be data with the same ref_date and different msg_type, or with a different ref_date (within the time range)
   ]
}

An example of a successful JSON response from the getupstreammsghour API is included below:

{ 
   "list": [ 
       { 
           "ref_date": "2014-12-07", 
           "ref_hour": 0, 
           "msg_type": 1, 
           "msg_user": 9, 
           "msg_count": 10
       }
	// Below would be data with the same ref_hour and different msg_type, or with a different ref_hour. As the maximum time span is 1, ref_date is a fixed value.
   ]
}

An example of a successful JSON response from the getupstreammsgweek API is provided below:

{ 
   "list": [ 
       { 
           "ref_date": "2014-12-08", 
           "msg_type": 1, 
           "msg_user": 16, 
           "msg_count": 27
       }
	// Below would be data with the same ref_date and different msg_type, or with a different ref_date
   ]
}

An example of a successful JSON response from the getupstreammsgmonth API is provided below:

{ 
   "list": [ 
       { 
           "ref_date": "2014-11-01", 
           "msg_type": 1, 
           "msg_user": 7989, 
           "msg_count": 42206
       }
	// Below would be data with the same ref_date and different msg_type, or with a different ref_date
   ]
}

An example of a successful JSON response from the getupstreammsgdist API is provided below:

{ 
   "list": [ 
       { 
           "ref_date": "2014-12-07", 
           "count_interval": 1, 
           "msg_user": 246
       }
	// Below would be data with the same ref_date and different count_interval, or with a different ref_date
   ]
}

An example of a successful JSON response from the getupstreammsgdistweek API is provided below:

{ 
   "list": [ 
       { 
           "ref_date": "2014-12-07", 
           "count_interval": 1, 
           "msg_user": 246
       }
	// Below would be data with the same ref_date and different count_interval, or with a different ref_date
   ]
}

An example of a successful JSON response from the getupstreammsgdistmonth API is provided below:

{ 
   "list": [ 
       { 
           "ref_date": "2014-12-07", 
           "count_interval": 1, 
           "msg_user": 246
       }
	// Below would be data with the same ref_date and different count_interval, or with a different ref_date
   ]
}

Return Parameter Description

Parameter Description
ref_date Date of the data, between begin_date and end_date
ref_hour Hour of the data, from 000 to 2300, indicating from [000,100) (first hour of each day) to [2300,2400) (last hour of each day)
msg_type Message type:

1: Text, 2: Image, 3: Audio, 4: Video, 6: Third-party application (i.e. URL)

msg_user Number of followers who sent messages to the official account
msg_count Number of user-sent messages
count_interval Interval for the number of messages user has sent to the official account in the specified day: 0: 0, 1: 1-5, 2: 6-10, 3: more than 10
int_page_read_count Number of views of the article web page
ori_page_read_user Number of followers who viewed the original web page (by clicking "Read more" on the article web page), 0 if there is no the original web page

An error code will be returned upon failure. For details about error codes, please see Return Codes.

Developer Guide
Custom-defined Menu
WeChat JS-SDK