发送小程序

发送小程序卡片。

请求参数

参数	必填	类型	说明
appid	是	string	实例 appid，标识操作哪个已登录账号。示例：we_xxxxxxxxxxxxxxx
conversationId	是	int64	会话 id：单聊传对方 userId，群聊传 roomId，给自己发传当前账号 uin；必须是 JSON number。示例：7881301709020163
content	是	object	消息内容，子字段见下。示例：{"title":"示例小程序","miniProgramDetails":{"username":"gh_f9d…

content 字段

字段	类型	说明
content.title	string	标题
content.miniProgramDetails	object	小程序详情（内含 appId/path/封面等）
content.miniProgramDetails.username	string	小程序信息
content.miniProgramDetails.appId	string	小程序信息
content.miniProgramDetails.path	string	小程序信息
content.miniProgramDetails.coverUrl	string	封面图 url
content.miniProgramDetails.title	string	小程序信息
content.miniProgramDetails.appName	string	小程序信息
content.miniProgramDetails.fallbackUrl	string	小程序信息
content.miniProgramDetails.coverFileId	string	封面图需先 /api/cdn/uploadImage
content.miniProgramDetails.coverMd5	string	封面图需先 /api/cdn/uploadImage
content.miniProgramDetails.coverAesKey	string	封面图需先 /api/cdn/uploadImage
content.miniProgramDetails.coverSize	int64	封面图需先 /api/cdn/uploadImage
content.miniProgramDetails.coverWidth	int64	封面图需先 /api/cdn/uploadImage
content.miniProgramDetails.coverHeight	int64	封面图需先 /api/cdn/uploadImage

请求示例

HTTP

POST {BASE_URL}/wx-api/api/message/sendMiniProgram
Authorization: Bearer <你的 App Token>
Content-Type: application/json

{
  "appid": "we_xxxxxxxxxxxxxxx",
  "conversationId": 7881301709020163,
  "content": {
    "title": "示例小程序",
    "miniProgramDetails": {
      "username": "gh_f9d9fca26a50@app",
      "appId": "<小程序 appId>",
      "path": "pages/tabBar/index/index.html",
      "coverUrl": "http://mmbiz.qpic.cn/.../640",
      "title": "示例小程序",
      "appName": "示例小程序",
      "fallbackUrl": "https://mp.weixin.qq.com/mp/waerrpage?appid=<小程序 appId>&type=upgrade&upgradetype=3#wechat_redirect",
      "coverFileId": "<uploadImage 返回 id>",
      "coverMd5": "961aa29ebd964455b22ecfaa691924d7",
      "coverAesKey": "caf54890e1a4f45b072e64db3d265fe7",
      "coverSize": 57102,
      "coverWidth": 500,
      "coverHeight": 400
    }
  }
}

curl

curl -X POST '{BASE_URL}/wx-api/api/message/sendMiniProgram' \
  -H 'Authorization: Bearer <你的 App Token>' \
  -H 'Content-Type: application/json' \
  --data-raw '{
  "appid": "we_xxxxxxxxxxxxxxx",
  "conversationId": 7881301709020163,
  "content": {
    "title": "示例小程序",
    "miniProgramDetails": {
      "username": "gh_f9d9fca26a50@app",
      "appId": "<小程序 appId>",
      "path": "pages/tabBar/index/index.html",
      "coverUrl": "http://mmbiz.qpic.cn/.../640",
      "title": "示例小程序",
      "appName": "示例小程序",
      "fallbackUrl": "https://mp.weixin.qq.com/mp/waerrpage?appid=<小程序 appId>&type=upgrade&upgradetype=3#wechat_redirect",
      "coverFileId": "<uploadImage 返回 id>",
      "coverMd5": "961aa29ebd964455b22ecfaa691924d7",
      "coverAesKey": "caf54890e1a4f45b072e64db3d265fe7",
      "coverSize": 57102,
      "coverWidth": 500,
      "coverHeight": 400
    }
  }
}'

Python

import requests

url = "{BASE_URL}/wx-api/api/message/sendMiniProgram"
headers = {"Authorization": "Bearer <你的 App Token>", "Content-Type": "application/json"}
body = """{
  "appid": "we_xxxxxxxxxxxxxxx",
  "conversationId": 7881301709020163,
  "content": {
    "title": "示例小程序",
    "miniProgramDetails": {
      "username": "gh_f9d9fca26a50@app",
      "appId": "<小程序 appId>",
      "path": "pages/tabBar/index/index.html",
      "coverUrl": "http://mmbiz.qpic.cn/.../640",
      "title": "示例小程序",
      "appName": "示例小程序",
      "fallbackUrl": "https://mp.weixin.qq.com/mp/waerrpage?appid=<小程序 appId>&type=upgrade&upgradetype=3#wechat_redirect",
      "coverFileId": "<uploadImage 返回 id>",
      "coverMd5": "961aa29ebd964455b22ecfaa691924d7",
      "coverAesKey": "caf54890e1a4f45b072e64db3d265fe7",
      "coverSize": 57102,
      "coverWidth": 500,
      "coverHeight": 400
    }
  }
}"""

resp = requests.post(url, headers=headers, data=body.encode("utf-8"))
print(resp.text)

Java

import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;

String url = "{BASE_URL}/wx-api/api/message/sendMiniProgram";
String body = "{\n" +
    "  \"appid\": \"we_xxxxxxxxxxxxxxx\",\n" +
    "  \"conversationId\": 7881301709020163,\n" +
    "  \"content\": {\n" +
    "    \"title\": \"示例小程序\",\n" +
    "    \"miniProgramDetails\": {\n" +
    "      \"username\": \"gh_f9d9fca26a50@app\",\n" +
    "      \"appId\": \"<小程序 appId>\",\n" +
    "      \"path\": \"pages/tabBar/index/index.html\",\n" +
    "      \"coverUrl\": \"http://mmbiz.qpic.cn/.../640\",\n" +
    "      \"title\": \"示例小程序\",\n" +
    "      \"appName\": \"示例小程序\",\n" +
    "      \"fallbackUrl\": \"https://mp.weixin.qq.com/mp/waerrpage?appid=<小程序 appId>&type=upgrade&upgradetype=3#wechat_redirect\",\n" +
    "      \"coverFileId\": \"<uploadImage 返回 id>\",\n" +
    "      \"coverMd5\": \"961aa29ebd964455b22ecfaa691924d7\",\n" +
    "      \"coverAesKey\": \"caf54890e1a4f45b072e64db3d265fe7\",\n" +
    "      \"coverSize\": 57102,\n" +
    "      \"coverWidth\": 500,\n" +
    "      \"coverHeight\": 400\n" +
    "    }\n" +
    "  }\n" +
    "}";

HttpClient client = HttpClient.newHttpClient();
HttpRequest request = HttpRequest.newBuilder(URI.create(url))
    .header("Authorization", "Bearer <你的 App Token>")
    .header("Content-Type", "application/json")
    .POST(HttpRequest.BodyPublishers.ofString(body))
    .build();
HttpResponse<String> response = client.send(request, HttpResponse.BodyHandlers.ofString());
System.out.println(response.body());

PHP

<?php

$url = '{BASE_URL}/wx-api/api/message/sendMiniProgram';
$body = <<<'JSON'
{
  "appid": "we_xxxxxxxxxxxxxxx",
  "conversationId": 7881301709020163,
  "content": {
    "title": "示例小程序",
    "miniProgramDetails": {
      "username": "gh_f9d9fca26a50@app",
      "appId": "<小程序 appId>",
      "path": "pages/tabBar/index/index.html",
      "coverUrl": "http://mmbiz.qpic.cn/.../640",
      "title": "示例小程序",
      "appName": "示例小程序",
      "fallbackUrl": "https://mp.weixin.qq.com/mp/waerrpage?appid=<小程序 appId>&type=upgrade&upgradetype=3#wechat_redirect",
      "coverFileId": "<uploadImage 返回 id>",
      "coverMd5": "961aa29ebd964455b22ecfaa691924d7",
      "coverAesKey": "caf54890e1a4f45b072e64db3d265fe7",
      "coverSize": 57102,
      "coverWidth": 500,
      "coverHeight": 400
    }
  }
}
JSON;

$ch = curl_init($url);
curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_POSTFIELDS, $body);
curl_setopt($ch, CURLOPT_HTTPHEADER, [
    'Authorization: Bearer <你的 App Token>',
    'Content-Type: application/json',
]);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
$response = curl_exec($ch);
curl_close($ch);
echo $response;

响应示例

响应结构与发送文本消息相同

成功时 data 就是刚发出的完整消息，字段见发送文本消息的响应示例。data.content 回显你发送的内容或上传字段，形状随消息类型不同，见消息模块总览的码表。

响应字段

字段	类型	说明
code	int64	统一封套状态码：0=成功，负数=失败
detail	string	附加明细，通常为空
message	string	文案：成功为 ok；失败形如 -码|描述
time	string	服务端处理时间 YYYY-MM-DD HH:MM:SS

常见错误

下表为企微错误码。业务失败时顶层 code=-1，具体错误码在 message 的 | 前，例如 -3004|参数错误；鉴权与网关错误见错误码。

错误码	含义	怎么办
-4046	sendMiniProgram 误填 cover 字段	cover 留空
-4014	过期或错误的 uin 作 conversationId	先 personal/getInfo 取当前 uin
-3020	用自聊伪房间 roomId 作发送目标	给自己发用当前账号 uin
-3004	参数错误	检查字段名与类型，数字 id 不能传字符串

下一步

• 消息模块总览
• 错误码
• 快速开始