# C2C单聊 QGFriend

> For the complete documentation index, see [llms.txt](https://simbot.forte.love/v4/llms.txt).

> **Note:**
> 自 `4.0.0-beta6` 开始支持。

`QGFriend` 表示 QQ 机器人中的一个 `C2C` 单聊目标。

和“传统好友列表”不同，`QGFriend` 更接近于 “来自事件上下文的可回复目标”：

* 它通常从 `C2C` 消息事件中得到

* 目前没有对应的“好友列表查询”能力

* 只能稳定拿到 `openid`

所以它通常表现为：

* `id` 可用于标识此单聊目标

* `name` 始终是空字符串，`avatar` 始终是 `null`

## 获取途径

处理 `C2C` 单聊相关事件时， 通常可以从事件的 `author`、`content` 或目标对象链路中拿到 `QGFriend`。

要看这个场景的事件本身， 可继续阅读：

* [事件定义列表](component-qq-guild-event-list.html)

* [QQ机器人](component-qq-guild.html)

## 可用能力

`QGFriend` 当前主要有两类能力：

发送消息
: 继承 `Contact` 的发送能力，可直接发送 `String`、`Message`、`MessageContent`。

上传媒体
: 通过 `uploadMedia(...)` 上传媒体，得到 `QGMedia`。 `QGMedia` 本身是一个消息元素，可用于后续的 `C2C` / QQ 群消息发送。

## 发送消息

Kotlin:

```KOTLIN
suspend fun reply(friend: QGFriend) {
    friend.send("你好，这是一条 C2C 单聊消息")
}
```

Java:

```JAVA
QGFriend friend = ...;

friend.sendAsync("你好，这是一条 C2C 单聊消息")
        .thenAccept(receipt -> { });
```

```JAVA
QGFriend friend = ...;

var receipt = friend.sendBlocking("你好，这是一条 C2C 单聊消息");
```

```JAVA
QGFriend friend = ...;

friend.sendReserve("你好，这是一条 C2C 单聊消息")
        .transform(SuspendReserves.mono())
        .subscribe(receipt -> { });
```

## 上传媒体

目前公开了两组上传函数：

* `uploadMedia(url: String, type: Int)`

* `uploadMedia(resource: Resource, type: Int)` (`4.1.1` 起)

其中 `type` 与开放平台媒体类型一致：

* `1`: 图片

* `2`: 视频

* `3`: 语音

* `4`: 文件（当前平台侧仍有限制）

Kotlin:

```KOTLIN
suspend fun upload(friend: QGFriend) {
    val media = friend.uploadMedia(
        url = "https://example.com/example.png",
        type = 1
    )

    // media: QGMedia
}
```

Java:

```JAVA
QGFriend friend = ...;

friend.uploadMediaAsync("https://example.com/example.png", 1)
        .thenAccept(media -> { });
```

```JAVA
QGFriend friend = ...;

var media = friend.uploadMediaBlocking("https://example.com/example.png", 1);
```

```JAVA
QGFriend friend = ...;

friend.uploadMediaReserve("https://example.com/example.png", 1)
        .transform(SuspendReserves.mono())
        .subscribe(media -> { });
```