> ## Documentation Index
> Fetch the complete documentation index at: https://gowa-docs.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# WhatsApp 频道

> 查找、关注和阅读通讯、下载频道媒体并接收实时参与更新。

GOWA 在 API中调用 WhatsApp 频道 **newsletters** 。本页面上的所有请求都使用 Basic Auth 和 `X-Device-Id` 选择的登录设备。 频道ID在`@newsletter`中结束；联系号码或群组JID不是一个频道ID。

在运行曲线示例之前设置服务器 URL 和凭据。使用远程服务器的公共HTTPS URL，并在配置时包含 `APP_BASE_PATH` 。

```bash theme={null}
export GOWA_URL=http://localhost:3000
export GOWA_USER=admin
export GOWA_PASSWORD=replace-with-your-password
export DEVICE_ID=my-device
```

## 查找频道

通过`newsletter_id`或`invite`查找频道元数据。提供准确的。邀请可以是一个完整的 `https://whatsapp.com/channel/...` 链接或其代码。

```bash theme={null}
curl --user "$GOWA_USER:$GOWA_PASSWORD" --get \
  -H "X-Device-Id: $DEVICE_ID" \
  --data-urlencode 'invite=https://whatsapp.com/channel/0029Va4K0PZ5a245NkngBA2M' \
  "$GOWA_URL/newsletter/info"
```

`results` 包含频道元数据，包括其 ID、会话线程元数据和查看者元数据。通过邀请信息查询可在不关注频道的情况下获取公开元数据。通过 JID 查询则取决于所选账号对该频道的访问权限。当 WhatsApp 仅提供公开元数据时，`viewer_metadata` 可能为 `null`。

若要浏览目录，请至少提供一个国家代码。要通过名称搜索，请使用 `search_text` 。

```bash theme={null}
curl --user "$GOWA_USER:$GOWA_PASSWORD" --get \
  -H "X-Device-Id: $DEVICE_ID" \
  --data-urlencode 'country_codes=ID' --data-urlencode 'view=TRENDING' \
  --data-urlencode 'limit=20' "$GOWA_URL/newsletter/directory"

curl --user "$GOWA_USER:$GOWA_PASSWORD" --get \
  -H "X-Device-Id: $DEVICE_ID" \
  --data-urlencode 'search_text=news' "$GOWA_URL/newsletter/directory"
```

| 查询 | 行为 |
| - | - |
| `view` | 默认为 `RECOMMENDED`。也接受 `TRENDING`、`POPULAR`、`NEW` 和 `FEATURED`。按名称搜索时会忽略此选项。 |
| `country_codes` | ISO 两字母代码、重复或逗号分隔。浏览所需。名称搜索不支持国家过滤。 |
| `categories` | 取值为 `BUSINESS`、`ENTERTAINMENT`、`LIFESTYLE`、`NEWS`、`ORGANIZATIONS`、`PEOPLE` 和 `SPORTS`，可通过重复参数或以逗号分隔的方式传入。 |
| `limit` | Default `20`, range `1`–`50`. |
| `cursor` | 使用上一条响应中的 `results.next_cursor` 继续查询，直到 `results.has_more` 不再为 `true`。 |

目录响应将频道放入`results.data`。该目录使用无证WhatsApp 查询，可以独立于GOWA独立更改。

## 跟随或取消关注

```bash theme={null}
curl --user "$GOWA_USER:$GOWA_PASSWORD" \
  -H "X-Device-Id: $DEVICE_ID" -H 'Content-Type: application/json' \
  "$GOWA_URL/newsletter/follow" \
  --data '{"newsletter_id":"120363024512399999@newsletter"}'
```

使用 `POST /newsletter/unfollow` 来取消跟随。`GET /user/my/newsletters` 列出了选定的帐户之后的新闻通讯。

关注频道与订阅实时互动数据更新是两个独立操作。请通过 `/newsletter/live-updates` 管理实时订阅。

## 阅读消息和计数器

```bash theme={null}
curl --user "$GOWA_USER:$GOWA_PASSWORD" --get \
  -H "X-Device-Id: $DEVICE_ID" \
  --data-urlencode 'newsletter_id=120363024512399999@newsletter' \
  --data-urlencode 'count=50' "$GOWA_URL/newsletter/messages"
```

`GET /newsletter/messages` 直接从 WhatsApp 读取帖子，无需关注频道。可获取的历史记录由 WhatsApp 决定。GOWA 不保证保留时长或归档的完整性。`count` 默认为 `50`，接受 `1`–`100`。要加载更早的帖子，请将已返回帖子中最早一条的 `server_id` 作为 `before` 传入。

`results.data` 包含帖子，每条帖子带有 `server_id`、`message_id`、`type`、`timestamp`、`text`、`views_count`、`forwards_count` 以及可选的 `reaction_counts`。内容字段可能缺失。WhatsApp 会向频道管理员报告浏览次数；其他账号可能会看到 `views_count: 0`。

将数字`server_id`，而不是`message_id`用于分页和媒体下载。

```bash theme={null}
curl --user "$GOWA_USER:$GOWA_PASSWORD" --get \
  -H "X-Device-Id: $DEVICE_ID" \
  --data-urlencode 'newsletter_id=120363024512399999@newsletter' \
  --data-urlencode 'after=123' --data-urlencode 'count=50' \
  "$GOWA_URL/newsletter/message-updates"
```

`GET /newsletter/message-updates` 用于刷新计数，不获取消息内容。`after` 为必填项，必须是正整数形式的服务器 ID。`count` 默认为 `50`，最大为 `100`。可选参数 `since` 为非负的 Unix 时间戳，单位为秒。结果使用相同的 `results.data` 列表结构；当 WhatsApp 未返回内容字段时，这些字段会被省略。

## 接收实时计数器更新

配置 [webhook](https://gowa-docs.mintlify.site/zh/concepts/webhooks.md)，然后订阅每个设备所需的频道。

```bash theme={null}
curl --user "$GOWA_USER:$GOWA_PASSWORD" \
  -H "X-Device-Id: $DEVICE_ID" -H 'Content-Type: application/json' \
  "$GOWA_URL/newsletter/live-updates" \
  --data '{"newsletter_id":"120363024512399999@newsletter"}'
```

响应中的 `results` 包含 `newsletter_id`、`duration_seconds`、`expires_at`、`renewed_at` 以及可选的 `last_error`。WhatsApp 提供的订阅有效期很短，实际观察约为 90 秒。GOWA 会在到期前及重新连接后续订。计数更新事件通过 `newsletter.message` webhook 送达。

列表订阅 `GET /newsletter/live-updates` 。它的 `results.data` 包含相同的状态字段。在更新失败时检查 `last_error` 。

```bash theme={null}
curl --user "$GOWA_USER:$GOWA_PASSWORD" -X DELETE --get \
  -H "X-Device-Id: $DEVICE_ID" \
  --data-urlencode 'newsletter_id=120363024512399999@newsletter' \
  "$GOWA_URL/newsletter/live-updates"
```

删除订阅停止更新。WhatsApp 可以继续发送更新，直到现有的赠款过期。 取消不会通过重新连接或飞行更新恢复。删除没有订阅的频道会返回验证错误。

> [!NOTE]
>
> 订阅保存在内存中，服务器无法重启。重启GOWA后重新创建它们。订阅状态属于所选设备。

## 下载频道媒体

```bash theme={null}
curl --user "$GOWA_USER:$GOWA_PASSWORD" --get \
  -H "X-Device-Id: $DEVICE_ID" \
  --data-urlencode 'newsletter_id=120363024512399999@newsletter' \
  "$GOWA_URL/newsletter/messages/123/download"
```

端点直接从 WhatsApp 获取帖子并保存支持的媒体到服务器的媒体目录。 它的 JSON `results` 包含`server_id`、`message_id`、`status`、`media_type`、`mime_type`、`filename`、`file_path`、`file_url`和`file_size`。 REST 处理器提供 `file_url` 作为已保存文件的公共静态URL。 这不是二进制文件响应。缺少帖子或没有可下载媒体的帖子返回错误。


## Related topics

- [GOWA: WhatsApp REST API](https://gowa-docs.mintlify.site/zh/index.md)
- [检查用户是否在WhatsApp](https://gowa-docs.mintlify.site/zh/api-reference/user/检查用户是否在whatsapp.md)
- [认证](https://gowa-docs.mintlify.site/zh/authentication.md)
- [配置引用](https://gowa-docs.mintlify.site/zh/configuration.md)
- [发送限制](https://gowa-docs.mintlify.site/zh/advanced/rate-limiting.md)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.