# Extension Message Management Interface

# I. reaching out to promoters

The merchant can call the interface to directly send template messages to bound promoters for timely incentive reminders and business-related notifications.

# 1. Group message

# Interface Dxplaination

This interface is only suitable for group messaging to a bound promoter (single sender = = 50). Use the single message capability when the group size is less than 50. Note: After sending a mass message, you can use the "Section II" interface to check the delivery result, and the "Section III" interface to check the click effect of the message.

# Request address

POST https://api.weixin.qq.com/promoter/sendmsg?access_token=ACCESS_TOKEN

# Request parameters

parameter type Is it compulsory? Introductions
msg_type uint3 yes Message Types, Enumeration Values Reference Weixin Mini Program Message Template Summary
content string yes The message content is a json - formatted character string, and examples of strings of different types are shown in the template list
appid string no Message body jump AppID (need to call the interface appid in the same OPEN account), do not fill in the default interface appid
path string yes Message body jump path, ensure that the path is correct, otherwise the report page does not exist
list_type uint32 no 1: Send it to all promoters under the entered role_id, 2: Send it to ALL promoters under entered retail_id, 3: Send it to the promoters corresponding to the entered id, 0 or no, send it to all the promoters. Please ensure the correctness of the parameters entered. Incorrect parameters will not be sent
role_id uint32数组 no List_type is required for 1, the value can refer to the results returned by the query promoter API
retail_id String array no List_type is required for 2 hours, and the value can refer to the results returned by the query extension api
id String array no List_type is required for 3 hours, and the value can refer to the results returned by the query extension api

# Example Requests

// List_type does not pass
{
  "msg_type" : 1,
  "content" : "{\"title\":\"今日优惠活动\",\"topic\":\"双十一大促\",\"desc\":\"三件五折,两件七折\",\"date\":\"2022/10/28\"}",
  "appid" : "xxxxx",
  "path" : "pages/index/xxxxx"
}

// List_type is 1
{
  "msg_type" : 1,
  "content" : "{\"title\":\"今日优惠活动\",\"topic\":\"双十一大促\",\"desc\":\"三件五折,两件七折\",\"date\":\"2022/10/28\"}",
  "appid" : "xxxxx",
  "path" : "pages/index/xxxxx",
  "list_type" : 1,
  "role_id" : [ 1, 2 ]
}

// List_type is 2
{
  "msg_type" : 1,
  "content" : "{\"title\":\"今日优惠活动\",\"topic\":\"双十一大促\",\"desc\":\"三件五折,两件七折\",\"date\":\"2022/10/28\"}",
  "appid" : "xxxxx",
  "path" : "pages/index/xxxxx",
  "list_type" : 2,
  "retail_id" : [ "xxxxx", "xxxxx" ]
}

// List_type is 3
{
  "msg_type" : 1,
  "content" : "{\"title\":\"今日优惠活动\",\"topic\":\"双十一大促\",\"desc\":\"三件五折,两件七折\",\"date\":\"2022/10/28\"}",
  "appid" : "xxxxx",
  "path" : "pages/index/xxxxx",
  "list_type" : 3,
  "id" : [ "1", "2" ]
}

# Return value

attribute type Introductions
errcode int32 Error code
errmsg string Error message
msg_id string Message id

# Return data example

{
  "msg_id": "123456",
  "errcode": 0,
  "errmsg": "OK"
}

Note: Message parameter type restriction

  • First: less than 10 characters (numbers / letters / symbols / Chinese characters), only one line feed
  • Thing: 20 characters (numbers / letters / symbols / Chinese characters)
  • Time: 24-hour time format (support + year, month, day), support time period, connect between two time points with "~" symbol
  • Amount: a currency sign + 10 digits, mixed decimal and "yuan" at the end
  • number: numbers within 32 bits

# 2. Send a single message

This interface is suitable for sending messages to a single bound promoter and returning the delivery results in real time after sending them. Note: When sending a single message, there is no need to use the "Section 2" interface to check the delivery result;It is not possible to query the click data of a single message through the "Section 3" interface; only the overall click data at the message type dimension (dimension=1) can be obtained.

# Request address

POST https://api.weixin.qq.com/promoter/singlesendmsg?access_token=ACCESS_TOKEN

# Request parameters

parameter type Is it compulsory? Introductions
msg_type uint3 yes Message Types, Enumeration Values Reference Weixin Mini Program Message Template Summary
content string yes The message content is a json - formatted character string, and examples of strings of different types are shown in the template list
appid string no Message body jump AppID (need to call the interface appid in the same OPEN account), do not fill in the default interface appid
path string yes Message body jump path, ensure that the path is correct, otherwise the report page does not exist
openid string no Promoter openid or unionid

# Example Requests

{
  "msg_type" : 1,
  "content" : "{\"title\":\"今日优惠活动\",\"topic\":\"双十一大促\",\"desc\":\"三件五折,两件七折\",\"date\":\"2022/10/28\"}",
  "appid" : "xxxxx",
  "path" : "pages/index/xxxxx",
  "id" : "1"
}
或
{
  "msg_type" : 1,
  "content" : "{\"title\":\"今日优惠活动\",\"topic\":\"双十一大促\",\"desc\":\"三件五折,两件七折\",\"date\":\"2022/10/28\"}",
  "appid" : "xxxxx",
  "path" : "pages/index/xxxxx",
  "openid" : "xxxxxxxxxxxx"
}

# Return value

attribute type Introductions
errcode int32 Error code
errmsg string Error message

# Return data example

{
  "errcode": 0,
  "errmsg": "OK"
}

# II. Enquiry Delivery Results

# Interface Dxplaination

After a merchant sends a message to a group of promoters (the number of promoters sent = > 50), it can query the delivery of the message through the interface to optimize the delivery rate of the message. Note 1: Since the message is sent asynchronously, it is recommended to wait a few minutes after sending the message (the value of the percent field is 100) before adjusting the interface query. Note 2: A query for message delivery results is valid for 7 days and needs to be queried within 7 days after the message is sent.

# Request address

POST https://api.weixin.qq.com/promoter/getmsg?access_token=ACCESS_TOKEN

# Request parameters

parameter type Is it compulsory? Introductions
msg_id string yes Message id, the value returned by the send template message interface

# Example Requests

{
  "msg_type" : 1
}

# Return value

attribute type Introductions
send_cnt uint32 Total number sent
percent uint32 Proportion of currently sent
fail_cnt uint32 Total number of failures, updated after all sent, send progress reference percent
fail_info array Contains the unique ID and failure error code, the number of failures more than one thousand will generate a file, will not return the details
fail_info_url string Fail_info file url
msg_type uint32 Message Types, Enumeration Values Reference Weixin Mini Program Message Template Summary
content string The message content is a json - formatted character string, and examples of strings of different types are shown in the template list
appid string Message body jump AppID, do not fill in the default to the call-up interface appid
path string Message body jump path
list_type uint32 Distribution types (0: full volume distribution, 1: role_id distribution, 2: retail_id distribution, 3: promotion_id distribution)
role_id uint32数组 List_type has a value of 1
retail_id String array List_type has a value of 2
id String array List_type has a value of 3
errcode int32 Error code
errmsg string Error message

# Return data example

{
  "send_cnt" : 2,
  "fail_cnt" : 1,
  "fail_info" : [
    {
      "id" : "123",
      "errcode" : 103010
    }
  ],
  "fail_info_url" : "https://xxxxxxxxxx",
  "msg_type" : 1,
  "content" : "{\"title\":\"今日优惠活动\",\"topic\":\"双十一大促\",\"desc\":\"三件五折,两件七折\",\"date\":\"2022/10/28\"}",
  "appid" : "xxxxx",
  "path" : "pages/index/xxxxx",
  "list_type" : 1,
  "role_id" : [ 1, 2 ],
  "errcode": 0,
  "errmsg": "OK"
}

# III. Analysis of click effect

# Interface Dxplaination

After the merchant confirms that the message has been delivered to the user, the next day you can check the clicking status of the message through this interface. Note 1: This interface only supports querying message data in the dimensions of grouped messages (single group size > = 50) and message type; Note 2: Message click data only scrolls for 7 days, i.e. after the message is sent, the message click data will remain the same; The message is stored for 3 months, i.e. 90 days after the message was sent, and the click data of the message cannot be found through this interface.

# Request address

POST https://api.weixin.qq.com/promoter/getmsgclickdata?access_token=ACCESS_TOKEN

# Request parameters

parameter type Is it compulsory? Introductions
send_date string yes Message sent date, formatted as yyyy-MM-dd
dimonsion uint32 yes Message click number statistics dimension, 0: by message id statistics (group less than 50 no data), 1: by message type statistics
msg_type uint3 yes Message Types, Enumeration Values Reference Weixin Mini Program Message Template Summary
msg_id string no Message id, the value returned by the sending template message interface (effective when dimonsion is 0)
begin_send_time uint32 no Message sending start timestamp, must belong to the natural day on which send_date (effective when dimonsion is 0)
end_send_time uint32 no Message sent end timestamp, must belong to send_date natural day (dimonsion is effective at 0)

# Example Requests

{
  "send_date" : "2023-08-04",
  "dimonsion" : 0,
  "msg_type" : 1,
  "begin_send_time" : 1691114400,
  "end_send_time" : 1691128800
}
或
{
  "send_date" : "2023-08-04",
  "dimonsion" : 1,
  "msg_type" : 1
}

# Return value

attribute type Introductions
click_uv uint32 Number of message clicks
click_pv uint32 Number of message clicks
msg_type uint32 Message Types, Enumeration Values Reference Weixin Mini Program Message Template Summary
msg_id string Message id, the value returned by the send template message interface
send_time uint32 Message Sent Time
errcode int32 Error code
errmsg string Error message

# Return data example

dimonsion为0时返回:
{
  "data_list" : [
    {
      "msg_id" : "123456",
      "send_time" : 1691114400,
      "click_uv" : 123,
      "click_pv" : 200
    }
  ],
  "errcode": 0,
  "errmsg": "OK"
}

dimonsion为1时返回:
{
  "data_list" : [
    {
      "msg_type" : 1,
      "click_uv" : 123,
      "click_pv" : 200
    }
  ],
  "errcode": 0,
  "errmsg": "OK"
}