发送文件

通过文件 URL 向好友或群聊发送文件消息。平台会先下载文件资源，再转发到微信。

接口地址： POST /sendFile

媒体素材复用

在接收人已获得必要告知并同意的场景中，可先获取素材 XML，再使用转发接口减少重复上传。详见 已授权场景的媒体素材复用。

前置条件

• 微信账号已登录，并已获得可用的 wId。
• path 必须是公网可访问的文件 URL。
• fileName 建议包含正确扩展名，便于微信端展示。

请求参数

参数名	必选	类型	说明
wId	是	string	登录实例标识
wcId	是	string	接收方微信 ID 或群 ID（如 24187765053@chatroom）
path	是	string	文件 URL
fileName	是	string	文件名

响应参数

参数名	类型	说明
code	string	1000 成功；其他值都是失败，通常是 1001
message	string	反馈信息
data.type	int	消息类型
data.msgId	long	消息 ID
data.newMsgId	long	新消息 ID
data.createTime	long	发送时间戳（秒）
data.wcId	string	接收方 ID

请求示例

HTTP

POST {BASE_URL}/sendFile
Authorization: Bearer <你的调用凭证>
Content-Type: application/json

{
  "wId": "0000016f-a805-4715-0001-848f9a297a40",
  "wcId": "jack_623555049",
  "path": "https://xc-1300726975.cos.ap-shanghai.myqcloud.com/%E4%B8%8B%E8%BD%BD%E6%96%87%E4%BB%B6.txt",
  "fileName": "文件.txt"
}

curl

curl -X POST '{BASE_URL}/sendFile' \
  -H 'Authorization: Bearer <你的调用凭证>' \
  -H 'Content-Type: application/json' \
  --data-raw '{
  "wId": "0000016f-a805-4715-0001-848f9a297a40",
  "wcId": "jack_623555049",
  "path": "https://xc-1300726975.cos.ap-shanghai.myqcloud.com/%E4%B8%8B%E8%BD%BD%E6%96%87%E4%BB%B6.txt",
  "fileName": "文件.txt"
}'

Python

import requests

url = "{BASE_URL}/sendFile"
headers = {"Authorization": "Bearer <你的调用凭证>", "Content-Type": "application/json"}
body = """{
  "wId": "0000016f-a805-4715-0001-848f9a297a40",
  "wcId": "jack_623555049",
  "path": "https://xc-1300726975.cos.ap-shanghai.myqcloud.com/%E4%B8%8B%E8%BD%BD%E6%96%87%E4%BB%B6.txt",
  "fileName": "文件.txt"
}"""

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}/sendFile";
String body = "{\n" +
    "  \"wId\": \"0000016f-a805-4715-0001-848f9a297a40\",\n" +
    "  \"wcId\": \"jack_623555049\",\n" +
    "  \"path\": \"https://xc-1300726975.cos.ap-shanghai.myqcloud.com/%E4%B8%8B%E8%BD%BD%E6%96%87%E4%BB%B6.txt\",\n" +
    "  \"fileName\": \"文件.txt\"\n" +
    "}";

HttpClient client = HttpClient.newHttpClient();
HttpRequest request = HttpRequest.newBuilder(URI.create(url))
    .header("Authorization", "Bearer <你的调用凭证>")
    .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}/sendFile';
$body = <<<'JSON'
{
  "wId": "0000016f-a805-4715-0001-848f9a297a40",
  "wcId": "jack_623555049",
  "path": "https://xc-1300726975.cos.ap-shanghai.myqcloud.com/%E4%B8%8B%E8%BD%BD%E6%96%87%E4%BB%B6.txt",
  "fileName": "文件.txt"
}
JSON;

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

成功响应

{
  "code": "1000",
  "message": "发送文件消息成功",
  "data": {
    "type": 6,
    "msgId": 697760551,
    "newMsgId": 8262558808731059065,
    "createTime": 1641458290,
    "wcId": "jack_623555049"
  }
}

错误响应

{
  "message": "失败",
  "code": "1001",
  "data": null
}

使用建议

• 文件 URL 建议放在稳定 CDN，避免下载慢、鉴权失败或链接过期。
• fileName 应与真实文件类型一致，便于接收方打开和识别。
• 多账号发送同一文件时，建议使用素材转发方案，减少重复上传和发送耗时。

验证与排查

场景	处理方式
文件发送慢	检查文件 URL 下载速度和文件大小
文件无法打开	检查 fileName 扩展名是否与文件类型一致
发送失败	确认 URL 可公网访问，且没有鉴权、过期或防盗链限制
多账号发送同文件	使用转发方案，减少重复上传