API

我想要 …

选择你的打算；下面只列出所需步骤。完整的参考文档在更下方。

在你的某个群组中，通过群组菜单的“机器人 → 我的机器人”创建机器人，设置头像、名称和 @名称。它的令牌只显示一次。
分享它的“添加机器人”链接，或将其提交到机器人目录，经团队审核后会出现在那里；可以管理群组角色的人按其同意的权限将它加入。
以流（GET /v2/events/stream）或在你的地址接收其群组中发生的事，并用 POST /v2/channels/{id}/messages 发消息。更多见机器人。
注册命令（PUT /v2/me/commands），并用卡片和按钮回复；机器人在语音频道中占一个位置播放音乐（POST /v2/channels/{id}/voice）。

概览

v2 让你自己的程序与 tellmelo 对话：每个请求一个密钥，返回 JSON，所有列表都以相同方式分页。规则与应用中相同。

每个路径都以 https://api.tellmelo.com/v2 开头。
请求和响应都是 UTF-8 编码的 JSON。字段名、代码和值都是英文，并保持英文。
密钥代表你的账号：你在应用里看不到的，它也读不到。

https://api.tellmelo.com/v2

快速开始

在“开发者区 → API”中创建密钥并复制。它只显示一次。
用它调用根路径。响应会显示版本、密钥权限以及本分钟剩余的请求数。
所有路径的用法都一样：请求头带密钥，返回 JSON，列表用 items 和 next。

curl -H "Authorization: Bearer tm_key_…" https://api.tellmelo.com/v2

{
  "name": "tellmelo",
  "version": "2.20",
  "scope": "read write",
  "rateLimit": {
    "limit": 120,
    "remaining": 117
  },
  "docs": "/developers/docs",
  "spec": "/api/v2/openapi.json"
}

接下来：/me 获取你的个人主页，/posts 获取公开帖子，/feed 获取你的动态。

试一试

选择一项任务，填写字段，然后复制请求或直接从这里发送。写入操作会先询问。代码从 TELLMELO_KEY 读取密钥。

任务

read API 版本和本站名称。

curl \
  -H "Authorization: Bearer $TELLMELO_KEY" \
  "https://api.tellmelo.com/v2"

你的密钥只保留在此页面，直到你关闭它。

你的密钥

每个账号最多 10 个密钥，每个都有名称、自己的权限，并可设置到期日期。密钥以 tm_key_ 开头，只显示一次。丢失了？更新它，旧值随即失效。

在“开发者区 → API”中创建。它放在请求头中：

curl -H "Authorization: Bearer tm_key_…" \
  https://api.tellmelo.com/v2/posts

或者，如果更方便，放在单独的请求头里：

curl -H "X-Tellmelo-Key: tm_key_…" https://api.tellmelo.com/v2

不要放在 URL 里：它会出现在日志和浏览器历史中。

同一个密钥也可加载图片：每个 url 都指向 /api/media；在那里同样把密钥放在请求头中。

curl -H "Authorization: Bearer tm_key_…" \
  -o picture.webp "https://api.tellmelo.com/media?id=…"

密钥能做什么

密钥始终可以读取；如果你允许，还可以写入、赠送、上传媒体和管理群组。下面每条路径都说明了它需要什么：

read：读取。公开帖子、个人资料、群组和标签，以及你的动态、通知、消息和你所在群组的频道。
write：操作。发帖、回复、投票、发消息、在群组聊天中发言、关注、加入、屏蔽、将通知标为已读。
gifts：赠送。从合作伙伴的额度送给成员，以及在新帖子下发放礼物。这是单独的权限，确保用于发帖的密钥永远无法送出任何东西。
media：你自己的媒体库。上传、修改、分享和删除 GIF 和视频。这是一项单独的权限，因为上传会消耗账号的视频点数。查找已分享的 GIF 和视频只需要 read。
groups：管理群组。角色、频道、分类、邀请链接、动态频道、移除、禁言、踢出和封禁，以你的账号在该群组中的权限为限。这是单独的权限，因此用于发布的密钥永远不会改变谁在群组中能做什么。

任何密钥都做不到的事

任何密钥都无法触及密码、邮箱地址、账号类型、地点、角色、删除、会话、推送设备或其他密钥，也无法触及管理后台或群组管理。密码所保护的，任何密钥都做不到。

机器人

机器人是用于群组的独立账户，类型为 bot：没有密码和邮箱，由你的程序用它自己的密钥运行。它与其他账户使用同一套 API，在群组中能做其角色允许的一切。

在你的某个群组中打开群组菜单，在“机器人 → 我的机器人”中创建机器人，设置头像、封面、名称、用户名和简介。令牌只显示一次；它拥有 read、write、media 和 groups 权限。
分享机器人的链接，或将其提交到机器人目录；团队审核后它就会出现在那里。可以管理群组角色的人选择权限；机器人加入并获得自己的角色。
你的程序以 Authorization: Bearer … 发送令牌，以流读取其群组的事件，并使用机器人、频道和群组下的路由。

一个以流读取事件、并仅对提问者用 pong 回复 /ping 命令的小机器人：

// Node 18 or newer: reads the events of the bot's groups as they happen and answers /ping.
const BASE = 'https://api.tellmelo.com/v2';
const KEY = process.env.TELLMELO_BOT_TOKEN;
const call = (method, path, body) =>
  fetch(BASE + path, {
    method,
    headers: { Authorization: 'Bearer ' + KEY, 'Content-Type': 'application/json' },
    body: body && JSON.stringify(body),
  }).then((r) => r.json());

await call('PUT', '/me/commands', { commands: [{ name: 'ping', description: 'Answers pong' }] });

let last = '';
for (;;) {
  // The stream closes after ten minutes; Last-Event-ID goes on where it stopped.
  const res = await fetch(BASE + '/events/stream', {
    headers: { Authorization: 'Bearer ' + KEY, ...(last && { 'Last-Event-ID': last }) },
  });
  const reader = res.body.pipeThrough(new TextDecoderStream()).getReader();
  let buffer = '';
  for (;;) {
    const { value, done } = await reader.read();
    if (done) break;
    buffer += value;
    let end;
    while ((end = buffer.indexOf('

')) >= 0) {
      const data = buffer.slice(0, end).split('
').find((l) => l.startsWith('data: '));
      buffer = buffer.slice(end + 2);
      if (!data) continue;
      const event = JSON.parse(data.slice(6));
      last = event.id;
      if (event.type === 'command' && event.data.command === 'ping')
        await call('POST', '/interactions/' + event.data.interaction + '/reply', { text: 'pong', private: true });
    }
  }
}

同一个机器人的 Python 版本，按页获取事件：

# Python 3 with requests: the same bot, reading the events page by page.
import os, time, requests

BASE = 'https://api.tellmelo.com/v2'
H = {'Authorization': 'Bearer ' + os.environ['TELLMELO_BOT_TOKEN']}
requests.put(BASE + '/me/commands', headers=H,
             json={'commands': [{'name': 'ping', 'description': 'Answers pong'}]})

since = '0'
while True:
    page = requests.get(BASE + '/events', headers=H, params={'since': since}).json()
    for event in page['items']:
        if event['type'] == 'command' and event['data']['command'] == 'ping':
            requests.post(f"{BASE}/interactions/{event['data']['interaction']}/reply",
                          headers=H, json={'text': 'pong'})
    since = page['next'] or since
    time.sleep(2)

机器人在群组中能做什么由它在那里的角色决定，而不是令牌。角色以它的名字命名；群组在群组设置的角色中更改其权限，并在群组菜单的“机器人 → 本群组中”移除机器人。
每个账号最多 5 个机器人；每个群组按其权益允许的数量。机器人在每个群组每分钟最多发 30 条消息，无法通过搜索找到，只会给先给它发过消息的人发消息。适用限制。
事件也可发送到你自己的 HTTPS 地址（像 webhook 一样签名并重试）。此外：命令（PUT /v2/me/commands），回复可面向所有人或仅提问者；消息中的卡片和按钮；以及语音频道中的音乐（POST /v2/channels/{id}/voice）：全部见机器人。

请求与响应

处处都是 JSON。 每个响应都是 UTF-8 编码的 application/json，包括错误。只有图片以图片形式返回。
你发送的内容。 POST 在正文中以 JSON 携带字段。如果某个字段也出现在 URL 中，以正文为准。
时间是自 1970 年 1 月 1 日（UTC）起的毫秒数。
ID 是字符串。只能整体比较。
每个字段始终存在。 缺失的值为 null；列表可以为空。
文本是纯文本，与写入时完全一致。#标签、@名字 和链接保持原样，本站自定义表情也以 :name: 形式保留；其图片列在 /emojis 中。
图片是相对地址 /api/media?id=…。请求头中没有密钥会返回 401。

分页

每个列表都接受 limit 和 cursor，并返回 items 和 next。把 next 作为 cursor 传回即可获取下一页；next 为空时即结束。游标是不透明的：不要解析，也不要自己构造。

{ "items": [ … ], "next": "MTc1ODYyNDAwMDAwMDo1ZjBjMmE5ZS04ZDQx" }

curl -H "Authorization: Bearer tm_key_…" \
  "https://api.tellmelo.com/v2/posts?limit=20&cursor=MTc1ODYyNDAwMDAwMDo1ZjBjMmE5ZS04ZDQx"

不传 limit 时为 20 条，最多 50 条。有些列表不分页；它们的 next 始终为 null。

只取新内容

每个响应都带有 ETag。下次请求时作为 If-None-Match 传回：如果没有变化，你会收到无正文的 304。

ETag: W/"3Qk1mJ7fQe2Yb0sVxT9aL4pNdRc"
If-None-Match: W/"3Qk1mJ7fQe2Yb0sVxT9aL4pNdRc"  →  304

例外：/feed 没有 ETag，因为它的顺序一直在变；写入操作永远不会返回 304。

限额

每个密钥每分钟可发送 120 个请求，“机构”套餐为 600 个，除非管理员另有设置。超出后会收到 429，且不会执行任何操作。等一分钟再发送请求。

X-RateLimit-Limit: 120
X-RateLimit-Remaining: 117
X-RateLimit-Reset: 1758624060

写入操作也计入应用的限额，例如几分钟内可发多少帖子。这同样返回带 rate_limited 的 429。

请求头

除密钥外，不需要任何请求头。

你发送的

请求头	含义
`Authorization`	携带密钥：`Bearer tm_key_…`。通常的方式。
`X-Tellmelo-Key`	密钥，作为 `Authorization` 的替代。
`Content-Type`	`application/json`，用于带正文的请求。
`If-None-Match`	上一次响应的 `ETag`。如果此后没有变化，响应为无正文的 `304`。

返回的

请求头	含义
`ETag`	本次响应的指纹（`W/`）。作为 `If-None-Match` 传回。
`X-RateLimit-Limit`	此密钥每分钟可发送多少请求。
`X-RateLimit-Remaining`	当前分钟内还剩多少。
`X-RateLimit-Reset`	下一分钟何时开始，以自 1970 年（UTC）起的秒数表示。
`X-Tellmelo-Scope`	此密钥能做什么：`read` 或 `read write`。
`Retry-After`	收到 `429` 时：再次请求前需要等待的秒数。
`WWW-Authenticate`	没有密钥返回 `401` 时：`Bearer`。
`Cache-Control`	`no-store`：任何代理都不能缓存响应。你仍可以用 `ETag` 检查。

出错时

错误以 JSON 返回：error 中是供程序使用的固定英文代码，message 中是给人看的句子，并附相应的状态码。只比较代码；句子可能会变。

{ "error": "rate_limited",
  "message": "Too many requests. Try again in a minute.",
  "limit": 120 }

有些错误会多带一个字段：缺少密钥的 401 带 docs，429 带 limit。

状态	代码	含义
`400`	`bad_request`	请求无法读取、缺少必填字段或某个值不被允许。
`401`	`key_missing`	请求头中没有密钥。
`401`	`key_invalid`	密钥无效：输错、已被替换，或账号已被封禁。
`401`	`unauthorized`	因未登录被拒绝，原因与密钥无关。
`403`	`scope_missing`	密钥缺少所需权限，通常是 `write`。
`403`	`account_data_locked`	密码、邮箱地址或删除等账号数据不对密钥开放。
`403`	`forbidden`	你的账号不能这样做，例如因权限被收回或被屏蔽。
`403`	`timed_out`	你的账号目前在这个群组中被禁言。
`404`	`unknown_path`	没有这个路径，或不支持该方法。
`404`	`not_found`	未找到，或你无权查看。
`409`	`conflict`	与已有内容冲突，例如名称已被占用。
`409`	`feed_off`	该群组的动态频道已关闭。
`413`	`too_large`	对本站来说太大。
`422`	`unprocessable`	可以读取，但这种形式无法处理。
`429`	`rate_limited`	请求太多。未执行任何操作；请稍候再试。
`500`	`internal_error`	服务器出了问题。

版本

版本号在路径中。只要写的是 v2，路径和字段就保持不变；只会新增内容。

新增内容会提升第二位数字。每个路径都注明了从哪个版本开始提供。

2.20: PUT /v2/roles/{id}/selfGET /v2/eventsGET /v2/events/streamGET /v2/me/commandsPUT /v2/me/commandsPOST /v2/interactions/{id}/replyGET /v2/communities/{id}/emojisPOST /v2/communities/{id}/emojisDELETE /v2/communities/{id}/emojis/{name}PUT /v2/communities/{id}/channels/shapePOST /v2/channels/{id}/voice
2.19: POST /v2/replies/{id}/votePOST /v2/replies/{id}/pickGET /v2/posts/{id}/replies/waitingPOST /v2/replies/{id}/decideGET /v2/posts/{id}/replies/plannedPUT /v2/me/planned-replies/{id}POST /v2/me/planned-replies/{id}/sendDELETE /v2/me/planned-replies/{id}GET /v2/posts/{id}/reply-settingsPUT /v2/posts/{id}/reply-settingsPOST /v2/posts/{id}/coauthorDELETE /v2/posts/{id}/coauthorPOST /v2/posts/{id}/pinPOST /v2/conversations/{with}/plannedGET /v2/me/planned-messagesPOST /v2/me/planned-messages/{id}/sendDELETE /v2/me/planned-messages/{id}GET /v2/profiles/{handle}/followersGET /v2/profiles/{handle}/followingGET /v2/me/relationsGET /v2/me/collectionsPOST /v2/me/collectionsPUT /v2/me/collections/{id}DELETE /v2/me/collections/{id}GET /v2/me/collections/{id}/postsPOST /v2/me/collections/{id}/postsGET /v2/profiles/{handle}/eventsPOST /v2/me/eventsPUT /v2/me/events/{id}DELETE /v2/me/events/{id}GET /v2/me/events/{id}/signupsPOST /v2/events/{id}/signupPOST /v2/me/picturesPUT /v2/me/profileGET /v2/me/emojisPOST /v2/me/emojis/picturesPOST /v2/me/emojisDELETE /v2/me/emojis/{name}PUT /v2/me/emojis/sharingGET /v2/me/webhooksPOST /v2/me/webhooksDELETE /v2/me/webhooks/{id}POST /v2/me/webhooks/{id}/testPOST /v2/communitiesPUT /v2/communities/{id}GET /v2/communities/{id}/botsGET /v2/communities/{id}/voice
2.16: PUT /v2/communities/{id}/members/{member}/timeoutDELETE /v2/communities/{id}/members/{member}/timeoutGET /v2/communities/{id}/bansPUT /v2/communities/{id}/bans/{member}DELETE /v2/communities/{id}/bans/{member}
2.15: GET /v2/communities/{id}/channelsGET /v2/channels/{id}/messagesGET /v2/communities/{id}/membersGET /v2/communities/{id}/rolesGET /v2/communities/{id}/bellGET /v2/invites/{code}POST /v2/channels/{id}/messagesPOST /v2/channels/{id}/readDELETE /v2/channel-messages/{id}PUT /v2/communities/{id}/bellPOST /v2/invites/{code}/joinPOST /v2/communities/{id}/rolesPUT /v2/roles/{id}DELETE /v2/roles/{id}PUT /v2/communities/{id}/roles/orderPUT /v2/roles/{id}/members/{member}POST /v2/communities/{id}/channelsPUT /v2/channels/{id}DELETE /v2/channels/{id}PUT /v2/communities/{id}/channels/orderGET /v2/channels/{id}/overridesPUT /v2/channels/{id}/overrides/{role}POST /v2/communities/{id}/categoriesPUT /v2/categories/{id}DELETE /v2/categories/{id}PUT /v2/communities/{id}/feedGET /v2/communities/{id}/invitesPOST /v2/communities/{id}/invitesDELETE /v2/invites/{code}POST /v2/channel-messages/{id}/removePOST /v2/communities/{id}/posts/{post}/removeDELETE /v2/communities/{id}/members/{member}GET /v2/communities/{id}/log
2.14: GET /v2/mediaGET /v2/media/mineGET /v2/media/{id}POST /v2/media/uploadsPUT /v2/media/uploads/{upload}POST /v2/media/{id}DELETE /v2/media/{id}
2.12: GET /v2/me/scheduledPOST /v2/posts/{id}/schedulePOST /v2/posts/{id}/editPOST /v2/replies/{id}/editDELETE /v2/replies/{id}POST /v2/replies/{id}/likeDELETE /v2/conversations/{with}/messages/{id}GET /v2/partner/quotaGET /v2/partner/giftsPOST /v2/partner/giftsGET /v2/gift-dropsPOST /v2/gift-drops
2.1: GET /v2/emojisPOST /v2/conversations/{with}/read
2.0: GET /v2GET /v2/postsGET /v2/posts/{id}GET /v2/posts/{id}/repliesGET /v2/profiles/{handle}GET /v2/profiles/{handle}/postsGET /v2/communitiesGET /v2/communities/{id}GET /v2/communities/{id}/postsGET /v2/tagsGET /v2/searchGET /v2/meGET /v2/feedGET /v2/notificationsGET /v2/conversationsGET /v2/conversations/{with}/messagesPOST /v2/postsDELETE /v2/posts/{id}POST /v2/posts/{id}/repliesPOST /v2/posts/{id}/votePOST /v2/relationsPOST /v2/conversations/{with}/messagesPOST /v2/notifications/read

https://api.tellmelo.com/v1/ 已停用：旧路径返回 410，并在正文中指明新路径。

端点

先一览所有路径，再逐个附上示例。

路径	权限	用途
入口
GET`/v2`	`read`	API 版本和本站名称。
帖子
GET`/v2/posts`	`read`	公开帖子，最新的在前。
GET`/v2/posts/{id}`	`read`	按 `id` 获取单条帖子。
POST`/v2/posts`	`write`	发布帖子。
DELETE`/v2/posts/{id}`	`write`	删除你自己的一条帖子。
GET`/v2/me/scheduled`	`read`	你还没发布的帖子，以及它们在等什么。
POST`/v2/posts/{id}/schedule`	`write`	修改定时帖子的发布时间，或帖子自动删除的时间。
POST`/v2/posts/{id}/edit`	`write`	修改你某条帖子的文字。
GET`/v2/posts/{id}/reply-settings`	`read`	谁可以回复你的帖子、回复是否需要批准，以及慢速模式。
PUT`/v2/posts/{id}/reply-settings`	`write`	修改你帖子的回复设置。未提供的项目保持不变。
POST`/v2/posts/{id}/coauthor`	`write`	接受或拒绝共同作者邀请。
DELETE`/v2/posts/{id}/coauthor`	`write`	退出共同作者，或作为作者把共同作者从帖子中移除。
POST`/v2/posts/{id}/pin`	`write`	把你的帖子置顶到主页，或取消置顶。
回复
GET`/v2/posts/{id}/replies`	`read`	帖子的回复，不含已屏蔽的账号。
POST`/v2/posts/{id}/replies`	`write`	回复帖子。
POST`/v2/replies/{id}/edit`	`write`	修改你某条回复的文字。
DELETE`/v2/replies/{id}`	`write`	删除你的某条回复。
POST`/v2/replies/{id}/like`	`write`	赞成一条回复（自回复改为投票后，点赞即赞成），或撤回赞成；反对票保留。
POST`/v2/replies/{id}/vote`	`write`	给一条回复投赞成票或反对票，或撤回你的投票。返回你的投票和投票后的得分。
POST`/v2/replies/{id}/pick`	`write`	把你帖子下的一条回复标为最佳，或取消标记。
GET`/v2/posts/{id}/replies/waiting`	`read`	帖子下等待批准的回复：你自己的帖子下是全部，否则只有你自己的。
POST`/v2/replies/{id}/decide`	`write`	批准或拒绝你帖子下一条等待中的回复。被拒绝的回复会被删除。
GET`/v2/posts/{id}/replies/planned`	`read`	你在某个帖子下定时稍后发布的回复。
PUT`/v2/me/planned-replies/{id}`	`write`	修改定时回复的文字或时间。发送失败的回复会重新等待。
POST`/v2/me/planned-replies/{id}/send`	`write`	立即发送一条定时回复。
DELETE`/v2/me/planned-replies/{id}`	`write`	删除一条定时回复。
投票
POST`/v2/posts/{id}/vote`	`write`	参与投票。
个人主页
GET`/v2/profiles/{handle}`	`read`	按短名称获取个人主页。
GET`/v2/profiles/{handle}/posts`	`read`	某个个人主页的公开帖子，最新的在前。
GET`/v2/profiles/{handle}/events`	`read`	某个主页即将举行的活动，最近的在前。
POST`/v2/me/events`	`write`	创建活动。返回它的 `id`。
PUT`/v2/me/events/{id}`	`write`	修改你的活动。所有字段都会重新设置。
DELETE`/v2/me/events/{id}`	`write`	删除你的活动。
GET`/v2/me/events/{id}/signups`	`read`	谁报名了你的活动。
POST`/v2/events/{id}/signup`	`write`	报名参加活动或取消报名。
群组
GET`/v2/communities`	`read`	本实例的公开群组；使用 `mine=true` 时为你账号所在的群组。
GET`/v2/communities/{id}`	`read`	按 `id` 获取单个群组。
GET`/v2/communities/{id}/posts`	`read`	群组动态频道中的帖子，最新的在前。
GET`/v2/communities/{id}/members`	`read`	群组成员及其角色。
GET`/v2/communities/{id}/roles`	`read`	群组的角色，最高的在前，@everyone 在最后。
GET`/v2/communities/{id}/bell`	`read`	群组会向你发送哪些通知。
GET`/v2/invites/{code}`	`read`	加入前查看邀请链接背后的群组。
PUT`/v2/roles/{id}/self`	`write`	领取或取消一个自选身份组。
GET`/v2/communities/{id}/emojis`	`read`	群组自己的表情。
PUT`/v2/communities/{id}/bell`	`write`	设置群组向你发送哪些通知。
POST`/v2/invites/{code}/join`	`write`	通过邀请链接加入群组。
GET`/v2/communities/{id}/bots`	`read`	群组的机器人及其角色允许的操作。
频道
GET`/v2/communities/{id}/channels`	`read`	你能看到的群组频道，按其顺序排列。
GET`/v2/channels/{id}/messages`	`read`	聊天频道中的消息，最新的在前。
POST`/v2/channels/{id}/messages`	`write`	在聊天频道中发送消息。
POST`/v2/channels/{id}/read`	`write`	将聊天频道标为已读，直到某个时间点。
DELETE`/v2/channel-messages/{id}`	`write`	删除你在聊天频道中的一条消息。
GET`/v2/communities/{id}/voice`	`read`	群组语音频道中当前有谁，按频道列出。
管理群组
POST`/v2/communities/{id}/emojis`	`groups`	为群组添加一个表情。
DELETE`/v2/communities/{id}/emojis/{name}`	`groups`	从群组移除一个表情。
POST`/v2/communities/{id}/roles`	`groups`	创建角色。
PUT`/v2/roles/{id}`	`groups`	修改角色的名称、颜色和权限。
DELETE`/v2/roles/{id}`	`groups`	删除角色。
PUT`/v2/communities/{id}/roles/order`	`groups`	设置角色的等级顺序。
PUT`/v2/roles/{id}/members/{member}`	`groups`	给成员授予或收回角色。
POST`/v2/communities/{id}/channels`	`groups`	创建聊天频道。
PUT`/v2/channels/{id}`	`groups`	修改频道的名称、主题和分类。
DELETE`/v2/channels/{id}`	`groups`	删除聊天频道及其消息。
PUT`/v2/communities/{id}/channels/order`	`groups`	设置分类和聊天频道的顺序。
PUT`/v2/communities/{id}/channels/shape`	`groups`	设定群组所有频道图标的形状。
GET`/v2/channels/{id}/overrides`	`groups`	角色在某个频道中与在群组中不同的权限。
PUT`/v2/channels/{id}/overrides/{role}`	`groups`	设置某个角色在频道中的不同权限。
POST`/v2/communities/{id}/categories`	`groups`	创建频道分类。
PUT`/v2/categories/{id}`	`groups`	重命名分类。
DELETE`/v2/categories/{id}`	`groups`	删除分类。
PUT`/v2/communities/{id}/feed`	`groups`	开启或关闭群组的动态频道。
GET`/v2/communities/{id}/invites`	`groups`	群组仍然有效的邀请链接。
POST`/v2/communities/{id}/invites`	`groups`	创建邀请链接。
DELETE`/v2/invites/{code}`	`groups`	收回邀请链接。
POST`/v2/channel-messages/{id}/remove`	`groups`	从频道中移除其他成员的消息。
POST`/v2/communities/{id}/posts/{post}/remove`	`groups`	从群组中移除帖子。
DELETE`/v2/communities/{id}/members/{member}`	`groups`	将成员踢出群组。
PUT`/v2/communities/{id}/members/{member}/timeout`	`groups`	禁言成员。
DELETE`/v2/communities/{id}/members/{member}/timeout`	`groups`	解除禁言。
GET`/v2/communities/{id}/bans`	`groups`	群组当前的封禁。
PUT`/v2/communities/{id}/bans/{member}`	`groups`	封禁成员。
DELETE`/v2/communities/{id}/bans/{member}`	`groups`	解除封禁。
GET`/v2/communities/{id}/log`	`groups`	管理层记录：谁移除了什么以及原因。
POST`/v2/communities`	`groups`	创建一个群组。返回它的 `id`；你是创建者。
PUT`/v2/communities/{id}`	`groups`	修改你管理的群组。未提供的项目保持不变。
机器人
GET`/v2/events`	`read`	机器人所在群组自某事件以来的事件，按页读取。
GET`/v2/events/stream`	`read`	机器人所在群组的事件，发生即送达（server-sent events）。
GET`/v2/me/commands`	`read`	机器人的命令。
PUT`/v2/me/commands`	`write`	一次性设置机器人的全部命令。
POST`/v2/interactions/{id}/reply`	`write`	回复命令或按钮。
POST`/v2/channels/{id}/voice`	`write`	在语音频道中占一个位置来播放音乐或声音。
发现
GET`/v2/tags`	`read`	当前流行的标签。
GET`/v2/search`	`read`	在帖子、名字、短名称和标签中搜索。
GET`/v2/emojis`	`read`	本站自定义表情及其图片地址。
GIF 和视频
GET`/v2/media`	`read`	已分享的 GIF 或视频，最常用的排在前面。
GET`/v2/media/mine`	`media`	你自己的媒体库，最新的排在前面。
GET`/v2/media/{id}`	`read`	一个 GIF 或视频，你自己的或已分享的。
POST`/v2/media/uploads`	`media`	开始上传。
PUT`/v2/media/uploads/{upload}`	`media`	发送文件的一块。
POST`/v2/media/{id}`	`media`	修改你的一个 GIF 或视频。
DELETE`/v2/media/{id}`	`media`	删除你的一个 GIF 或视频。
你的账号
GET`/v2/me`	`read`	你自己的个人主页，包含其他路径需要的 `id`。
GET`/v2/feed`	`read`	你自己的动态，与应用中的排列方式相同。
POST`/v2/me/pictures`	`write`	以字节形式上传一张图片。返回 `id` 和 `url`；之后用这个 `id` 作为头像、封面或用在帖子里。
PUT`/v2/me/profile`	`profile`	修改你的主页：名称、简介、头像、封面和主页颜色。未提供的项目保持不变。
GET`/v2/me/emojis`	`read`	你自己的表情。
POST`/v2/me/emojis/pictures`	`profile`	以字节形式上传自定义表情的图片。
POST`/v2/me/emojis`	`profile`	创建一个自定义表情。返回你的全部表情。
DELETE`/v2/me/emojis/{name}`	`profile`	删除一个自定义表情。返回剩下的表情。
PUT`/v2/me/emojis/sharing`	`profile`	设置你的粉丝能否在自己的文字中使用你的表情。
GET`/v2/me/webhooks`	`webhooks`	你的 Webhook 及其状态。
POST`/v2/me/webhooks`	`webhooks`	创建 Webhook。返回 `id` 和签名用的密钥，仅此一次。
DELETE`/v2/me/webhooks/{id}`	`webhooks`	删除 Webhook。
POST`/v2/me/webhooks/{id}/test`	`webhooks`	向 Webhook 发送测试。
通知
GET`/v2/notifications`	`read`	你的通知，最新的在前。
POST`/v2/notifications/read`	`write`	将你的通知标为已读。
私信
GET`/v2/conversations`	`read`	你的收件箱：每个对话一行，最新的在前。
GET`/v2/conversations/{with}/messages`	`read`	某个对话中的私信，最新的在前。
POST`/v2/conversations/{with}/messages`	`write`	在对话中发送私信。
POST`/v2/conversations/{with}/read`	`write`	将某个对话的所有私信标为已读。
DELETE`/v2/conversations/{with}/messages/{id}`	`write`	删除你的某条私信。
POST`/v2/conversations/{with}/planned`	`write`	定时稍后发送一条私信。返回定时私信的 `id`。
GET`/v2/me/planned-messages`	`read`	你尚未发送的定时私信，按时间排序。
POST`/v2/me/planned-messages/{id}/send`	`write`	立即发送一条被暂缓或发送失败的定时私信。
DELETE`/v2/me/planned-messages/{id}`	`write`	在发送前删除一条定时私信。
关系
POST`/v2/relations`	`write`	点赞、收藏、转发、关注、加入、屏蔽、静音，取决于 `kind`。
GET`/v2/profiles/{handle}/followers`	`read`	谁关注了某个主页，最新的在前。
GET`/v2/profiles/{handle}/following`	`read`	某个主页关注了谁，最新的在前。
GET`/v2/me/relations`	`read`	你屏蔽、静音或仅在私信中屏蔽的账号，最新的在前。
收藏夹
GET`/v2/me/collections`	`read`	你的收藏夹及其中的帖子数。
POST`/v2/me/collections`	`write`	创建收藏夹。返回它的 `id`。
PUT`/v2/me/collections/{id}`	`write`	重命名收藏夹。
DELETE`/v2/me/collections/{id}`	`write`	删除收藏夹。
GET`/v2/me/collections/{id}/posts`	`read`	收藏夹中的帖子，与收藏标签页相同。
POST`/v2/me/collections/{id}/posts`	`write`	把帖子放入收藏夹或从中移出。
礼物
GET`/v2/partner/quota`	`read`	你的额度里还剩多少可以送。
GET`/v2/partner/gifts`	`read`	你从额度送出了什么、送给谁、什么时候——最新的在前。
POST`/v2/partner/gifts`	`gifts`	从你的额度中把套餐月数或火花送给一位成员。
GET`/v2/gift-drops`	`read`	你在帖子下发放的礼物：还剩多少名额，以及是怎么付款的。
POST`/v2/gift-drops`	`gifts`	发布一条带礼物的帖子，供他人领取。

入口

每个程序的第一个请求：密钥能用吗，它能做什么？

GET`/v2`

API 版本和本站名称。

权限 read
带 ETag
自 v2.0

末尾不要加斜杠：https://api.tellmelo.com/v2/ 会以 308 重定向到 https://api.tellmelo.com/v2，并非所有程序都会跟随。

请求示例

curl \
  -H "Authorization: Bearer tm_key_…" \
  "https://api.tellmelo.com/v2"

响应

返回一个 Service。

示例

{
  "name": "tellmelo",
  "version": "2.20",
  "scope": "read write",
  "rateLimit": {
    "limit": 120,
    "remaining": 117
  },
  "docs": "/developers/docs",
  "spec": "/api/v2/openapi.json"
}

可能的状态： 200304401429

帖子

读取公开帖子、发布自己的帖子，以及再次删除。

GET`/v2/posts`

公开帖子，最新的在前。

权限 read
可分页
带 ETag
自 v2.0

在公开路径上，counts.likes 和 counts.reposts 始终为 0，pinned 为 false。

群组中的帖子不在这里，而在 /communities/{id}/posts。

参数

名称	类型	含义
`limit`在查询中	`integer`可选	每页条目数：默认 20，最多 50。
`cursor`在查询中	`string`可选	上一个响应中的 `next`。不传则从头开始。

请求示例

curl \
  -H "Authorization: Bearer tm_key_…" \
  "https://api.tellmelo.com/v2/posts?limit=20"

响应

返回一页 Post，形式为 `items` 和 `next`。

示例

{
  "items": [
    {
      "id": "5f0c2a9e-8d41-4b7a-9c3e-2e61d0f4a7b1",
      "text": "The bees are back in the garden 🐝 #garden",
      "kind": "poll",
      "author": {
        "id": "a3e1f7c2-54b9-4d0e-8f16-7b2c9d4e1a05",
        "handle": "mara",
        "name": "Mara 🌻",
        "verified": true,
        "accountKind": "person"
      },
      "community": {
        "id": "c81d4e2a-0f3b-4a6c-9e57-1d2b3c4a5f60",
        "name": "Urban Gardening"
      },
      "media": [
        {
          "url": "/api/media?id=b2d7e9f1-3c4a-4e8b-a1f0-6d5c4b3a2918",
          "kind": "image",
          "poster": null,
          "ai": "without"
        }
      ],
      "poll": {
        "options": [
          {
            "text": "Lavender",
            "votes": 12
          },
          {
            "text": "Sunflowers",
            "votes": 7
          },
          {
            "text": "Clover",
            "votes": 3
          }
        ],
        "total": 22,
        "multiple": false,
        "endsAt": null,
        "running": true,
        "resultsVisible": true,
        "myVotes": [
          0
        ]
      },
      "quotes": null,
      "continues": null,
      "counts": {
        "replies": 4,
        "likes": 31,
        "reposts": 2
      },
      "pinned": false,
      "giftDrop": {
        "item": "plan",
        "quantity": 3,
        "places": 10,
        "left": 4,
        "audience": "followers",
        "newAccounts": false,
        "status": "open",
        "claimed": true
      },
      "createdAt": 1758624000000
    }
  ],
  "next": "MTc1ODYyNDAwMDAwMDo1ZjBjMmE5ZS04ZDQx"
}

可能的状态： 200304401429

GET`/v2/posts/{id}`

按 id 获取单条帖子。

权限 read
带 ETag
自 v2.0

在公开路径上，counts.likes 和 counts.reposts 始终为 0，pinned 为 false。

群组中的帖子不在这里，而在 /communities/{id}/posts。

参数

名称	类型	含义
`id`在路径中	`string`必填	帖子的 `id`。

请求示例

curl \
  -H "Authorization: Bearer tm_key_…" \
  "https://api.tellmelo.com/v2/posts/5f0c2a9e-8d41-4b7a-9c3e-2e61d0f4a7b1"

响应

返回一个 Post。

示例

{
  "id": "5f0c2a9e-8d41-4b7a-9c3e-2e61d0f4a7b1",
  "text": "The bees are back in the garden 🐝 #garden",
  "kind": "poll",
  "author": {
    "id": "a3e1f7c2-54b9-4d0e-8f16-7b2c9d4e1a05",
    "handle": "mara",
    "name": "Mara 🌻",
    "verified": true,
    "accountKind": "person"
  },
  "community": {
    "id": "c81d4e2a-0f3b-4a6c-9e57-1d2b3c4a5f60",
    "name": "Urban Gardening"
  },
  "media": [
    {
      "url": "/api/media?id=b2d7e9f1-3c4a-4e8b-a1f0-6d5c4b3a2918",
      "kind": "image",
      "poster": null,
      "ai": "without"
    }
  ],
  "poll": {
    "options": [
      {
        "text": "Lavender",
        "votes": 12
      },
      {
        "text": "Sunflowers",
        "votes": 7
      },
      {
        "text": "Clover",
        "votes": 3
      }
    ],
    "total": 22,
    "multiple": false,
    "endsAt": null,
    "running": true,
    "resultsVisible": true,
    "myVotes": [
      0
    ]
  },
  "quotes": null,
  "continues": null,
  "counts": {
    "replies": 4,
    "likes": 31,
    "reposts": 2
  },
  "pinned": false,
  "giftDrop": {
    "item": "plan",
    "quantity": 3,
    "places": 10,
    "left": 4,
    "audience": "followers",
    "newAccounts": false,
    "status": "open",
    "claimed": true
  },
  "createdAt": 1758624000000
}

可能的状态： 200304400401404429

POST`/v2/posts`

发布帖子。

权限 write
自 v2.0

帖子需要文字或投票。长度、投票选项和频率由本站设定；超出时会收到 400 或 429。

用 media 附加图片、一个 GIF 或一个视频。GIF 或视频只能单独使用。你可以在 tellmelo 上使用其他成员分享的 GIF 和视频。

仅密友可见或带共同作者的帖子会立即发布，不能发在群组里，也不能定时。两者不能同时使用。

参数

名称	类型	含义
`text`在正文中	`string`可选	帖子、回复或私信的文字。
`community`在正文中	`string`可选	帖子要发到其动态频道的群组 `id`；该频道必须开启，且你需要相应权限。不传时，帖子不属于任何群组。
`quotes`在正文中	`string`可选	本帖引用的帖子的 `id`。
`poll`在正文中	`string[]`可选	选项，以文本列表形式。
`media`在正文中	`string[]`可选	在 App 中上传的图片的 ID，或媒体库中某个 GIF 或视频的 ID（自 2.14 起）。
`audience`在正文中	`string`可选	谁能看到帖子：`everyone` 所有可以看的人，`close` 只有你的密友。`everyoneclose`
`coauthor`在正文中	`string`可选	你邀请为共同作者的账号的 `id`。你们需要互相关注。

请求示例

curl -X POST \
  -H "Authorization: Bearer tm_key_…" \
  -H "Content-Type: application/json" \
  -d '{"text":"The bees are back in the garden 🐝 #garden","audience":"everyone"}' \
  "https://api.tellmelo.com/v2/posts"

响应

返回一个 Created。

示例

{
  "id": "5f0c2a9e-8d41-4b7a-9c3e-2e61d0f4a7b1",
  "scheduledFor": null,
  "deleteAt": null
}

可能的状态： 200400401403429

DELETE`/v2/posts/{id}`

删除你自己的一条帖子。

权限 write
自 v2.0

参数

名称	类型	含义
`id`在路径中	`string`必填	帖子的 `id`。

请求示例

curl -X DELETE \
  -H "Authorization: Bearer tm_key_…" \
  "https://api.tellmelo.com/v2/posts/5f0c2a9e-8d41-4b7a-9c3e-2e61d0f4a7b1"

响应

返回一个 Ok。

示例

{
  "ok": true
}

可能的状态： 200400401403404429

GET`/v2/me/scheduled`

你还没发布的帖子，以及它们在等什么。

权限 read
带 ETag
自 v2.12

请求示例

curl \
  -H "Authorization: Bearer tm_key_…" \
  "https://api.tellmelo.com/v2/me/scheduled"

响应

返回一页 ScheduledPost，形式为 `items` 和 `next`。

示例

{
  "items": [
    {
      "id": "5f0c2a9e-8d41-4b7a-9c3e-2e61d0f4a7b1",
      "text": "Market day tomorrow – see you at the bee stand! #garden",
      "communityId": null,
      "publishAt": 1758710400000,
      "deleteAt": null,
      "waitingFor": "time",
      "createdAt": 1758624000000
    }
  ],
  "next": null
}

可能的状态： 200304401429

POST`/v2/posts/{id}/schedule`

修改定时帖子的发布时间，或帖子自动删除的时间。

权限 write
自 v2.12

仅限你自己的帖子。帖子的礼物未付款前，无法设置定时。

参数

名称	类型	含义
`id`在路径中	`string`必填	帖子的 `id`。
`publishAt`在正文中	`integer`可选	定时帖子的发布时间，以自 1970 年起的毫秒数表示。
`deleteAt`在正文中	`integer`可选	帖子自动删除的时间，以自 1970 年起的毫秒数表示。

请求示例

curl -X POST \
  -H "Authorization: Bearer tm_key_…" \
  "https://api.tellmelo.com/v2/posts/5f0c2a9e-8d41-4b7a-9c3e-2e61d0f4a7b1/schedule"

响应

返回一个 Ok。

示例

{
  "ok": true
}

可能的状态： 200400401403404429

POST`/v2/posts/{id}/edit`

修改你某条帖子的文字。

权限 write
自 v2.12

仅在你的套餐允许的编辑时间内。定时帖子不能编辑。

参数

名称	类型	含义
`id`在路径中	`string`必填	帖子的 `id`。
`text`在正文中	`string`必填	帖子、回复或私信的文字。

请求示例

curl -X POST \
  -H "Authorization: Bearer tm_key_…" \
  -H "Content-Type: application/json" \
  -d '{"text":"The bees are back in the garden 🐝🌻 #garden"}' \
  "https://api.tellmelo.com/v2/posts/5f0c2a9e-8d41-4b7a-9c3e-2e61d0f4a7b1/edit"

响应

返回一个 Ok。

示例

{
  "ok": true
}

可能的状态： 200400401403404429

GET`/v2/posts/{id}/reply-settings`

谁可以回复你的帖子、回复是否需要批准，以及慢速模式。

权限 read
带 ETag
自 v2.19

参数

名称	类型	含义
`id`在路径中	`string`必填	帖子的 `id`。

请求示例

curl \
  -H "Authorization: Bearer tm_key_…" \
  "https://api.tellmelo.com/v2/posts/5f0c2a9e-8d41-4b7a-9c3e-2e61d0f4a7b1/reply-settings"

响应

返回一个 ReplySettings。

示例

{
  "audience": "following",
  "approval": false,
  "slow": "auto"
}

可能的状态： 200304400401404429

PUT`/v2/posts/{id}/reply-settings`

修改你帖子的回复设置。未提供的项目保持不变。

权限 write
自 v2.19

仅限你自己的帖子。

参数

名称	类型	含义
`id`在路径中	`string`必填	帖子的 `id`。
`audience`在正文中	`string`可选	谁可以回复：所有人、你关注的账号、被提及的人或没有人。`allfollowingmentionednobody`
`approval`在正文中	`boolean`可选	回复是否要等你批准后才显示。
`slow`在正文中	`string`可选	慢速模式：`auto` 在回复很多时自动开启，`on` 始终开启，`off` 从不开启。`autoonoff`

请求示例

curl -X PUT \
  -H "Authorization: Bearer tm_key_…" \
  -H "Content-Type: application/json" \
  -d '{"audience":"following","approval":false,"slow":"auto"}' \
  "https://api.tellmelo.com/v2/posts/5f0c2a9e-8d41-4b7a-9c3e-2e61d0f4a7b1/reply-settings"

响应

返回一个 ReplySettings。

示例

{
  "audience": "following",
  "approval": false,
  "slow": "auto"
}

可能的状态： 200400401403404429

POST`/v2/posts/{id}/coauthor`

接受或拒绝共同作者邀请。

权限 write
自 v2.19

参数

名称	类型	含义
`id`在路径中	`string`必填	帖子的 `id`。
`accept`在正文中	`boolean`必填	`true` 接受邀请，`false` 拒绝。

请求示例

curl -X POST \
  -H "Authorization: Bearer tm_key_…" \
  -H "Content-Type: application/json" \
  -d '{"accept":true}' \
  "https://api.tellmelo.com/v2/posts/5f0c2a9e-8d41-4b7a-9c3e-2e61d0f4a7b1/coauthor"

响应

返回一个 Ok。

示例

{
  "ok": true
}

可能的状态： 200400401403404429

DELETE`/v2/posts/{id}/coauthor`

退出共同作者，或作为作者把共同作者从帖子中移除。

权限 write
自 v2.19

适用于共同作者和帖子作者。

参数

名称	类型	含义
`id`在路径中	`string`必填	帖子的 `id`。

请求示例

curl -X DELETE \
  -H "Authorization: Bearer tm_key_…" \
  "https://api.tellmelo.com/v2/posts/5f0c2a9e-8d41-4b7a-9c3e-2e61d0f4a7b1/coauthor"

响应

返回一个 Ok。

示例

{
  "ok": true
}

可能的状态： 200400401403404429

POST`/v2/posts/{id}/pin`

把你的帖子置顶到主页，或取消置顶。

权限 write
自 v2.19

仅限你自己可见的帖子。能置顶几条取决于你的套餐。

参数

名称	类型	含义
`id`在路径中	`string`必填	帖子的 `id`。
`active`在正文中	`boolean`必填	`true` 置顶帖子，`false` 取消置顶。

请求示例

curl -X POST \
  -H "Authorization: Bearer tm_key_…" \
  -H "Content-Type: application/json" \
  -d '{"active":true}' \
  "https://api.tellmelo.com/v2/posts/5f0c2a9e-8d41-4b7a-9c3e-2e61d0f4a7b1/pin"

响应

返回一个 Ok。

示例

{
  "ok": true
}

可能的状态： 200400401403404429

帖子下的回复，以带 parentId 的列表形式。

GET`/v2/posts/{id}/replies`

帖子的回复，不含已屏蔽的账号。

权限 read
可分页
带 ETag
自 v2.0

列表是扁平的，按写作顺序排列；parentId 可将其组成树。一页总是包含完整的讨论串。已屏蔽账号的回复不包含在内。

参数

名称	类型	含义
`id`在路径中	`string`必填	帖子的 `id`。
`limit`在查询中	`integer`可选	每页条目数：默认 20，最多 50。
`cursor`在查询中	`string`可选	上一个响应中的 `next`。不传则从头开始。

请求示例

curl \
  -H "Authorization: Bearer tm_key_…" \
  "https://api.tellmelo.com/v2/posts/5f0c2a9e-8d41-4b7a-9c3e-2e61d0f4a7b1/replies?limit=20"

响应

返回一页 Reply，形式为 `items` 和 `next`。

示例

{
  "items": [
    {
      "id": "9e4b1c7d-2a3f-4d5e-8b6c-0f1e2d3c4b5a",
      "text": "Same here, the lavender is full of them.",
      "kind": "post",
      "author": {
        "id": "d4c3b2a1-6e5f-4a7b-9c8d-1e2f3a4b5c6d",
        "handle": "jon",
        "name": "Jon",
        "verified": false,
        "accountKind": "person"
      },
      "community": null,
      "media": [],
      "poll": null,
      "quotes": null,
      "continues": null,
      "counts": {
        "replies": 0,
        "likes": 3,
        "reposts": 0
      },
      "pinned": false,
      "giftDrop": null,
      "createdAt": 1758624600000,
      "postId": "5f0c2a9e-8d41-4b7a-9c3e-2e61d0f4a7b1",
      "parentId": null
    }
  ],
  "next": "MTc1ODYyNDAwMDAwMDo1ZjBjMmE5ZS04ZDQx"
}

可能的状态： 200304400401404429

POST`/v2/posts/{id}/replies`

回复帖子。

权限 write
自 v2.0

慢速模式下，每人每 10 分钟可回复一次，否则返回 429。作者及其关注的账号不受限制。

通过 media 最多附加一张图片、一个 GIF 或一个视频。

参数

名称	类型	含义
`id`在路径中	`string`必填	帖子的 `id`。
`text`在正文中	`string`必填	帖子、回复或私信的文字。
`parentId`在正文中	`string`可选	本回复所回复的回复的 `id`。不传则直接回复帖子。
`media`在正文中	`string[]`可选	在 App 中上传的图片的 ID，或媒体库中某个 GIF 或视频的 ID（自 2.14 起）。
`publishAt`在正文中	`integer`可选	回复发布的时间，以 1970 年起的毫秒数表示。不填则立即发布。

请求示例

curl -X POST \
  -H "Authorization: Bearer tm_key_…" \
  -H "Content-Type: application/json" \
  -d '{"text":"Same here, the lavender is full of them."}' \
  "https://api.tellmelo.com/v2/posts/5f0c2a9e-8d41-4b7a-9c3e-2e61d0f4a7b1/replies"

响应

返回一个 Created。

示例

{
  "id": "5f0c2a9e-8d41-4b7a-9c3e-2e61d0f4a7b1",
  "scheduledFor": null,
  "deleteAt": null
}

可能的状态： 200400401403404429

POST`/v2/replies/{id}/edit`

修改你某条回复的文字。

权限 write
自 v2.12

参数

名称	类型	含义
`id`在路径中	`string`必填	回复的 id。
`text`在正文中	`string`必填	帖子、回复或私信的文字。

请求示例

curl -X POST \
  -H "Authorization: Bearer tm_key_…" \
  -H "Content-Type: application/json" \
  -d '{"text":"Same here, the lavender and the clover are full of them."}' \
  "https://api.tellmelo.com/v2/replies/9e4b1c7d-2a3f-4d5e-8b6c-0f1e2d3c4b5a/edit"

响应

返回一个 Ok。

示例

{
  "ok": true
}

可能的状态： 200400401403404429

DELETE`/v2/replies/{id}`

删除你的某条回复。

权限 write
自 v2.12

参数

名称	类型	含义
`id`在路径中	`string`必填	回复的 id。

请求示例

curl -X DELETE \
  -H "Authorization: Bearer tm_key_…" \
  "https://api.tellmelo.com/v2/replies/9e4b1c7d-2a3f-4d5e-8b6c-0f1e2d3c4b5a"

响应

返回一个 Ok。

示例

{
  "ok": true
}

可能的状态： 200400401403404429

POST`/v2/replies/{id}/like`

赞成一条回复（自回复改为投票后，点赞即赞成），或撤回赞成；反对票保留。

权限 write
自 v2.12
已弃用

自 2.19 起已弃用：请使用 POST /replies/{id}/vote。此路由暂时保留。

参数

名称	类型	含义
`id`在路径中	`string`必填	回复的 id。
`active`在正文中	`boolean`必填	`true` 建立关系，`false` 解除关系。

请求示例

curl -X POST \
  -H "Authorization: Bearer tm_key_…" \
  -H "Content-Type: application/json" \
  -d '{"active":true}' \
  "https://api.tellmelo.com/v2/replies/9e4b1c7d-2a3f-4d5e-8b6c-0f1e2d3c4b5a/like"

响应

返回一个 Ok。

示例

{
  "ok": true
}

可能的状态： 200400401403404429

POST`/v2/replies/{id}/vote`

给一条回复投赞成票或反对票，或撤回你的投票。返回你的投票和投票后的得分。

权限 write
自 v2.19

参数

名称	类型	含义
`id`在路径中	`string`必填	回复的 id。
`vote`在正文中	`string`必填	`up` 赞成，`down` 反对，`none` 撤回你的投票。`updownnone`

请求示例

curl -X POST \
  -H "Authorization: Bearer tm_key_…" \
  -H "Content-Type: application/json" \
  -d '{"vote":"up"}' \
  "https://api.tellmelo.com/v2/replies/9e4b1c7d-2a3f-4d5e-8b6c-0f1e2d3c4b5a/vote"

响应

返回一个 ReplyVote。

示例

{
  "vote": "up",
  "score": 12
}

可能的状态： 200400401403404429

POST`/v2/replies/{id}/pick`

把你帖子下的一条回复标为最佳，或取消标记。

权限 write
自 v2.19

只能在你自己的帖子下，且只能是直接回复帖子的回复。新的标记会替换旧的。

参数

名称	类型	含义
`id`在路径中	`string`必填	回复的 id。
`active`在正文中	`boolean`必填	`true` 标为最佳，`false` 取消标记。

请求示例

curl -X POST \
  -H "Authorization: Bearer tm_key_…" \
  -H "Content-Type: application/json" \
  -d '{"active":true}' \
  "https://api.tellmelo.com/v2/replies/9e4b1c7d-2a3f-4d5e-8b6c-0f1e2d3c4b5a/pick"

响应

返回一个 Ok。

示例

{
  "ok": true
}

可能的状态： 200400401403404429

GET`/v2/posts/{id}/replies/waiting`

帖子下等待批准的回复：你自己的帖子下是全部，否则只有你自己的。

权限 read
带 ETag
自 v2.19

回复是否需要等待，由作者在回复设置中决定。

参数

名称	类型	含义
`id`在路径中	`string`必填	帖子的 `id`。

请求示例

curl \
  -H "Authorization: Bearer tm_key_…" \
  "https://api.tellmelo.com/v2/posts/5f0c2a9e-8d41-4b7a-9c3e-2e61d0f4a7b1/replies/waiting"

响应

返回一页 Reply，形式为 `items` 和 `next`。

示例

{
  "items": [
    {
      "id": "9e4b1c7d-2a3f-4d5e-8b6c-0f1e2d3c4b5a",
      "text": "Same here, the lavender is full of them.",
      "kind": "post",
      "author": {
        "id": "d4c3b2a1-6e5f-4a7b-9c8d-1e2f3a4b5c6d",
        "handle": "jon",
        "name": "Jon",
        "verified": false,
        "accountKind": "person"
      },
      "community": null,
      "media": [],
      "poll": null,
      "quotes": null,
      "continues": null,
      "counts": {
        "replies": 0,
        "likes": 3,
        "reposts": 0
      },
      "pinned": false,
      "giftDrop": null,
      "createdAt": 1758624600000,
      "postId": "5f0c2a9e-8d41-4b7a-9c3e-2e61d0f4a7b1",
      "parentId": null
    }
  ],
  "next": null
}

可能的状态： 200304400401404429

POST`/v2/replies/{id}/decide`

批准或拒绝你帖子下一条等待中的回复。被拒绝的回复会被删除。

权限 write
自 v2.19

参数

名称	类型	含义
`id`在路径中	`string`必填	回复的 id。
`approve`在正文中	`boolean`必填	`true` 批准回复，`false` 拒绝。

请求示例

curl -X POST \
  -H "Authorization: Bearer tm_key_…" \
  -H "Content-Type: application/json" \
  -d '{"approve":true}' \
  "https://api.tellmelo.com/v2/replies/9e4b1c7d-2a3f-4d5e-8b6c-0f1e2d3c4b5a/decide"

响应

返回一个 Ok。

示例

{
  "ok": true
}

可能的状态： 200400401403404429

GET`/v2/posts/{id}/replies/planned`

你在某个帖子下定时稍后发布的回复。

权限 read
带 ETag
自 v2.19

回复时用 publishAt 定时。同时最多 20 条定时回复。

参数

名称	类型	含义
`id`在路径中	`string`必填	帖子的 `id`。

请求示例

curl \
  -H "Authorization: Bearer tm_key_…" \
  "https://api.tellmelo.com/v2/posts/5f0c2a9e-8d41-4b7a-9c3e-2e61d0f4a7b1/replies/planned"

响应

返回一页 PlannedReply，形式为 `items` 和 `next`。

示例

{
  "items": [
    {
      "id": "3b2a1c0d-9e8f-4a7b-b6c5-d4e3f2a1b0c9",
      "parentId": null,
      "text": "Count me in for Saturday!",
      "publishAt": 1758710400000,
      "state": "waiting"
    }
  ],
  "next": null
}

可能的状态： 200304400401404429

PUT`/v2/me/planned-replies/{id}`

修改定时回复的文字或时间。发送失败的回复会重新等待。

权限 write
自 v2.19

参数

名称	类型	含义
`id`在路径中	`string`必填	定时回复的 `id`。
`text`在正文中	`string`可选	帖子、回复或私信的文字。
`publishAt`在正文中	`integer`可选	回复发布的时间，以 1970 年起的毫秒数表示。不填则立即发布。

请求示例

curl -X PUT \
  -H "Authorization: Bearer tm_key_…" \
  -H "Content-Type: application/json" \
  -d '{"text":"See you there!","publishAt":1758700000000}' \
  "https://api.tellmelo.com/v2/me/planned-replies/3b2a1c0d-9e8f-4a7b-b6c5-d4e3f2a1b0c9"

响应

返回一个 Ok。

示例

{
  "ok": true
}

可能的状态： 200400401403404429

POST`/v2/me/planned-replies/{id}/send`

立即发送一条定时回复。

权限 write
自 v2.19

参数

名称	类型	含义
`id`在路径中	`string`必填	定时回复的 `id`。

请求示例

curl -X POST \
  -H "Authorization: Bearer tm_key_…" \
  "https://api.tellmelo.com/v2/me/planned-replies/3b2a1c0d-9e8f-4a7b-b6c5-d4e3f2a1b0c9/send"

响应

返回一个 Ok。

示例

{
  "ok": true
}

可能的状态： 200400401403404429

DELETE`/v2/me/planned-replies/{id}`

删除一条定时回复。

权限 write
自 v2.19

参数

名称	类型	含义
`id`在路径中	`string`必填	定时回复的 `id`。

请求示例

curl -X DELETE \
  -H "Authorization: Bearer tm_key_…" \
  "https://api.tellmelo.com/v2/me/planned-replies/3b2a1c0d-9e8f-4a7b-b6c5-d4e3f2a1b0c9"

响应

返回一个 Ok。

示例

{
  "ok": true
}

可能的状态： 200400401403404429

投票

投票是设置了 poll 的帖子。投票操作有单独的路径。

POST`/v2/posts/{id}/vote`

参与投票。

权限 write
自 v2.0

在你投票或投票结束之前，各选项的票数为 null。total 始终存在。

参数

名称	类型	含义
`id`在路径中	`string`必填	帖子的 `id`。
`option`在正文中	`integer`必填	哪个选项，从 0 开始计数。多选时每个选项调用一次。
`retract`在正文中	`boolean`可选	`true` 撤回投票。

请求示例

curl -X POST \
  -H "Authorization: Bearer tm_key_…" \
  -H "Content-Type: application/json" \
  -d '{"option":0}' \
  "https://api.tellmelo.com/v2/posts/5f0c2a9e-8d41-4b7a-9c3e-2e61d0f4a7b1/vote"

响应

返回一个 Ok。

示例

{
  "ok": true
}

可能的状态： 200400401403404429

个人主页

按短名称获取公开个人主页及其发布的内容。

GET`/v2/profiles/{handle}`

按短名称获取个人主页。

权限 read
带 ETag
自 v2.0

参数

名称	类型	含义
`handle`在路径中	`string`必填	个人主页的短名称，不区分大小写。

请求示例

curl \
  -H "Authorization: Bearer tm_key_…" \
  "https://api.tellmelo.com/v2/profiles/mara"

响应

返回一个 Profile。

示例

{
  "id": "a3e1f7c2-54b9-4d0e-8f16-7b2c9d4e1a05",
  "handle": "mara",
  "name": "Mara 🌻",
  "verified": true,
  "accountKind": "person",
  "about": "Beekeeper, allotment, too many seeds. :tellmelo:",
  "website": "https://mara-imkerei.example/",
  "websiteVerified": true,
  "followers": 148,
  "createdAt": 1750848000000
}

可能的状态： 200304400401404429

GET`/v2/profiles/{handle}/posts`

某个个人主页的公开帖子，最新的在前。

权限 read
可分页
带 ETag
自 v2.0

在公开路径上，counts.likes 和 counts.reposts 始终为 0，pinned 为 false。

群组中的帖子不在这里，而在 /communities/{id}/posts。

参数

名称	类型	含义
`handle`在路径中	`string`必填	个人主页的短名称，不区分大小写。
`limit`在查询中	`integer`可选	每页条目数：默认 20，最多 50。
`cursor`在查询中	`string`可选	上一个响应中的 `next`。不传则从头开始。

请求示例

curl \
  -H "Authorization: Bearer tm_key_…" \
  "https://api.tellmelo.com/v2/profiles/mara/posts?limit=20"

响应

返回一页 Post，形式为 `items` 和 `next`。

示例

{
  "items": [
    {
      "id": "5f0c2a9e-8d41-4b7a-9c3e-2e61d0f4a7b1",
      "text": "The bees are back in the garden 🐝 #garden",
      "kind": "poll",
      "author": {
        "id": "a3e1f7c2-54b9-4d0e-8f16-7b2c9d4e1a05",
        "handle": "mara",
        "name": "Mara 🌻",
        "verified": true,
        "accountKind": "person"
      },
      "community": {
        "id": "c81d4e2a-0f3b-4a6c-9e57-1d2b3c4a5f60",
        "name": "Urban Gardening"
      },
      "media": [
        {
          "url": "/api/media?id=b2d7e9f1-3c4a-4e8b-a1f0-6d5c4b3a2918",
          "kind": "image",
          "poster": null,
          "ai": "without"
        }
      ],
      "poll": {
        "options": [
          {
            "text": "Lavender",
            "votes": 12
          },
          {
            "text": "Sunflowers",
            "votes": 7
          },
          {
            "text": "Clover",
            "votes": 3
          }
        ],
        "total": 22,
        "multiple": false,
        "endsAt": null,
        "running": true,
        "resultsVisible": true,
        "myVotes": [
          0
        ]
      },
      "quotes": null,
      "continues": null,
      "counts": {
        "replies": 4,
        "likes": 31,
        "reposts": 2
      },
      "pinned": false,
      "giftDrop": {
        "item": "plan",
        "quantity": 3,
        "places": 10,
        "left": 4,
        "audience": "followers",
        "newAccounts": false,
        "status": "open",
        "claimed": true
      },
      "createdAt": 1758624000000
    }
  ],
  "next": "MTc1ODYyNDAwMDAwMDo1ZjBjMmE5ZS04ZDQx"
}

可能的状态： 200304400401404429

GET`/v2/profiles/{handle}/events`

某个主页即将举行的活动，最近的在前。

权限 read
带 ETag
自 v2.19

仅在该主页的套餐包含活动时。互相屏蔽的账号之间不显示任何内容。

参数

名称	类型	含义
`handle`在路径中	`string`必填	个人主页的短名称，不区分大小写。

请求示例

curl \
  -H "Authorization: Bearer tm_key_…" \
  "https://api.tellmelo.com/v2/profiles/mara/events"

响应

返回一页 Event，形式为 `items` 和 `next`。

示例

{
  "items": [
    {
      "id": "2a3b4c5d-6e7f-4809-9a1b-2c3d4e5f6a7b",
      "title": "Seed swap",
      "startsAt": 1758883200000,
      "endsAt": 1758890400000,
      "place": "Community garden",
      "description": "Bring seeds, take seeds.",
      "signups": {
        "count": 14,
        "going": true
      }
    }
  ],
  "next": null
}

可能的状态： 200304400401404429

POST`/v2/me/events`

创建活动。返回它的 id。

权限 write
自 v2.19

需要包含活动的套餐，否则返回 403。能有多少个即将举行的活动取决于套餐。

参数

名称	类型	含义
`title`在正文中	`string`必填	标题。
`startsAt`在正文中	`integer`必填	开始时间，以 1970 年起的毫秒数表示。
`endsAt`在正文中	`integer`可选	结束时间，以 1970 年起的毫秒数表示。可选。
`place`在正文中	`string`可选	举办地点。
`description`在正文中	`string`可选	描述。
`signups`在正文中	`boolean`可选	是否可以报名。需要包含报名功能的套餐。
`capacity`在正文中	`integer`可选	最多可报名人数。不填则不限。

请求示例

curl -X POST \
  -H "Authorization: Bearer tm_key_…" \
  -H "Content-Type: application/json" \
  -d '{"title":"Seed swap","startsAt":1758700000000,"place":"Community garden","signups":true,"capacity":30}' \
  "https://api.tellmelo.com/v2/me/events"

响应

返回一个 Made。

示例

{
  "id": "0d9c8b7a-6f5e-4d3c-2b1a-0f9e8d7c6b5a"
}

可能的状态： 200400401403429

PUT`/v2/me/events/{id}`

修改你的活动。所有字段都会重新设置。

权限 write
自 v2.19

已开始的活动保留其开始时间。

参数

名称	类型	含义
`id`在路径中	`string`必填	活动的 `id`。
`title`在正文中	`string`必填	标题。
`startsAt`在正文中	`integer`必填	开始时间，以 1970 年起的毫秒数表示。
`endsAt`在正文中	`integer`可选	结束时间，以 1970 年起的毫秒数表示。可选。
`place`在正文中	`string`可选	举办地点。
`description`在正文中	`string`可选	描述。
`signups`在正文中	`boolean`可选	是否可以报名。需要包含报名功能的套餐。
`capacity`在正文中	`integer`可选	最多可报名人数。不填则不限。

请求示例

curl -X PUT \
  -H "Authorization: Bearer tm_key_…" \
  -H "Content-Type: application/json" \
  -d '{"title":"Seed swap","startsAt":1758700000000,"place":"Community garden","signups":true,"capacity":30}' \
  "https://api.tellmelo.com/v2/me/events/2a3b4c5d-6e7f-4809-9a1b-2c3d4e5f6a7b"

响应

返回一个 Made。

示例

{
  "id": "0d9c8b7a-6f5e-4d3c-2b1a-0f9e8d7c6b5a"
}

可能的状态： 200400401403404429

DELETE`/v2/me/events/{id}`

删除你的活动。

权限 write
自 v2.19

参数

名称	类型	含义
`id`在路径中	`string`必填	活动的 `id`。

请求示例

curl -X DELETE \
  -H "Authorization: Bearer tm_key_…" \
  "https://api.tellmelo.com/v2/me/events/2a3b4c5d-6e7f-4809-9a1b-2c3d4e5f6a7b"

响应

返回一个 Ok。

示例

{
  "ok": true
}

可能的状态： 200400401403404429

GET`/v2/me/events/{id}/signups`

谁报名了你的活动。

权限 read
带 ETag
自 v2.19

参数

名称	类型	含义
`id`在路径中	`string`必填	活动的 `id`。

请求示例

curl \
  -H "Authorization: Bearer tm_key_…" \
  "https://api.tellmelo.com/v2/me/events/2a3b4c5d-6e7f-4809-9a1b-2c3d4e5f6a7b/signups"

响应

返回一页 EventSignup，形式为 `items` 和 `next`。

示例

{
  "items": [
    {
      "id": "a3e1f7c2-54b9-4d0e-8f16-7b2c9d4e1a05",
      "handle": "mara",
      "name": "Mara 🌻",
      "at": 1758624000000
    }
  ],
  "next": null
}

可能的状态： 200304400401404429

POST`/v2/events/{id}/signup`

报名参加活动或取消报名。

权限 write
自 v2.19

仅限可报名的活动，且不能是你自己的。满员时返回 409。

参数

名称	类型	含义
`id`在路径中	`string`必填	活动的 `id`。
`going`在正文中	`boolean`必填	`true` 报名，`false` 取消报名。

请求示例

curl -X POST \
  -H "Authorization: Bearer tm_key_…" \
  -H "Content-Type: application/json" \
  -d '{"going":true}' \
  "https://api.tellmelo.com/v2/events/2a3b4c5d-6e7f-4809-9a1b-2c3d4e5f6a7b/signup"

响应

返回一个 Ok。

示例

{
  "ok": true
}

可能的状态： 200400401403404429

群组

公开群组和你自己的群组，以及它们的帖子、成员、角色和邀请链接。

GET`/v2/communities`

本实例的公开群组；使用 mine=true 时为你账号所在的群组。

权限 read
带 ETag
自 v2.0

按成员数排序，不分页；next 始终为 null。

参数

名称	类型	含义
`limit`在查询中	`integer`可选	每页条目数：默认 20，最多 50。
`mine`在查询中	`boolean`可选	设为 `true` 时返回你账号所在的群组，包括内部和隐藏群组，按名称排序。

请求示例

curl \
  -H "Authorization: Bearer tm_key_…" \
  "https://api.tellmelo.com/v2/communities?limit=20"

响应

返回一页 Community，形式为 `items` 和 `next`。

示例

{
  "items": [
    {
      "id": "c81d4e2a-0f3b-4a6c-9e57-1d2b3c4a5f60",
      "name": "Urban Gardening",
      "handle": "urbangardening",
      "description": "Balconies, allotments, rooftops: whatever grows.",
      "tags": [
        "garden",
        "bees"
      ],
      "members": 312,
      "joinPolicy": "open",
      "visibility": "open",
      "feedChannel": true,
      "sparks": 24,
      "perks": [
        "tint",
        "welcome"
      ],
      "membership": {
        "leader": null,
        "roles": [
          "4e5f6a7b-8c9d-4e0f-a1b2-c3d4e5f6a7b8"
        ],
        "permissions": [
          "attach",
          "invite",
          "send",
          "view"
        ],
        "mutedUntil": null
      }
    }
  ],
  "next": null
}

可能的状态： 200304401429

GET`/v2/communities/{id}`

按 id 获取单个群组。

权限 read
带 ETag
自 v2.0

内部和隐藏群组仅在你的账号是成员时可见。

参数

名称	类型	含义
`id`在路径中	`string`必填	群组的 `id`。

请求示例

curl \
  -H "Authorization: Bearer tm_key_…" \
  "https://api.tellmelo.com/v2/communities/c81d4e2a-0f3b-4a6c-9e57-1d2b3c4a5f60"

响应

返回一个 Community。

示例

{
  "id": "c81d4e2a-0f3b-4a6c-9e57-1d2b3c4a5f60",
  "name": "Urban Gardening",
  "handle": "urbangardening",
  "description": "Balconies, allotments, rooftops: whatever grows.",
  "tags": [
    "garden",
    "bees"
  ],
  "members": 312,
  "joinPolicy": "open",
  "visibility": "open",
  "feedChannel": true,
  "sparks": 24,
  "perks": [
    "tint",
    "welcome"
  ],
  "membership": {
    "leader": null,
    "roles": [
      "4e5f6a7b-8c9d-4e0f-a1b2-c3d4e5f6a7b8"
    ],
    "permissions": [
      "attach",
      "invite",
      "send",
      "view"
    ],
    "mutedUntil": null
  }
}

可能的状态： 200304400401404429

GET`/v2/communities/{id}/posts`

群组动态频道中的帖子，最新的在前。

权限 read
可分页
带 ETag
自 v2.0

在公开路径上，counts.likes 和 counts.reposts 始终为 0，pinned 为 false。

动态频道关闭时，该路径返回 409 和 feed_off。

参数

名称	类型	含义
`id`在路径中	`string`必填	群组的 `id`。
`limit`在查询中	`integer`可选	每页条目数：默认 20，最多 50。
`cursor`在查询中	`string`可选	上一个响应中的 `next`。不传则从头开始。

请求示例

curl \
  -H "Authorization: Bearer tm_key_…" \
  "https://api.tellmelo.com/v2/communities/c81d4e2a-0f3b-4a6c-9e57-1d2b3c4a5f60/posts?limit=20"

响应

返回一页 Post，形式为 `items` 和 `next`。

示例

{
  "items": [
    {
      "id": "5f0c2a9e-8d41-4b7a-9c3e-2e61d0f4a7b1",
      "text": "The bees are back in the garden 🐝 #garden",
      "kind": "poll",
      "author": {
        "id": "a3e1f7c2-54b9-4d0e-8f16-7b2c9d4e1a05",
        "handle": "mara",
        "name": "Mara 🌻",
        "verified": true,
        "accountKind": "person"
      },
      "community": {
        "id": "c81d4e2a-0f3b-4a6c-9e57-1d2b3c4a5f60",
        "name": "Urban Gardening"
      },
      "media": [
        {
          "url": "/api/media?id=b2d7e9f1-3c4a-4e8b-a1f0-6d5c4b3a2918",
          "kind": "image",
          "poster": null,
          "ai": "without"
        }
      ],
      "poll": {
        "options": [
          {
            "text": "Lavender",
            "votes": 12
          },
          {
            "text": "Sunflowers",
            "votes": 7
          },
          {
            "text": "Clover",
            "votes": 3
          }
        ],
        "total": 22,
        "multiple": false,
        "endsAt": null,
        "running": true,
        "resultsVisible": true,
        "myVotes": [
          0
        ]
      },
      "quotes": null,
      "continues": null,
      "counts": {
        "replies": 4,
        "likes": 31,
        "reposts": 2
      },
      "pinned": false,
      "giftDrop": {
        "item": "plan",
        "quantity": 3,
        "places": 10,
        "left": 4,
        "audience": "followers",
        "newAccounts": false,
        "status": "open",
        "claimed": true
      },
      "createdAt": 1758624000000
    }
  ],
  "next": "MTc1ODYyNDAwMDAwMDo1ZjBjMmE5ZS04ZDQx"
}

可能的状态： 200304400401404429

GET`/v2/communities/{id}/members`

群组成员及其角色。

权限 read
带 ETag
自 v2.15

管理层在前，其余按最高角色排序；最多 300 人。

参数

名称	类型	含义
`id`在路径中	`string`必填	群组的 `id`。

请求示例

curl \
  -H "Authorization: Bearer tm_key_…" \
  "https://api.tellmelo.com/v2/communities/c81d4e2a-0f3b-4a6c-9e57-1d2b3c4a5f60/members"

响应

返回一页 GroupMember，形式为 `items` 和 `next`。

示例

{
  "items": [
    {
      "id": "d4c3b2a1-6e5f-4a7b-9c8d-1e2f3a4b5c6d",
      "handle": "jon",
      "name": "Jon",
      "bot": false,
      "leader": null,
      "roles": [
        "4e5f6a7b-8c9d-4e0f-a1b2-c3d4e5f6a7b8"
      ],
      "mutedUntil": null
    }
  ],
  "next": null
}

可能的状态： 200304400401404429

GET`/v2/communities/{id}/roles`

群组的角色，最高的在前，@everyone 在最后。

权限 read
带 ETag
自 v2.15

参数

名称	类型	含义
`id`在路径中	`string`必填	群组的 `id`。

请求示例

curl \
  -H "Authorization: Bearer tm_key_…" \
  "https://api.tellmelo.com/v2/communities/c81d4e2a-0f3b-4a6c-9e57-1d2b3c4a5f60/roles"

响应

返回一页 Role，形式为 `items` 和 `next`。

示例

{
  "items": [
    {
      "id": "4e5f6a7b-8c9d-4e0f-a1b2-c3d4e5f6a7b8",
      "name": "Gardeners",
      "everyone": false,
      "color": "green",
      "permissions": [
        "attach",
        "invite",
        "send",
        "view"
      ],
      "members": 24,
      "editable": true,
      "selfable": false
    }
  ],
  "next": null
}

可能的状态： 200304400401404429

GET`/v2/communities/{id}/bell`

群组会向你发送哪些通知。

权限 read
带 ETag
自 v2.15

参数

名称	类型	含义
`id`在路径中	`string`必填	群组的 `id`。

请求示例

curl \
  -H "Authorization: Bearer tm_key_…" \
  "https://api.tellmelo.com/v2/communities/c81d4e2a-0f3b-4a6c-9e57-1d2b3c4a5f60/bell"

响应

返回一个 Bell。

示例

{
  "level": "important"
}

可能的状态： 200304400401404429

GET`/v2/invites/{code}`

加入前查看邀请链接背后的群组。

权限 read
带 ETag
自 v2.15

参数

名称	类型	含义
`code`在路径中	`string`必填	邀请链接的代码，即其地址的末尾部分。

请求示例

curl \
  -H "Authorization: Bearer tm_key_…" \
  "https://api.tellmelo.com/v2/invites/k7Qm2xPa"

响应

返回一个 InvitePreview。

示例

{
  "community": {
    "id": "c81d4e2a-0f3b-4a6c-9e57-1d2b3c4a5f60",
    "name": "Urban Gardening",
    "members": 312,
    "rules": [
      "Be kind.",
      "No advertising."
    ]
  },
  "member": false
}

可能的状态： 200304400401404429

PUT`/v2/roles/{id}/self`

领取或取消一个自选身份组。

权限 write
自 v2.20

仅限管理层提供为自选的身份组（selfable），且仅限你自己的账号。

参数

名称	类型	含义
`id`在路径中	`string`必填	角色的 `id`。
`active`在正文中	`boolean`可选	`false` 收回角色；否则授予。

请求示例

curl -X PUT \
  -H "Authorization: Bearer tm_key_…" \
  -H "Content-Type: application/json" \
  -d '{"active":true}' \
  "https://api.tellmelo.com/v2/roles/4e5f6a7b-8c9d-4e0f-a1b2-c3d4e5f6a7b8/self"

响应

返回一个 Ok。

示例

{
  "ok": true
}

可能的状态： 200400401403404429

GET`/v2/communities/{id}/emojis`

群组自己的表情。

权限 read
带 ETag
自 v2.20

参数

名称	类型	含义
`id`在路径中	`string`必填	群组的 `id`。

请求示例

curl \
  -H "Authorization: Bearer tm_key_…" \
  "https://api.tellmelo.com/v2/communities/c81d4e2a-0f3b-4a6c-9e57-1d2b3c4a5f60/emojis"

响应

返回一页 GroupEmoji，形式为 `items` 和 `next`。

示例

{
  "items": [
    {
      "name": "seedling",
      "url": "/api/media?id=8c7b6a59-4837-4261-9f5e-d4c3b2a1f0e9",
      "animated": false
    }
  ],
  "next": null
}

可能的状态： 200304400401404429

PUT`/v2/communities/{id}/bell`

设置群组向你发送哪些通知。

权限 write
自 v2.15

参数

名称	类型	含义
`id`在路径中	`string`必填	群组的 `id`。
`level`在正文中	`string`必填	接收哪些通知。`allimportantoff`

请求示例

curl -X PUT \
  -H "Authorization: Bearer tm_key_…" \
  -H "Content-Type: application/json" \
  -d '{"level":"important"}' \
  "https://api.tellmelo.com/v2/communities/c81d4e2a-0f3b-4a6c-9e57-1d2b3c4a5f60/bell"

响应

返回一个 Bell。

示例

{
  "level": "important"
}

可能的状态： 200400401403404429

POST`/v2/invites/{code}/join`

通过邀请链接加入群组。

权限 write
自 v2.15

参数

名称	类型	含义
`code`在路径中	`string`必填	邀请链接的代码，即其地址的末尾部分。
`rules`在正文中	`boolean`可选	接受群组规则时为 `true`；群组有规则时必须提供。

请求示例

curl -X POST \
  -H "Authorization: Bearer tm_key_…" \
  "https://api.tellmelo.com/v2/invites/k7Qm2xPa/join"

响应

返回一个 Joined。

示例

{
  "community": "c81d4e2a-0f3b-4a6c-9e57-1d2b3c4a5f60"
}

可能的状态： 200400401403404429

GET`/v2/communities/{id}/bots`

群组的机器人及其角色允许的操作。

权限 read
带 ETag
自 v2.19

参数

名称	类型	含义
`id`在路径中	`string`必填	群组的 `id`。

请求示例

curl \
  -H "Authorization: Bearer tm_key_…" \
  "https://api.tellmelo.com/v2/communities/c81d4e2a-0f3b-4a6c-9e57-1d2b3c4a5f60/bots"

响应

返回一页 GroupBot，形式为 `items` 和 `next`。

示例

{
  "items": [
    {
      "id": "a3e1f7c2-54b9-4d0e-8f16-7b2c9d4e1a05",
      "handle": "gardenbot",
      "name": "Garden bot",
      "description": "Reminds the group of watering days.",
      "permissions": [
        "send",
        "view"
      ]
    }
  ],
  "next": null
}

可能的状态： 200304400401404429

频道

你所在群组的频道及其聊天：读取、发言、标为已读。

GET`/v2/communities/{id}/channels`

你能看到的群组频道，按其顺序排列。

权限 read
带 ETag
自 v2.15

动态频道（kind: feed）只在开启时出现在这里；其帖子通过 /communities/{id}/posts 获取。

参数

名称	类型	含义
`id`在路径中	`string`必填	群组的 `id`。

请求示例

curl \
  -H "Authorization: Bearer tm_key_…" \
  "https://api.tellmelo.com/v2/communities/c81d4e2a-0f3b-4a6c-9e57-1d2b3c4a5f60/channels"

响应

返回一页 Channel，形式为 `items` 和 `next`。

示例

{
  "items": [
    {
      "id": "0d9c8b7a-6f5e-4d3c-2b1a-0f9e8d7c6b5a",
      "kind": "chat",
      "name": "harvest",
      "topic": "What came in this week",
      "category": {
        "id": "9a8b7c6d-5e4f-4a3b-8c2d-1e0f9a8b7c6d",
        "name": "Garden",
        "symbol": {
          "emoji": null,
          "icon": null,
          "image": null,
          "color": null,
          "shape": null
        }
      },
      "unread": 3,
      "permissions": [
        "view",
        "send"
      ],
      "symbol": {
        "emoji": "🌻",
        "icon": null,
        "image": null,
        "color": "amber",
        "shape": "circle"
      }
    }
  ],
  "next": null
}

可能的状态： 200304400401404429

GET`/v2/channels/{id}/messages`

聊天频道中的消息，最新的在前。

权限 read
可分页
带 ETag
自 v2.15

每页最多 50 条消息。不包含你屏蔽的账号或屏蔽了你的账号的消息。

参数

名称	类型	含义
`id`在路径中	`string`必填	频道的 `id`。
`cursor`在查询中	`string`可选	上一个响应中的 `next`。不传则从头开始。
`thread`在查询中	`string`可选	要读取其话题的消息：返回它及其回复，而不是聊天。

请求示例

curl \
  -H "Authorization: Bearer tm_key_…" \
  "https://api.tellmelo.com/v2/channels/0d9c8b7a-6f5e-4d3c-2b1a-0f9e8d7c6b5a/messages"

响应

返回一页 ChannelMessage，形式为 `items` 和 `next`。

示例

{
  "items": [
    {
      "id": "61a2b3c4-d5e6-4f70-8192-a3b4c5d6e7f8",
      "text": "@jon the first tomatoes are ripe 🍅",
      "author": {
        "id": "a3e1f7c2-54b9-4d0e-8f16-7b2c9d4e1a05",
        "handle": "mara",
        "name": "Mara 🌻",
        "bot": false
      },
      "media": [
        {
          "url": "/api/media?id=b2d7e9f1-3c4a-4e8b-a1f0-6d5c4b3a2918",
          "kind": "image",
          "poster": null,
          "ai": "without"
        }
      ],
      "replyTo": "72b3c4d5-e6f7-4081-92a3-b4c5d6e7f809",
      "roleColor": "green",
      "threadOf": null,
      "threadCount": 3,
      "card": null,
      "buttons": [],
      "createdAt": 1758631200000
    }
  ],
  "next": "MTc1ODYyNDAwMDAwMDo1ZjBjMmE5ZS04ZDQx"
}

可能的状态： 200304400401404429

POST`/v2/channels/{id}/messages`

在聊天频道中发送消息。

权限 write
自 v2.15

@名称 通知一位成员；有相应权限时 @everyone 通知所有人，每小时最多六次。

参数

名称	类型	含义
`id`在路径中	`string`必填	频道的 `id`。
`text`在正文中	`string`可选	帖子、回复或私信的文字。
`replyTo`在正文中	`string`可选	你回复的同一频道中消息的 `id`。
`media`在正文中	`string[]`可选	在 App 中上传的图片的 ID，或媒体库中某个 GIF 或视频的 ID（自 2.14 起）。
`thread`在正文中	`string`可选	要在其话题中回复的聊天消息；不填则消息发到聊天中。
`card`在正文中	`object`可选	卡片 `{ title, text, color, fields: [{ name, value }] }`，最多 10 个字段。
`buttons`在正文中	`object[]`可选	最多 5 个按钮，每个为 `{ id, label, style }`，`style` 为 `primary`、`secondary` 或 `danger`。按下会作为 `interaction` 事件送达。

请求示例

curl -X POST \
  -H "Authorization: Bearer tm_key_…" \
  -H "Content-Type: application/json" \
  -d '{"text":"Who has seeds to swap?"}' \
  "https://api.tellmelo.com/v2/channels/0d9c8b7a-6f5e-4d3c-2b1a-0f9e8d7c6b5a/messages"

响应

返回一个 Made。

示例

{
  "id": "0d9c8b7a-6f5e-4d3c-2b1a-0f9e8d7c6b5a"
}

可能的状态： 200400401403404429

POST`/v2/channels/{id}/read`

将聊天频道标为已读，直到某个时间点。

权限 write
自 v2.15

参数

名称	类型	含义
`id`在路径中	`string`必填	频道的 `id`。
`at`在正文中	`integer`必填	已读到的时间点（毫秒），通常为最新消息的 `createdAt`。

请求示例

curl -X POST \
  -H "Authorization: Bearer tm_key_…" \
  "https://api.tellmelo.com/v2/channels/0d9c8b7a-6f5e-4d3c-2b1a-0f9e8d7c6b5a/read"

响应

返回一个 Ok。

示例

{
  "ok": true
}

可能的状态： 200400401403404429

DELETE`/v2/channel-messages/{id}`

删除你在聊天频道中的一条消息。

权限 write
自 v2.15

只能删除自己的消息；他人的消息由管理层通过 groups 权限移除。

参数

名称	类型	含义
`id`在路径中	`string`必填	聊天频道中消息的 `id`。

请求示例

curl -X DELETE \
  -H "Authorization: Bearer tm_key_…" \
  "https://api.tellmelo.com/v2/channel-messages/61a2b3c4-d5e6-4f70-8192-a3b4c5d6e7f8"

响应

返回一个 Ok。

示例

{
  "ok": true
}

可能的状态： 200400401403404429

GET`/v2/communities/{id}/voice`

群组语音频道中当前有谁，按频道列出。

权限 read
带 ETag
自 v2.19

仅限你能看到的频道。没有媒体服务器时列表为空。

参数

名称	类型	含义
`id`在路径中	`string`必填	群组的 `id`。

请求示例

curl \
  -H "Authorization: Bearer tm_key_…" \
  "https://api.tellmelo.com/v2/communities/c81d4e2a-0f3b-4a6c-9e57-1d2b3c4a5f60/voice"

响应

返回一页 VoiceRoom，形式为 `items` 和 `next`。

示例

{
  "items": [
    {
      "channel": "0d9c8b7a-6f5e-4d3c-2b1a-0f9e8d7c6b5a",
      "people": [
        {
          "id": "a3e1f7c2-54b9-4d0e-8f16-7b2c9d4e1a05",
          "handle": "mara",
          "name": "Mara 🌻",
          "muted": false,
          "deaf": false,
          "camera": false,
          "screen": true
        }
      ]
    }
  ],
  "next": null
}

可能的状态： 200304400401404429

管理群组

群组设置在应用中能做的事，需要 groups 权限。你的账号能做什么由群组决定，与应用中相同：管理层、角色及其等级。

POST`/v2/communities/{id}/emojis`

为群组添加一个表情。

权限 groups
自 v2.20

仅限可管理群组频道的人。图片像自己的表情一样上传（POST /me/emojis/pictures）；所有表情中一个名称只能使用一次。

参数

名称	类型	含义
`id`在路径中	`string`必填	群组的 `id`。
`name`在正文中	`string`必填	书写表情时用的名称，形如 `:名称:`。
`picture`在正文中	`string`必填	来自 `POST /me/emojis/pictures` 的 `id`。

请求示例

curl -X POST \
  -H "Authorization: Bearer tm_key_…" \
  -H "Content-Type: application/json" \
  -d '{"name":"seedling","picture":"8c7b6a59-4837-4261-9f5e-d4c3b2a1f0e9"}' \
  "https://api.tellmelo.com/v2/communities/c81d4e2a-0f3b-4a6c-9e57-1d2b3c4a5f60/emojis"

响应

返回一页 GroupEmoji，形式为 `items` 和 `next`。

示例

{
  "items": [
    {
      "name": "seedling",
      "url": "/api/media?id=8c7b6a59-4837-4261-9f5e-d4c3b2a1f0e9",
      "animated": false
    }
  ],
  "next": null
}

可能的状态： 200400401403404429

DELETE`/v2/communities/{id}/emojis/{name}`

从群组移除一个表情。

权限 groups
自 v2.20

参数

名称	类型	含义
`id`在路径中	`string`必填	群组的 `id`。
`name`在路径中	`string`必填	表情名称，不带冒号。

请求示例

curl -X DELETE \
  -H "Authorization: Bearer tm_key_…" \
  "https://api.tellmelo.com/v2/communities/c81d4e2a-0f3b-4a6c-9e57-1d2b3c4a5f60/emojis/seedling"

响应

返回一页 GroupEmoji，形式为 `items` 和 `next`。

示例

{
  "items": [
    {
      "name": "seedling",
      "url": "/api/media?id=8c7b6a59-4837-4261-9f5e-d4c3b2a1f0e9",
      "animated": false
    }
  ],
  "next": null
}

可能的状态： 200400401403404429

POST`/v2/communities/{id}/roles`

创建角色。

权限 groups
自 v2.15

只能操作低于你最高角色的角色，且只能授予你自己拥有的权限；管理层高于所有角色。

参数

名称	类型	含义
`id`在路径中	`string`必填	群组的 `id`。
`name`在正文中	`string`可选	角色名称；@everyone 保留其名称。
`color`在正文中	`string`可选	颜色；留空表示无颜色。`indigovioletroseambergreenteal`
`permissions`在正文中	`string[]`可选	权限：`view`、`send`、`attach`、`post_feed`、`invite`、`mention_everyone`、`moderate`、`timeout_members`、`kick_members`、`ban_members`、`manage_channels`、`manage_roles`。
`selfable`在正文中	`boolean`可选	`true`：成员自行领取该身份组。仅限权限不超出参与范围的身份组（view、send、attach、voice_connect、voice_speak、voice_video）。

请求示例

curl -X POST \
  -H "Authorization: Bearer tm_key_…" \
  -H "Content-Type: application/json" \
  -d '{"name":"Gardeners","permissions":["view","send","invite"],"selfable":false}' \
  "https://api.tellmelo.com/v2/communities/c81d4e2a-0f3b-4a6c-9e57-1d2b3c4a5f60/roles"

响应

返回一个 Made。

示例

{
  "id": "0d9c8b7a-6f5e-4d3c-2b1a-0f9e8d7c6b5a"
}

可能的状态： 200400401403404429

PUT`/v2/roles/{id}`

修改角色的名称、颜色和权限。

权限 groups
自 v2.15

替换名称、颜色和权限；省略的内容将变为空。

只能操作低于你最高角色的角色，且只能授予你自己拥有的权限；管理层高于所有角色。

参数

名称	类型	含义
`id`在路径中	`string`必填	角色的 `id`。
`name`在正文中	`string`可选	角色名称；@everyone 保留其名称。
`color`在正文中	`string`可选	颜色；留空表示无颜色。`indigovioletroseambergreenteal`
`permissions`在正文中	`string[]`可选	权限：`view`、`send`、`attach`、`post_feed`、`invite`、`mention_everyone`、`moderate`、`timeout_members`、`kick_members`、`ban_members`、`manage_channels`、`manage_roles`。
`selfable`在正文中	`boolean`可选	`true`：成员自行领取该身份组。仅限权限不超出参与范围的身份组（view、send、attach、voice_connect、voice_speak、voice_video）。

请求示例

curl -X PUT \
  -H "Authorization: Bearer tm_key_…" \
  -H "Content-Type: application/json" \
  -d '{"name":"Gardeners","permissions":["view","send","invite"],"selfable":false}' \
  "https://api.tellmelo.com/v2/roles/4e5f6a7b-8c9d-4e0f-a1b2-c3d4e5f6a7b8"

响应

返回一个 Made。

示例

{
  "id": "0d9c8b7a-6f5e-4d3c-2b1a-0f9e8d7c6b5a"
}

可能的状态： 200400401403404429

DELETE`/v2/roles/{id}`

删除角色。

权限 groups
自 v2.15

参数

名称	类型	含义
`id`在路径中	`string`必填	角色的 `id`。

请求示例

curl -X DELETE \
  -H "Authorization: Bearer tm_key_…" \
  "https://api.tellmelo.com/v2/roles/4e5f6a7b-8c9d-4e0f-a1b2-c3d4e5f6a7b8"

响应

返回一个 Ok。

示例

{
  "ok": true
}

可能的状态： 200400401403404429

PUT`/v2/communities/{id}/roles/order`

设置角色的等级顺序。

权限 groups
自 v2.15

参数

名称	类型	含义
`id`在路径中	`string`必填	群组的 `id`。
`roles`在正文中	`string[]`必填	你自己最高角色之下所有角色的 `id`，最高的在前；对于管理层，是除 @everyone 之外的全部角色。

请求示例

curl -X PUT \
  -H "Authorization: Bearer tm_key_…" \
  "https://api.tellmelo.com/v2/communities/c81d4e2a-0f3b-4a6c-9e57-1d2b3c4a5f60/roles/order"

响应

返回一个 Ok。

示例

{
  "ok": true
}

可能的状态： 200400401403404429

PUT`/v2/roles/{id}/members/{member}`

给成员授予或收回角色。

权限 groups
自 v2.15

参数

名称	类型	含义
`id`在路径中	`string`必填	角色的 `id`。
`member`在路径中	`string`必填	成员账号的 `id`。
`active`在正文中	`boolean`可选	`false` 收回角色；否则授予。

请求示例

curl -X PUT \
  -H "Authorization: Bearer tm_key_…" \
  -H "Content-Type: application/json" \
  -d '{"active":true}' \
  "https://api.tellmelo.com/v2/roles/4e5f6a7b-8c9d-4e0f-a1b2-c3d4e5f6a7b8/members/d4c3b2a1-6e5f-4a7b-9c8d-1e2f3a4b5c6d"

响应

返回一个 Ok。

示例

{
  "ok": true
}

可能的状态： 200400401403404429

POST`/v2/communities/{id}/channels`

创建聊天频道。

权限 groups
自 v2.15

参数

名称	类型	含义
`id`在路径中	`string`必填	群组的 `id`。
`name`在正文中	`string`可选	名称，不含 `#`；留空则使用应用在各语言中给出的名称。
`topic`在正文中	`string`可选	显示在频道上方的主题。
`category`在正文中	`string`可选	频道所属分类的 `id`；留空表示无分类。
`emoji`在正文中	`string`可选	用作图标的表情。
`icon`在正文中	`string`可选	应用图标库中的图标名称。`homehashmegaphonevolumemessagehelpinfobellcalendarbookbookmarkpinshieldstarheartsparklesflamezaptrophygiftrocketlightbulbcodewrenchbriefcasegraduationpalettecamerafilmmusicgamepaddumbbellleafflowerpawsunmooncloudglobemapcoffeepizzasmile`
`image`在正文中	`string`可选	你通过 `/media/emoji` 上传的图片 id。
`color`在正文中	`string`可选	图块的颜色。`brandindigovioletroseambergreentealred`
`shape`在正文中	`string`可选	图块形状；不填则为圆形。`circlesquaretrianglediamondhexagonoctagonshieldstar`

请求示例

curl -X POST \
  -H "Authorization: Bearer tm_key_…" \
  -H "Content-Type: application/json" \
  -d '{"name":"harvest","emoji":"🌻","color":"amber"}' \
  "https://api.tellmelo.com/v2/communities/c81d4e2a-0f3b-4a6c-9e57-1d2b3c4a5f60/channels"

响应

返回一个 Made。

示例

{
  "id": "0d9c8b7a-6f5e-4d3c-2b1a-0f9e8d7c6b5a"
}

可能的状态： 200400401403404429

PUT`/v2/channels/{id}`

修改频道的名称、主题和分类。

权限 groups
自 v2.15

替换名称、主题和分类；省略的内容将变为空。

参数

名称	类型	含义
`id`在路径中	`string`必填	频道的 `id`。
`name`在正文中	`string`可选	名称，不含 `#`；留空则使用应用在各语言中给出的名称。
`topic`在正文中	`string`可选	显示在频道上方的主题。
`category`在正文中	`string`可选	频道所属分类的 `id`；留空表示无分类。
`emoji`在正文中	`string`可选	用作图标的表情。
`icon`在正文中	`string`可选	应用图标库中的图标名称。`homehashmegaphonevolumemessagehelpinfobellcalendarbookbookmarkpinshieldstarheartsparklesflamezaptrophygiftrocketlightbulbcodewrenchbriefcasegraduationpalettecamerafilmmusicgamepaddumbbellleafflowerpawsunmooncloudglobemapcoffeepizzasmile`
`image`在正文中	`string`可选	你通过 `/media/emoji` 上传的图片 id。
`color`在正文中	`string`可选	图块的颜色。`brandindigovioletroseambergreentealred`
`shape`在正文中	`string`可选	图块形状；不填则为圆形。`circlesquaretrianglediamondhexagonoctagonshieldstar`

请求示例

curl -X PUT \
  -H "Authorization: Bearer tm_key_…" \
  -H "Content-Type: application/json" \
  -d '{"name":"harvest","emoji":"🌻","color":"amber"}' \
  "https://api.tellmelo.com/v2/channels/0d9c8b7a-6f5e-4d3c-2b1a-0f9e8d7c6b5a"

响应

返回一个 Made。

示例

{
  "id": "0d9c8b7a-6f5e-4d3c-2b1a-0f9e8d7c6b5a"
}

可能的状态： 200400401403404429

DELETE`/v2/channels/{id}`

删除聊天频道及其消息。

权限 groups
自 v2.15

动态频道不能删除，只能关闭。

参数

名称	类型	含义
`id`在路径中	`string`必填	频道的 `id`。

请求示例

curl -X DELETE \
  -H "Authorization: Bearer tm_key_…" \
  "https://api.tellmelo.com/v2/channels/0d9c8b7a-6f5e-4d3c-2b1a-0f9e8d7c6b5a"

响应

返回一个 Ok。

示例

{
  "ok": true
}

可能的状态： 200400401403404429

PUT`/v2/communities/{id}/channels/order`

设置分类和聊天频道的顺序。

权限 groups
自 v2.15

参数

名称	类型	含义
`id`在路径中	`string`必填	群组的 `id`。
`categories`在正文中	`string[]`必填	群组所有分类的 `id`，按新的顺序。
`channels`在正文中	`string[]`必填	群组所有聊天频道的 `id`，按新的顺序。

请求示例

curl -X PUT \
  -H "Authorization: Bearer tm_key_…" \
  "https://api.tellmelo.com/v2/communities/c81d4e2a-0f3b-4a6c-9e57-1d2b3c4a5f60/channels/order"

响应

返回一个 Ok。

示例

{
  "ok": true
}

可能的状态： 200400401403404429

PUT`/v2/communities/{id}/channels/shape`

设定群组所有频道图标的形状。

权限 groups
自 v2.20

仅限群组管理者。

参数

名称	类型	含义
`id`在路径中	`string`必填	群组的 `id`。
`shape`在正文中	`string`可选	群组所有图标的形状；省略时各频道自选。`circlesquaretrianglediamondhexagonoctagonshieldstar`

请求示例

curl -X PUT \
  -H "Authorization: Bearer tm_key_…" \
  "https://api.tellmelo.com/v2/communities/c81d4e2a-0f3b-4a6c-9e57-1d2b3c4a5f60/channels/shape"

响应

返回一个 Ok。

示例

{
  "ok": true
}

可能的状态： 200400401403404429

GET`/v2/channels/{id}/overrides`

角色在某个频道中与在群组中不同的权限。

权限 groups
带 ETag
自 v2.15

参数

名称	类型	含义
`id`在路径中	`string`必填	频道的 `id`。

请求示例

curl \
  -H "Authorization: Bearer tm_key_…" \
  "https://api.tellmelo.com/v2/channels/0d9c8b7a-6f5e-4d3c-2b1a-0f9e8d7c6b5a/overrides"

响应

返回一页 ChannelOverride，形式为 `items` 和 `next`。

示例

{
  "items": [
    {
      "role": "4e5f6a7b-8c9d-4e0f-a1b2-c3d4e5f6a7b8",
      "allow": [
        "send"
      ],
      "deny": []
    }
  ],
  "next": null
}

可能的状态： 200304400401403404429

PUT`/v2/channels/{id}/overrides/{role}`

设置某个角色在频道中的不同权限。

权限 groups
自 v2.15

不适用于与你最高角色同级或更高的角色。

参数

名称	类型	含义
`id`在路径中	`string`必填	频道的 `id`。
`role`在路径中	`string`必填	角色的 `id`。
`allow`在正文中	`string[]`可选	该角色在这里额外可以做的：在聊天中 `view`、`send`、`attach`、`mention_everyone`、`moderate`，在动态频道中 `view` 和 `post_feed`。
`deny`在正文中	`string[]`可选	该角色在此不能做的事，取自同一组权限。两个列表都为空时取消差异。

请求示例

curl -X PUT \
  -H "Authorization: Bearer tm_key_…" \
  -H "Content-Type: application/json" \
  -d '{"allow":["view"],"deny":["send"]}' \
  "https://api.tellmelo.com/v2/channels/0d9c8b7a-6f5e-4d3c-2b1a-0f9e8d7c6b5a/overrides/4e5f6a7b-8c9d-4e0f-a1b2-c3d4e5f6a7b8"

响应

返回一个 Ok。

示例

{
  "ok": true
}

可能的状态： 200400401403404429

POST`/v2/communities/{id}/categories`

创建频道分类。

权限 groups
自 v2.15

参数

名称	类型	含义
`id`在路径中	`string`必填	群组的 `id`。
`name`在正文中	`string`必填	分类名称。
`emoji`在正文中	`string`可选	用作图标的表情。
`icon`在正文中	`string`可选	应用图标库中的图标名称。`homehashmegaphonevolumemessagehelpinfobellcalendarbookbookmarkpinshieldstarheartsparklesflamezaptrophygiftrocketlightbulbcodewrenchbriefcasegraduationpalettecamerafilmmusicgamepaddumbbellleafflowerpawsunmooncloudglobemapcoffeepizzasmile`
`image`在正文中	`string`可选	你通过 `/media/emoji` 上传的图片 id。
`color`在正文中	`string`可选	图块的颜色。`brandindigovioletroseambergreentealred`

请求示例

curl -X POST \
  -H "Authorization: Bearer tm_key_…" \
  -H "Content-Type: application/json" \
  -d '{"name":"Garden","emoji":"🌻","color":"amber"}' \
  "https://api.tellmelo.com/v2/communities/c81d4e2a-0f3b-4a6c-9e57-1d2b3c4a5f60/categories"

响应

返回一个 Made。

示例

{
  "id": "0d9c8b7a-6f5e-4d3c-2b1a-0f9e8d7c6b5a"
}

可能的状态： 200400401403404429

PUT`/v2/categories/{id}`

重命名分类。

权限 groups
自 v2.15

参数

名称	类型	含义
`id`在路径中	`string`必填	分类的 `id`。
`name`在正文中	`string`必填	分类名称。
`emoji`在正文中	`string`可选	用作图标的表情。
`icon`在正文中	`string`可选	应用图标库中的图标名称。`homehashmegaphonevolumemessagehelpinfobellcalendarbookbookmarkpinshieldstarheartsparklesflamezaptrophygiftrocketlightbulbcodewrenchbriefcasegraduationpalettecamerafilmmusicgamepaddumbbellleafflowerpawsunmooncloudglobemapcoffeepizzasmile`
`image`在正文中	`string`可选	你通过 `/media/emoji` 上传的图片 id。
`color`在正文中	`string`可选	图块的颜色。`brandindigovioletroseambergreentealred`

请求示例

curl -X PUT \
  -H "Authorization: Bearer tm_key_…" \
  -H "Content-Type: application/json" \
  -d '{"name":"Garden","emoji":"🌻","color":"amber"}' \
  "https://api.tellmelo.com/v2/categories/9a8b7c6d-5e4f-4a3b-8c2d-1e0f9a8b7c6d"

响应

返回一个 Made。

示例

{
  "id": "0d9c8b7a-6f5e-4d3c-2b1a-0f9e8d7c6b5a"
}

可能的状态： 200400401403404429

DELETE`/v2/categories/{id}`

删除分类。

权限 groups
自 v2.15

其中的频道保留，但没有分类。

参数

名称	类型	含义
`id`在路径中	`string`必填	分类的 `id`。

请求示例

curl -X DELETE \
  -H "Authorization: Bearer tm_key_…" \
  "https://api.tellmelo.com/v2/categories/9a8b7c6d-5e4f-4a3b-8c2d-1e0f9a8b7c6d"

响应

返回一个 Ok。

示例

{
  "ok": true
}

可能的状态： 200400401403404429

PUT`/v2/communities/{id}/feed`

开启或关闭群组的动态频道。

权限 groups
自 v2.15

关闭后，帖子仍会保存，但只有作者本人能看到。

参数

名称	类型	含义
`id`在路径中	`string`必填	群组的 `id`。
`on`在正文中	`boolean`必填	`true` 开启动态频道，`false` 关闭。

请求示例

curl -X PUT \
  -H "Authorization: Bearer tm_key_…" \
  "https://api.tellmelo.com/v2/communities/c81d4e2a-0f3b-4a6c-9e57-1d2b3c4a5f60/feed"

响应

返回一个 Ok。

示例

{
  "ok": true
}

可能的状态： 200400401403404429

GET`/v2/communities/{id}/invites`

群组仍然有效的邀请链接。

权限 groups
带 ETag
自 v2.15

管理层能看到全部，其他人只能看到自己创建的。

参数

名称	类型	含义
`id`在路径中	`string`必填	群组的 `id`。

请求示例

curl \
  -H "Authorization: Bearer tm_key_…" \
  "https://api.tellmelo.com/v2/communities/c81d4e2a-0f3b-4a6c-9e57-1d2b3c4a5f60/invites"

响应

返回一页 InviteLink，形式为 `items` 和 `next`。

示例

{
  "items": [
    {
      "code": "k7Qm2xPa",
      "url": "https://tellmelo.com/groups?join=k7Qm2xPa",
      "createdBy": {
        "id": "d4c3b2a1-6e5f-4a7b-9c8d-1e2f3a4b5c6d",
        "handle": "jon",
        "name": "Jon",
        "bot": false
      },
      "createdAt": 1758624000000,
      "expiresAt": 1759228800000,
      "uses": 3,
      "maxUses": 10
    }
  ],
  "next": null
}

可能的状态： 200304400401403404429

POST`/v2/communities/{id}/invites`

创建邀请链接。

权限 groups
自 v2.15

链接只在你仍有邀请权限时有效，你退出群组后链接随之删除。

参数

名称	类型	含义
`id`在路径中	`string`必填	群组的 `id`。
`days`在正文中	`integer`可选	链接有效的天数；不传则一直有效，直到被收回。`1730`
`uses`在正文中	`integer`可选	链接可使用的次数；不传则不限次数。`151025100`

请求示例

curl -X POST \
  -H "Authorization: Bearer tm_key_…" \
  -H "Content-Type: application/json" \
  -d '{"days":7,"uses":10}' \
  "https://api.tellmelo.com/v2/communities/c81d4e2a-0f3b-4a6c-9e57-1d2b3c4a5f60/invites"

响应

返回一个 Made。

示例

{
  "id": "0d9c8b7a-6f5e-4d3c-2b1a-0f9e8d7c6b5a"
}

可能的状态： 200400401403404429

DELETE`/v2/invites/{code}`

收回邀请链接。

权限 groups
自 v2.15

参数

名称	类型	含义
`code`在路径中	`string`必填	邀请链接的代码，即其地址的末尾部分。

请求示例

curl -X DELETE \
  -H "Authorization: Bearer tm_key_…" \
  "https://api.tellmelo.com/v2/invites/k7Qm2xPa"

响应

返回一个 Ok。

示例

{
  "ok": true
}

可能的状态： 200400401403404429

POST`/v2/channel-messages/{id}/remove`

从频道中移除其他成员的消息。

权限 groups
自 v2.15

与应用中一样，会记入群组记录，每小时最多 60 次。

参数

名称	类型	含义
`id`在路径中	`string`必填	聊天频道中消息的 `id`。

请求示例

curl -X POST \
  -H "Authorization: Bearer tm_key_…" \
  "https://api.tellmelo.com/v2/channel-messages/61a2b3c4-d5e6-4f70-8192-a3b4c5d6e7f8/remove"

响应

返回一个 Ok。

示例

{
  "ok": true
}

可能的状态： 200400401403404429

POST`/v2/communities/{id}/posts/{post}/remove`

从群组中移除帖子。

权限 groups
自 v2.15

与应用中一样，会记入群组记录，每小时最多 60 次。

参数

名称	类型	含义
`id`在路径中	`string`必填	群组的 `id`。
`post`在路径中	`string`必填	帖子的 `id`。
`reason`在正文中	`string`必填	成员会看到的理由。

请求示例

curl -X POST \
  -H "Authorization: Bearer tm_key_…" \
  -H "Content-Type: application/json" \
  -d '{"reason":"Advertising for another site, despite rule 2."}' \
  "https://api.tellmelo.com/v2/communities/c81d4e2a-0f3b-4a6c-9e57-1d2b3c4a5f60/posts/post/remove"

响应

返回一个 Ok。

示例

{
  "ok": true
}

可能的状态： 200400401403404429

DELETE`/v2/communities/{id}/members/{member}`

将成员踢出群组。

权限 groups
自 v2.15

自 2.16 起为踢出：成员可以回来。需要留在外面的人应当封禁。

仅限拥有相应权限时，且仅对低于你最高角色的成员；协同管理者仅限创建者。

与应用中一样，会记入群组记录，每小时最多 60 次。

参数

名称	类型	含义
`id`在路径中	`string`必填	群组的 `id`。
`member`在路径中	`string`必填	成员账号的 `id`。
`reason`在正文中	`string`必填	成员会看到的理由。

请求示例

curl -X DELETE \
  -H "Authorization: Bearer tm_key_…" \
  -H "Content-Type: application/json" \
  -d '{"reason":"Advertising for another site, despite rule 2."}' \
  "https://api.tellmelo.com/v2/communities/c81d4e2a-0f3b-4a6c-9e57-1d2b3c4a5f60/members/d4c3b2a1-6e5f-4a7b-9c8d-1e2f3a4b5c6d"

响应

返回一个 Ok。

示例

{
  "ok": true
}

可能的状态： 200400401403404429

PUT`/v2/communities/{id}/members/{member}/timeout`

禁言成员。

权限 groups
自 v2.16

新的禁言会替换正在进行的禁言。退出后再加入不会结束禁言。

仅限拥有相应权限时，且仅对低于你最高角色的成员；协同管理者仅限创建者。

与应用中一样，会记入群组记录，每小时最多 60 次。

参数

名称	类型	含义
`id`在路径中	`string`必填	群组的 `id`。
`member`在路径中	`string`必填	成员账号的 `id`。
`seconds`在正文中	`integer`必填	持续时间，以秒计。`60300600360086400604800`
`reason`在正文中	`string`可选	成员会看到的理由；可选。

请求示例

curl -X PUT \
  -H "Authorization: Bearer tm_key_…" \
  -H "Content-Type: application/json" \
  -d '{"seconds":600}' \
  "https://api.tellmelo.com/v2/communities/c81d4e2a-0f3b-4a6c-9e57-1d2b3c4a5f60/members/d4c3b2a1-6e5f-4a7b-9c8d-1e2f3a4b5c6d/timeout"

响应

返回一个 Until。

示例

{
  "until": 1758624600000
}

可能的状态： 200400401403404429

DELETE`/v2/communities/{id}/members/{member}/timeout`

解除禁言。

权限 groups
自 v2.16

参数

名称	类型	含义
`id`在路径中	`string`必填	群组的 `id`。
`member`在路径中	`string`必填	成员账号的 `id`。

请求示例

curl -X DELETE \
  -H "Authorization: Bearer tm_key_…" \
  "https://api.tellmelo.com/v2/communities/c81d4e2a-0f3b-4a6c-9e57-1d2b3c4a5f60/members/d4c3b2a1-6e5f-4a7b-9c8d-1e2f3a4b5c6d/timeout"

响应

返回一个 Until。

示例

{
  "until": 1758624600000
}

可能的状态： 200400401403404429

GET`/v2/communities/{id}/bans`

群组当前的封禁。

权限 groups
带 ETag
自 v2.16

参数

名称	类型	含义
`id`在路径中	`string`必填	群组的 `id`。

请求示例

curl \
  -H "Authorization: Bearer tm_key_…" \
  "https://api.tellmelo.com/v2/communities/c81d4e2a-0f3b-4a6c-9e57-1d2b3c4a5f60/bans"

响应

返回一页 Ban，形式为 `items` 和 `next`。

示例

{
  "items": [
    {
      "member": {
        "id": "d4c3b2a1-6e5f-4a7b-9c8d-1e2f3a4b5c6d",
        "handle": "jon",
        "name": "Jon",
        "bot": false
      },
      "until": 1759228800000,
      "createdAt": 1758624000000,
      "by": "Mara 🌻"
    }
  ],
  "next": null
}

可能的状态： 200304400401403404429

PUT`/v2/communities/{id}/bans/{member}`

封禁成员。

权限 groups
自 v2.16

没有 days 时，封禁一直有效，直到被解除。

仅限拥有相应权限时，且仅对低于你最高角色的成员；协同管理者仅限创建者。

与应用中一样，会记入群组记录，每小时最多 60 次。

参数

名称	类型	含义
`id`在路径中	`string`必填	群组的 `id`。
`member`在路径中	`string`必填	成员账号的 `id`。
`days`在正文中	`integer`可选	持续时间，以天计；不填表示无期限封禁。`1730`
`reason`在正文中	`string`必填	成员会看到的理由。

请求示例

curl -X PUT \
  -H "Authorization: Bearer tm_key_…" \
  -H "Content-Type: application/json" \
  -d '{"days":7,"reason":"Advertising for another site, despite rule 2."}' \
  "https://api.tellmelo.com/v2/communities/c81d4e2a-0f3b-4a6c-9e57-1d2b3c4a5f60/bans/d4c3b2a1-6e5f-4a7b-9c8d-1e2f3a4b5c6d"

响应

返回一个 Until。

示例

{
  "until": 1758624600000
}

可能的状态： 200400401403404429

DELETE`/v2/communities/{id}/bans/{member}`

解除封禁。

权限 groups
自 v2.16

参数

名称	类型	含义
`id`在路径中	`string`必填	群组的 `id`。
`member`在路径中	`string`必填	成员账号的 `id`。

请求示例

curl -X DELETE \
  -H "Authorization: Bearer tm_key_…" \
  "https://api.tellmelo.com/v2/communities/c81d4e2a-0f3b-4a6c-9e57-1d2b3c4a5f60/bans/d4c3b2a1-6e5f-4a7b-9c8d-1e2f3a4b5c6d"

响应

返回一个 Ok。

示例

{
  "ok": true
}

可能的状态： 200400401403404429

GET`/v2/communities/{id}/log`

管理层记录：谁移除了什么以及原因。

权限 groups
带 ETag
自 v2.15

参数

名称	类型	含义
`id`在路径中	`string`必填	群组的 `id`。

请求示例

curl \
  -H "Authorization: Bearer tm_key_…" \
  "https://api.tellmelo.com/v2/communities/c81d4e2a-0f3b-4a6c-9e57-1d2b3c4a5f60/log"

响应

返回一页 LogEntry，形式为 `items` 和 `next`。

示例

{
  "items": [
    {
      "id": "8f7e6d5c-4b3a-4291-8f7e-6d5c4b3a2918",
      "action": "message_removed",
      "member": {
        "id": "d4c3b2a1-6e5f-4a7b-9c8d-1e2f3a4b5c6d",
        "handle": "jon",
        "name": "Jon",
        "bot": false
      },
      "reason": "",
      "by": "Mara 🌻",
      "createdAt": 1758710400000
    }
  ],
  "next": null
}

可能的状态： 200304400401403404429

POST`/v2/communities`

创建一个群组。返回它的 id；你是创建者。

权限 groups
自 v2.19

需要 groups 权限。未指定时群组为 internal 且可自由加入；隐藏群组仅限邀请。成员能否创建群组由运营者决定。

参数

名称	类型	含义
`name`在正文中	`string`必填	名称，最多 60 个字符。
`description`在正文中	`string`可选	描述，最多 240 个字符。
`handle`在正文中	`string`可选	用于 @# 提及和链接的短名：3 到 30 个小写字母、数字或 `_`。
`tags`在正文中	`string[]`可选	最多 5 个描述群组主题的 #标签。
`joinPolicy`在正文中	`string`可选	加入方式：`open` 自由加入，`application` 申请加入，`invite` 仅限邀请。`openapplicationinvite`
`visibility`在正文中	`string`可选	谁能看到群组：`open` 所有人，`internal` 内容仅成员可见，`hidden` 完全仅成员可见。`openinternalhidden`

请求示例

curl -X POST \
  -H "Authorization: Bearer tm_key_…" \
  -H "Content-Type: application/json" \
  -d '{"name":"Seed swap","handle":"seedswap","tags":["garden","seeds"],"joinPolicy":"open","visibility":"open"}' \
  "https://api.tellmelo.com/v2/communities"

响应

返回一个 Made。

示例

{
  "id": "0d9c8b7a-6f5e-4d3c-2b1a-0f9e8d7c6b5a"
}

可能的状态： 200400401403429

PUT`/v2/communities/{id}`

修改你管理的群组。未提供的项目保持不变。

权限 groups
自 v2.19

需要 groups 权限并管理该群组。管理权、解散和火花特权仍在应用中操作。

参数

名称	类型	含义
`id`在路径中	`string`必填	群组的 `id`。
`name`在正文中	`string`可选	名称，最多 60 个字符。
`description`在正文中	`string`可选	描述，最多 240 个字符。
`handle`在正文中	`string`可选	用于 @# 提及和链接的短名：3 到 30 个小写字母、数字或 `_`。
`tags`在正文中	`string[]`可选	最多 5 个描述群组主题的 #标签。
`joinPolicy`在正文中	`string`可选	加入方式：`open` 自由加入，`application` 申请加入，`invite` 仅限邀请。`openapplicationinvite`
`visibility`在正文中	`string`可选	谁能看到群组：`open` 所有人，`internal` 内容仅成员可见，`hidden` 完全仅成员可见。`openinternalhidden`
`image`在正文中	`string`可选	作为群组头像的已上传图片 `id`（`POST /me/pictures`）。留空则移除。
`banner`在正文中	`string`可选	作为群组封面的已上传图片 `id`。留空则移除。

请求示例

curl -X PUT \
  -H "Authorization: Bearer tm_key_…" \
  -H "Content-Type: application/json" \
  -d '{"name":"Seed swap","handle":"seedswap","tags":["garden","seeds"],"joinPolicy":"open","visibility":"open"}' \
  "https://api.tellmelo.com/v2/communities/c81d4e2a-0f3b-4a6c-9e57-1d2b3c4a5f60"

响应

返回一个 Ok。

示例

{
  "ok": true
}

可能的状态： 200400401403404429

机器人

机器人所在群组中发生的事，实时：以流、按页或投递到地址的方式。

GET`/v2/events`

机器人所在群组自某事件以来的事件，按页读取。

权限 read
自 v2.20

仅限机器人的令牌。频道的事件仅在机器人可查看该频道时提供。

事件保留一天。next 是最后一个事件的编号，作为下一页的 since。

参数

名称	类型	含义
`since`在查询中	`string`可选	机器人已有的最后一个事件的编号。没有它时，流从现在开始，列表从最早的开始。

请求示例

curl \
  -H "Authorization: Bearer tm_key_…" \
  "https://api.tellmelo.com/v2/events?since=0"

响应

返回一页 BotEvent，形式为 `items` 和 `next`。

示例

{
  "items": [
    {
      "id": "4711",
      "type": "message.created",
      "community": "c81d4e2a-0f3b-4a6c-9e57-1d2b3c4a5f60",
      "channel": "0d9c8b7a-6f5e-4d3c-2b1a-0f9e8d7c6b5a",
      "createdAt": 1758634800000,
      "data": {
        "message": {
          "id": "61a2b3c4-d5e6-4f70-8192-a3b4c5d6e7f8",
          "text": "/dice 6",
          "author": {
            "id": "a3e1f7c2-54b9-4d0e-8f16-7b2c9d4e1a05",
            "handle": "mara",
            "name": "Mara 🌻",
            "bot": false
          },
          "media": 0,
          "replyTo": null,
          "threadOf": null,
          "createdAt": 1758634800000
        }
      }
    }
  ],
  "next": null
}

可能的状态： 200401429

GET`/v2/events/stream`

机器人所在群组的事件，发生即送达（server-sent events）。

权限 read
带 ETag
自 v2.20

连接保持打开，十分钟后关闭；客户端重新连接并发送 Last-Event-ID。

仅限机器人的令牌。频道的事件仅在机器人可查看该频道时提供。

参数

名称	类型	含义
`since`在查询中	`string`可选	机器人已有的最后一个事件的编号。没有它时，流从现在开始，列表从最早的开始。

请求示例

curl \
  -H "Authorization: Bearer tm_key_…" \
  "https://api.tellmelo.com/v2/events/stream?since=0"

响应

返回一个 BotEvent。

示例

{
  "id": "4711",
  "type": "message.created",
  "community": "c81d4e2a-0f3b-4a6c-9e57-1d2b3c4a5f60",
  "channel": "0d9c8b7a-6f5e-4d3c-2b1a-0f9e8d7c6b5a",
  "createdAt": 1758634800000,
  "data": {
    "message": {
      "id": "61a2b3c4-d5e6-4f70-8192-a3b4c5d6e7f8",
      "text": "/dice 6",
      "author": {
        "id": "a3e1f7c2-54b9-4d0e-8f16-7b2c9d4e1a05",
        "handle": "mara",
        "name": "Mara 🌻",
        "bot": false
      },
      "media": 0,
      "replyTo": null,
      "threadOf": null,
      "createdAt": 1758634800000
    }
  }
}

可能的状态： 200304401429

GET`/v2/me/commands`

机器人的命令。

权限 read
带 ETag
自 v2.20

仅限机器人的令牌。频道的事件仅在机器人可查看该频道时提供。

请求示例

curl \
  -H "Authorization: Bearer tm_key_…" \
  "https://api.tellmelo.com/v2/me/commands"

响应

返回一页 BotCommand，形式为 `items` 和 `next`。

示例

{
  "items": [
    {
      "name": "dice",
      "description": "Rolls a die"
    }
  ],
  "next": null
}

可能的状态： 200304401429

PUT`/v2/me/commands`

一次性设置机器人的全部命令。

权限 write
自 v2.20

替换所有命令；空列表会将其移除。在机器人可查看的聊天中，输入框会在“/”之后提示这些命令。

参数

名称	类型	含义
`commands`在正文中	`object[]`必填	最多 25 个命令，每个为 `{ name, description }`。

请求示例

curl -X PUT \
  -H "Authorization: Bearer tm_key_…" \
  -H "Content-Type: application/json" \
  -d '{"commands":[{"name":"dice","description":"Rolls a die"}]}' \
  "https://api.tellmelo.com/v2/me/commands"

响应

返回一页 BotCommand，形式为 `items` 和 `next`。

示例

{
  "items": [
    {
      "name": "dice",
      "description": "Rolls a die"
    }
  ],
  "next": null
}

可能的状态： 200400401403429

POST`/v2/interactions/{id}/reply`

回复命令或按钮。

权限 write
自 v2.20

在 command 或 interaction 事件后 15 分钟内；使用 private 时，只有使用该命令或按钮的人能看到回复。

参数

名称	类型	含义
`id`在路径中	`string`必填	事件中的 id（`data.interaction`）。
`text`在正文中	`string`可选	帖子、回复或私信的文字。
`private`在正文中	`boolean`可选	`true`：只有使用该命令或按钮的人能看到回复，为期一天。
`card`在正文中	`object`可选	卡片 `{ title, text, color, fields: [{ name, value }] }`，最多 10 个字段。
`buttons`在正文中	`object[]`可选	最多 5 个按钮，每个为 `{ id, label, style }`，`style` 为 `primary`、`secondary` 或 `danger`。按下会作为 `interaction` 事件送达。

请求示例

curl -X POST \
  -H "Authorization: Bearer tm_key_…" \
  -H "Content-Type: application/json" \
  -d '{"text":"You rolled a 4.","private":true}' \
  "https://api.tellmelo.com/v2/interactions/9b8c7d6e-5f4a-4b3c-8d2e-1f0a9b8c7d6e/reply"

响应

返回一个 Made。

示例

{
  "id": "0d9c8b7a-6f5e-4d3c-2b1a-0f9e8d7c6b5a"
}

可能的状态： 200400401403404429

POST`/v2/channels/{id}/voice`

在语音频道中占一个位置来播放音乐或声音。

权限 write
自 v2.20

仅限机器人的令牌，以其在频道中的身份组所允许为限。程序通过 LiveKit SDK 连接，并将声音作为麦克风发送；每个人自行调节其音量。

参数

名称	类型	含义
`id`在路径中	`string`必填	频道的 `id`。

请求示例

curl -X POST \
  -H "Authorization: Bearer tm_key_…" \
  "https://api.tellmelo.com/v2/channels/0d9c8b7a-6f5e-4d3c-2b1a-0f9e8d7c6b5a/voice"

响应

返回一个 VoiceSeat。

示例

{
  "url": "wss://voice.example.org",
  "token": "eyJhbGciOiJIUzI1NiJ9…",
  "iceServers": [
    {
      "urls": [
        "stun:turn.example.org:3478"
      ]
    }
  ],
  "speak": true,
  "video": false
}

可能的状态： 200400401403404429

发现

趋势、搜索和本站自定义表情。

GET`/v2/tags`

当前流行的标签。

权限 read
带 ETag
自 v2.0

按分数最多 10 个热门标签：每次使用计 1 分，每 3 天减半，同一账号每天最多计 3 分。posts 是四舍五入后的分数。limit 只会缩短列表。团队推荐的标签可能排得更靠前。

参数

名称	类型	含义
`limit`在查询中	`integer`可选	每页条目数：默认 20，最多 50。

请求示例

curl \
  -H "Authorization: Bearer tm_key_…" \
  "https://api.tellmelo.com/v2/tags?limit=10"

响应

返回一页 Tag，形式为 `items` 和 `next`。

示例

{
  "items": [
    {
      "tag": "garden",
      "posts": 58
    }
  ],
  "next": null
}

可能的状态： 200304401429

GET`/v2/search`

在帖子、名字、短名称和标签中搜索。

权限 read
带 ETag
自 v2.0

只搜索公开内容：群组外的帖子、个人主页和标签。limit 对每类分别生效。

参数

名称	类型	含义
`q`在查询中	`string`必填	要搜索的词。
`type`在查询中	`string`可选	哪种结果。不传则返回所有类型。`allpostsprofilestags`
`limit`在查询中	`integer`可选	每页条目数：默认 20，最多 50。

请求示例

curl \
  -H "Authorization: Bearer tm_key_…" \
  "https://api.tellmelo.com/v2/search?q=garden&type=posts"

响应

返回一个 SearchResult。

示例

{
  "posts": [
    {
      "id": "5f0c2a9e-8d41-4b7a-9c3e-2e61d0f4a7b1",
      "text": "The bees are back in the garden 🐝 #garden",
      "kind": "poll",
      "author": {
        "id": "a3e1f7c2-54b9-4d0e-8f16-7b2c9d4e1a05",
        "handle": "mara",
        "name": "Mara 🌻",
        "verified": true,
        "accountKind": "person"
      },
      "community": {
        "id": "c81d4e2a-0f3b-4a6c-9e57-1d2b3c4a5f60",
        "name": "Urban Gardening"
      },
      "media": [
        {
          "url": "/api/media?id=b2d7e9f1-3c4a-4e8b-a1f0-6d5c4b3a2918",
          "kind": "image",
          "poster": null,
          "ai": "without"
        }
      ],
      "poll": {
        "options": [
          {
            "text": "Lavender",
            "votes": 12
          },
          {
            "text": "Sunflowers",
            "votes": 7
          },
          {
            "text": "Clover",
            "votes": 3
          }
        ],
        "total": 22,
        "multiple": false,
        "endsAt": null,
        "running": true,
        "resultsVisible": true,
        "myVotes": [
          0
        ]
      },
      "quotes": null,
      "continues": null,
      "counts": {
        "replies": 4,
        "likes": 31,
        "reposts": 2
      },
      "pinned": false,
      "giftDrop": {
        "item": "plan",
        "quantity": 3,
        "places": 10,
        "left": 4,
        "audience": "followers",
        "newAccounts": false,
        "status": "open",
        "claimed": true
      },
      "createdAt": 1758624000000
    }
  ],
  "profiles": [
    {
      "id": "a3e1f7c2-54b9-4d0e-8f16-7b2c9d4e1a05",
      "handle": "mara",
      "name": "Mara 🌻",
      "verified": true,
      "accountKind": "person"
    }
  ],
  "tags": [
    {
      "tag": "garden",
      "posts": 58
    }
  ]
}

可能的状态： 200304400401429

GET`/v2/emojis`

本站自定义表情及其图片地址。

权限 read
带 ETag
自 v2.1

在文本中，表情显示为 :name:。用此列表中的图片替换；未知名称保持为文本。

请求示例

curl \
  -H "Authorization: Bearer tm_key_…" \
  "https://api.tellmelo.com/v2/emojis"

响应

返回一页 Emoji，形式为 `items` 和 `next`。

示例

{
  "items": [
    {
      "name": "tellmelo",
      "url": "/api/media?id=e1f2a3b4-c5d6-4e7f-8a9b-0c1d2e3f4a5b"
    }
  ],
  "next": null
}

可能的状态： 200304401429

GIF 和视频

媒体库：查找已分享的 GIF 和视频，上传和管理你自己的内容，并嵌入到其他网站上。

GET`/v2/media`

已分享的 GIF 或视频，最常用的排在前面。

权限 read
可分页
带 ETag
自 v2.14

不包括你屏蔽的账号或屏蔽了你的账号。用于 tellmelo 上的帖子时，用请求头中的密钥加载 url 和 poster。

用于其他网站的只有带 embed 的内容：它的地址无需密钥，在任何浏览器中都能使用。

参数

名称	类型	含义
`kind`在查询中	`string`可选	`gif` 或 `video`；未指定时为 `gif`。`gifvideo`
`q`在查询中	`string`可选	名称或关键词中包含的词。
`anywhere`在查询中	`boolean`可选	`true`：仅限也允许出现在其他网站上的内容。
`limit`在查询中	`integer`可选	每页条目数：默认 20，最多 50。
`cursor`在查询中	`string`可选	上一个响应中的 `next`。不传则从头开始。

请求示例

curl \
  -H "Authorization: Bearer tm_key_…" \
  "https://api.tellmelo.com/v2/media?kind=gif&q=bees&anywhere=true&limit=20"

响应

返回一页 MediaItem，形式为 `items` 和 `next`。

示例

{
  "items": [
    {
      "id": "b2d7e9f1-3c4a-4e8b-a1f0-6d5c4b3a2918",
      "kind": "gif",
      "name": "Happy bees",
      "keywords": "bees garden happy",
      "width": 480,
      "height": 270,
      "seconds": 0,
      "url": "/api/media?id=b2d7e9f1-3c4a-4e8b-a1f0-6d5c4b3a2918",
      "poster": "/api/media?id=b2d7e9f1-3c4a-4e8b-a1f0-6d5c4b3a2918&poster=1",
      "uploader": {
        "handle": "mara",
        "name": "Mara 🌻"
      },
      "mine": false,
      "shared": true,
      "anywhere": true,
      "embed": {
        "page": "https://tellmelo.com/media-embed/b2d7e9f1-3c4a-4e8b-a1f0-6d5c4b3a2918",
        "file": "https://tellmelo.com/media-embed/b2d7e9f1-3c4a-4e8b-a1f0-6d5c4b3a2918/file",
        "poster": "https://tellmelo.com/media-embed/b2d7e9f1-3c4a-4e8b-a1f0-6d5c4b3a2918/poster",
        "code": "<iframe src=\"https://tellmelo.com/media-embed/b2d7e9f1-3c4a-4e8b-a1f0-6d5c4b3a2918\" width=\"480\" height=\"300\" title=\"Happy bees\" style=\"border:0;max-width:100%\" loading=\"lazy\" allowfullscreen></iframe>"
      }
    }
  ],
  "next": "MTc1ODYyNDAwMDAwMDo1ZjBjMmE5ZS04ZDQx"
}

可能的状态： 200304400401429

GET`/v2/media/mine`

你自己的媒体库，最新的排在前面。

权限 media
可分页
带 ETag
自 v2.14

参数

名称	类型	含义
`kind`在查询中	`string`可选	`gif` 或 `video`；未指定时为 `gif`。`gifvideo`
`q`在查询中	`string`可选	名称或关键词中包含的词。
`limit`在查询中	`integer`可选	每页条目数：默认 20，最多 50。
`cursor`在查询中	`string`可选	上一个响应中的 `next`。不传则从头开始。

请求示例

curl \
  -H "Authorization: Bearer tm_key_…" \
  "https://api.tellmelo.com/v2/media/mine?kind=gif&q=bees&limit=20"

响应

返回一页 MediaItem，形式为 `items` 和 `next`。

示例

{
  "items": [
    {
      "id": "b2d7e9f1-3c4a-4e8b-a1f0-6d5c4b3a2918",
      "kind": "gif",
      "name": "Happy bees",
      "keywords": "bees garden happy",
      "width": 480,
      "height": 270,
      "seconds": 0,
      "url": "/api/media?id=b2d7e9f1-3c4a-4e8b-a1f0-6d5c4b3a2918",
      "poster": "/api/media?id=b2d7e9f1-3c4a-4e8b-a1f0-6d5c4b3a2918&poster=1",
      "uploader": {
        "handle": "mara",
        "name": "Mara 🌻"
      },
      "mine": false,
      "shared": true,
      "anywhere": true,
      "embed": {
        "page": "https://tellmelo.com/media-embed/b2d7e9f1-3c4a-4e8b-a1f0-6d5c4b3a2918",
        "file": "https://tellmelo.com/media-embed/b2d7e9f1-3c4a-4e8b-a1f0-6d5c4b3a2918/file",
        "poster": "https://tellmelo.com/media-embed/b2d7e9f1-3c4a-4e8b-a1f0-6d5c4b3a2918/poster",
        "code": "<iframe src=\"https://tellmelo.com/media-embed/b2d7e9f1-3c4a-4e8b-a1f0-6d5c4b3a2918\" width=\"480\" height=\"300\" title=\"Happy bees\" style=\"border:0;max-width:100%\" loading=\"lazy\" allowfullscreen></iframe>"
      }
    }
  ],
  "next": "MTc1ODYyNDAwMDAwMDo1ZjBjMmE5ZS04ZDQx"
}

可能的状态： 200304400401403429

GET`/v2/media/{id}`

一个 GIF 或视频，你自己的或已分享的。

权限 read
带 ETag
自 v2.14

参数

名称	类型	含义
`id`在路径中	`string`必填	GIF 或视频的 ID。

请求示例

curl \
  -H "Authorization: Bearer tm_key_…" \
  "https://api.tellmelo.com/v2/media/b2d7e9f1-3c4a-4e8b-a1f0-6d5c4b3a2918"

响应

返回一个 MediaItem。

示例

{
  "id": "b2d7e9f1-3c4a-4e8b-a1f0-6d5c4b3a2918",
  "kind": "gif",
  "name": "Happy bees",
  "keywords": "bees garden happy",
  "width": 480,
  "height": 270,
  "seconds": 0,
  "url": "/api/media?id=b2d7e9f1-3c4a-4e8b-a1f0-6d5c4b3a2918",
  "poster": "/api/media?id=b2d7e9f1-3c4a-4e8b-a1f0-6d5c4b3a2918&poster=1",
  "uploader": {
    "handle": "mara",
    "name": "Mara 🌻"
  },
  "mine": false,
  "shared": true,
  "anywhere": true,
  "embed": {
    "page": "https://tellmelo.com/media-embed/b2d7e9f1-3c4a-4e8b-a1f0-6d5c4b3a2918",
    "file": "https://tellmelo.com/media-embed/b2d7e9f1-3c4a-4e8b-a1f0-6d5c4b3a2918/file",
    "poster": "https://tellmelo.com/media-embed/b2d7e9f1-3c4a-4e8b-a1f0-6d5c4b3a2918/poster",
    "code": "<iframe src=\"https://tellmelo.com/media-embed/b2d7e9f1-3c4a-4e8b-a1f0-6d5c4b3a2918\" width=\"480\" height=\"300\" title=\"Happy bees\" style=\"border:0;max-width:100%\" loading=\"lazy\" allowfullscreen></iframe>"
  }
}

可能的状态： 200304400401404429

POST`/v2/media/uploads`

开始上传。

权限 media
自 v2.14

然后把文件分成每块最多 piece 字节，发送到 /media/uploads/{upload}。如果没有新的块，上传会在 15 分钟后结束。

适用 App 的限制：GIF 最大 15 MB，视频的大小和时长取决于订阅，每天的 GIF 数量，私密 GIF，每周的视频点数。否则会返回 409、413 或 429。

参数

名称	类型	含义
`kind`在正文中	`string`必填	`gif` 或 `video`；未指定时为 `gif`。`gifvideo`
`size`在正文中	`integer`必填	整个文件的大小，以字节为单位。
`name`在正文中	`string`必填	用于查找的名称：2 到 40 个字符。
`keywords`在正文中	`string`可选	用于搜索的关键词，以空格分隔。
`shared`在正文中	`boolean`可选	`true`：在 tellmelo 上与所有人分享。
`anywhere`在正文中	`boolean`可选	`true`：已分享，并且允许在其他网站上使用。只能与 `shared` 一起使用。

请求示例

curl -X POST \
  -H "Authorization: Bearer tm_key_…" \
  -H "Content-Type: application/json" \
  -d '{"kind":"gif","size":2400000,"name":"Happy bees","keywords":"bees garden","shared":true,"anywhere":false}' \
  "https://api.tellmelo.com/v2/media/uploads"

响应

返回一个 UploadStarted。

示例

{
  "upload": "e7c1a2b3-4d5e-4f60-8a9b-0c1d2e3f4a5b",
  "piece": 4194304
}

可能的状态： 200400401403429

PUT`/v2/media/uploads/{upload}`

发送文件的一块。

权限 media
自 v2.14

请求体就是这一块本身（application/octet-stream），不是 JSON。如果衔接不上，会返回 409 和 received：从那里继续发送。最后一块之后文件会被转换；这时响应中包含 item。

参数

名称	类型	含义
`upload`在路径中	`string`必填	开始上传时得到的 `upload`。
`offset`在查询中	`integer`必填	这一块在文件中的起始位置，以字节为单位；第一块为 `0`。

请求示例

curl -X PUT \
  -H "Authorization: Bearer tm_key_…" \
  -H "Content-Type: application/octet-stream" \
  --data-binary @piece \
  "https://api.tellmelo.com/v2/media/uploads/e7c1a2b3-4d5e-4f60-8a9b-0c1d2e3f4a5b?offset=0"

响应

返回一个 UploadPiece。

示例

{
  "received": 4194304,
  "item": null
}

可能的状态： 200400401403404429

POST`/v2/media/{id}`

修改你的一个 GIF 或视频。

权限 media
自 v2.14

参数

名称	类型	含义
`id`在路径中	`string`必填	GIF 或视频的 ID。
`name`在正文中	`string`可选	用于查找的名称：2 到 40 个字符。
`keywords`在正文中	`string`可选	用于搜索的关键词，以空格分隔。
`shared`在正文中	`boolean`可选	`true`：在 tellmelo 上与所有人分享。
`anywhere`在正文中	`boolean`可选	`true`：已分享，并且允许在其他网站上使用。只能与 `shared` 一起使用。

请求示例

curl -X POST \
  -H "Authorization: Bearer tm_key_…" \
  -H "Content-Type: application/json" \
  -d '{"name":"Happy bees","anywhere":true}' \
  "https://api.tellmelo.com/v2/media/b2d7e9f1-3c4a-4e8b-a1f0-6d5c4b3a2918"

响应

返回一个 Ok。

示例

{
  "ok": true
}

可能的状态： 200400401403404429

DELETE`/v2/media/{id}`

删除你的一个 GIF 或视频。

权限 media
自 v2.14

已经展示它的帖子会保留它。在其他网站上，它会在几分钟内消失。

参数

名称	类型	含义
`id`在路径中	`string`必填	GIF 或视频的 ID。

请求示例

curl -X DELETE \
  -H "Authorization: Bearer tm_key_…" \
  "https://api.tellmelo.com/v2/media/b2d7e9f1-3c4a-4e8b-a1f0-6d5c4b3a2918"

响应

返回一个 Ok。

示例

{
  "ok": true
}

可能的状态： 200400401403404429

你的账号

你的主页、你的动态、你自己的表情和你的 Webhook。

GET`/v2/me`

你自己的个人主页，包含其他路径需要的 id。

权限 read
带 ETag
自 v2.0

请求示例

curl \
  -H "Authorization: Bearer tm_key_…" \
  "https://api.tellmelo.com/v2/me"

响应

返回一个 Profile。

示例

{
  "id": "a3e1f7c2-54b9-4d0e-8f16-7b2c9d4e1a05",
  "handle": "mara",
  "name": "Mara 🌻",
  "verified": true,
  "accountKind": "person",
  "about": "Beekeeper, allotment, too many seeds. :tellmelo:",
  "website": "https://mara-imkerei.example/",
  "websiteVerified": true,
  "followers": 148,
  "createdAt": 1750848000000
}

可能的状态： 200304401429

GET`/v2/feed`

你自己的动态，与应用中的排列方式相同。

权限 read
可分页
自 v2.0

没有 ETag，因为顺序一直在变。你已开始的列表在结束前保持不变。

参数

名称	类型	含义
`tab`在查询中	`string`可选	哪个动态：`for-you`、`following`、`latest` 或 `bookmarks`。默认 `latest`。`for-youfollowinglatestbookmarks`
`tag`在查询中	`string`可选	只返回与此标签有关的帖子：用它写的或服务器在其中识别出的。不传则不过滤。
`limit`在查询中	`integer`可选	每页条目数：默认 20，最多 50。
`cursor`在查询中	`string`可选	上一个响应中的 `next`。不传则从头开始。

请求示例

curl \
  -H "Authorization: Bearer tm_key_…" \
  "https://api.tellmelo.com/v2/feed?tab=following&limit=20"

响应

返回一页 Post，形式为 `items` 和 `next`。

示例

{
  "items": [
    {
      "id": "5f0c2a9e-8d41-4b7a-9c3e-2e61d0f4a7b1",
      "text": "The bees are back in the garden 🐝 #garden",
      "kind": "poll",
      "author": {
        "id": "a3e1f7c2-54b9-4d0e-8f16-7b2c9d4e1a05",
        "handle": "mara",
        "name": "Mara 🌻",
        "verified": true,
        "accountKind": "person"
      },
      "community": {
        "id": "c81d4e2a-0f3b-4a6c-9e57-1d2b3c4a5f60",
        "name": "Urban Gardening"
      },
      "media": [
        {
          "url": "/api/media?id=b2d7e9f1-3c4a-4e8b-a1f0-6d5c4b3a2918",
          "kind": "image",
          "poster": null,
          "ai": "without"
        }
      ],
      "poll": {
        "options": [
          {
            "text": "Lavender",
            "votes": 12
          },
          {
            "text": "Sunflowers",
            "votes": 7
          },
          {
            "text": "Clover",
            "votes": 3
          }
        ],
        "total": 22,
        "multiple": false,
        "endsAt": null,
        "running": true,
        "resultsVisible": true,
        "myVotes": [
          0
        ]
      },
      "quotes": null,
      "continues": null,
      "counts": {
        "replies": 4,
        "likes": 31,
        "reposts": 2
      },
      "pinned": false,
      "giftDrop": {
        "item": "plan",
        "quantity": 3,
        "places": 10,
        "left": 4,
        "audience": "followers",
        "newAccounts": false,
        "status": "open",
        "claimed": true
      },
      "createdAt": 1758624000000
    }
  ],
  "next": "MTc1ODYyNDAwMDAwMDo1ZjBjMmE5ZS04ZDQx"
}

可能的状态： 200400401429

POST`/v2/me/pictures`

以字节形式上传一张图片。返回 id 和 url；之后用这个 id 作为头像、封面或用在帖子里。

权限 write
自 v2.19

PNG、JPEG、WebP 或 GIF，按前几个字节识别；去除元数据后重新保存。未被任何地方使用的图片稍后会被删除。

请求示例

curl -X POST \
  -H "Authorization: Bearer tm_key_…" \
  -H "Content-Type: application/octet-stream" \
  --data-binary @picture.png \
  "https://api.tellmelo.com/v2/me/pictures"

响应

返回一个 Picture。

示例

{
  "id": "8c7b6a59-4837-4261-9f5e-d4c3b2a1f0e9",
  "url": "/api/media?id=8c7b6a59-4837-4261-9f5e-d4c3b2a1f0e9"
}

可能的状态： 200401403429

PUT`/v2/me/profile`

修改你的主页：名称、简介、头像、封面和主页颜色。未提供的项目保持不变。

权限 profile
自 v2.19

需要 profile 权限。你的 @用户名只能在应用中修改：它也是你的登录名。

参数

名称	类型	含义
`name`在正文中	`string`可选	显示名称，最多 60 个字符。
`about`在正文中	`string`可选	“简介”文字。
`avatar`在正文中	`string`可选	作为头像的已上传图片 `id`。留空则移除。
`banner`在正文中	`string`可选	作为封面的已上传图片 `id`。留空则移除。
`color`在正文中	`string`可选	主页颜色，需要套餐。`null` 移除。`indigovioletrosecoralamberlimegreentealskyslatesandnight`

请求示例

curl -X PUT \
  -H "Authorization: Bearer tm_key_…" \
  -H "Content-Type: application/json" \
  -d '{"name":"Mara 🌻","about":"Gardening in the city.","avatar":"8c7b6a59-4837-4261-9f5e-d4c3b2a1f0e9"}' \
  "https://api.tellmelo.com/v2/me/profile"

响应

返回一个 Ok。

示例

{
  "ok": true
}

可能的状态： 200400401403429

GET`/v2/me/emojis`

你自己的表情。

权限 read
带 ETag
自 v2.19

请求示例

curl \
  -H "Authorization: Bearer tm_key_…" \
  "https://api.tellmelo.com/v2/me/emojis"

响应

返回一页 OwnEmoji，形式为 `items` 和 `next`。

示例

{
  "items": [
    {
      "name": "sunflower",
      "url": "/api/media?id=8c7b6a59-4837-4261-9f5e-d4c3b2a1f0e9",
      "animated": false,
      "resting": false
    }
  ],
  "next": null
}

可能的状态： 200304401429

POST`/v2/me/emojis/pictures`

以字节形式上传自定义表情的图片。

权限 profile
自 v2.19

动态表情需要套餐。转换后过大的图片会被拒绝。

请求示例

curl -X POST \
  -H "Authorization: Bearer tm_key_…" \
  -H "Content-Type: application/octet-stream" \
  --data-binary @picture.png \
  "https://api.tellmelo.com/v2/me/emojis/pictures"

响应

返回一个 EmojiPicture。

示例

{
  "id": "8c7b6a59-4837-4261-9f5e-d4c3b2a1f0e9",
  "url": "/api/media?id=8c7b6a59-4837-4261-9f5e-d4c3b2a1f0e9",
  "animated": false
}

可能的状态： 200401403429

POST`/v2/me/emojis`

创建一个自定义表情。返回你的全部表情。

权限 profile
自 v2.19

能创建多少表情取决于你的套餐。

参数

名称	类型	含义
`name`在正文中	`string`必填	书写表情时用的名称，形如 `:名称:`。
`picture`在正文中	`string`必填	来自 `POST /me/emojis/pictures` 的 `id`。

请求示例

curl -X POST \
  -H "Authorization: Bearer tm_key_…" \
  -H "Content-Type: application/json" \
  -d '{"name":"sunflower","picture":"8c7b6a59-4837-4261-9f5e-d4c3b2a1f0e9"}' \
  "https://api.tellmelo.com/v2/me/emojis"

响应

返回一页 OwnEmoji，形式为 `items` 和 `next`。

示例

{
  "items": [
    {
      "name": "sunflower",
      "url": "/api/media?id=8c7b6a59-4837-4261-9f5e-d4c3b2a1f0e9",
      "animated": false,
      "resting": false
    }
  ],
  "next": null
}

可能的状态： 200400401403429

DELETE`/v2/me/emojis/{name}`

删除一个自定义表情。返回剩下的表情。

权限 profile
自 v2.19

参数

名称	类型	含义
`name`在路径中	`string`必填	表情名称，不带冒号。

请求示例

curl -X DELETE \
  -H "Authorization: Bearer tm_key_…" \
  "https://api.tellmelo.com/v2/me/emojis/sunflower"

响应

返回一页 OwnEmoji，形式为 `items` 和 `next`。

示例

{
  "items": [
    {
      "name": "sunflower",
      "url": "/api/media?id=8c7b6a59-4837-4261-9f5e-d4c3b2a1f0e9",
      "animated": false,
      "resting": false
    }
  ],
  "next": null
}

可能的状态： 200400401403404429

PUT`/v2/me/emojis/sharing`

设置你的粉丝能否在自己的文字中使用你的表情。

权限 profile
自 v2.19

参数

名称	类型	含义
`shared`在正文中	`boolean`必填	`true` 与粉丝共享你的表情，`false` 不共享。

请求示例

curl -X PUT \
  -H "Authorization: Bearer tm_key_…" \
  -H "Content-Type: application/json" \
  -d '{"shared":true}' \
  "https://api.tellmelo.com/v2/me/emojis/sharing"

响应

返回一个 Ok。

示例

{
  "ok": true
}

可能的状态： 200400401403429

GET`/v2/me/webhooks`

你的 Webhook 及其状态。

权限 webhooks
带 ETag
自 v2.19

需要 webhooks 权限。Webhook 随组织套餐提供，或面向合作伙伴。

请求示例

curl \
  -H "Authorization: Bearer tm_key_…" \
  "https://api.tellmelo.com/v2/me/webhooks"

响应

返回一页 Webhook，形式为 `items` 和 `next`。

示例

{
  "items": [
    {
      "id": "1f2e3d4c-5b6a-4798-8a7b-6c5d4e3f2a1b",
      "url": "https://example.org/tellmelo-hook",
      "kinds": [
        "reply",
        "mention"
      ],
      "active": true,
      "lastStatus": 200,
      "lastAt": 1758624000000,
      "failures": 0
    }
  ],
  "next": null
}

可能的状态： 200304401403429

POST`/v2/me/webhooks`

创建 Webhook。返回 id 和签名用的密钥，仅此一次。

权限 webhooks
自 v2.19

每次推送都用密钥签名（X-Tellmelo-Signature）。请妥善保存；不会再次显示。

参数

名称	类型	含义
`url`在正文中	`string`必填	本地网络之外的 HTTPS 地址，不含凭据。
`kinds`在正文中	`string[]`必填	Webhook 接收哪些通知。可用的类型取决于你的套餐和合作伙伴身份。`replymentiongroup_mentionfollowlikerepostmessagequota_changedquota_giftdrop_claimeddrop_empty`

请求示例

curl -X POST \
  -H "Authorization: Bearer tm_key_…" \
  -H "Content-Type: application/json" \
  -d '{"url":"https://example.org/tellmelo-hook","kinds":["reply","mention"]}' \
  "https://api.tellmelo.com/v2/me/webhooks"

响应

返回一个 WebhookCreated。

示例

{
  "id": "1f2e3d4c-5b6a-4798-8a7b-6c5d4e3f2a1b",
  "secret": "whsec_3f9a…"
}

可能的状态： 200400401403429

DELETE`/v2/me/webhooks/{id}`

删除 Webhook。

权限 webhooks
自 v2.19

参数

名称	类型	含义
`id`在路径中	`string`必填	Webhook 的 `id`。

请求示例

curl -X DELETE \
  -H "Authorization: Bearer tm_key_…" \
  "https://api.tellmelo.com/v2/me/webhooks/1f2e3d4c-5b6a-4798-8a7b-6c5d4e3f2a1b"

响应

返回一个 Ok。

示例

{
  "ok": true
}

可能的状态： 200400401403404429

POST`/v2/me/webhooks/{id}/test`

向 Webhook 发送测试。

权限 webhooks
自 v2.19

参数

名称	类型	含义
`id`在路径中	`string`必填	Webhook 的 `id`。

请求示例

curl -X POST \
  -H "Authorization: Bearer tm_key_…" \
  "https://api.tellmelo.com/v2/me/webhooks/1f2e3d4c-5b6a-4798-8a7b-6c5d4e3f2a1b/test"

响应

返回一个 Ok。

示例

{
  "ok": true
}

可能的状态： 200400401403404429

通知

你的账号周围发生了什么，逐页查看。

GET`/v2/notifications`

你的通知，最新的在前。

权限 read
可分页
带 ETag
自 v2.0

读取不会将任何内容标为已读；POST /notifications/read 才会。同一帖子上的同类事件共用一行；more 表示数量。

参数

名称	类型	含义
`limit`在查询中	`integer`可选	每页条目数：默认 20，最多 50。
`cursor`在查询中	`string`可选	上一个响应中的 `next`。不传则从头开始。

请求示例

curl \
  -H "Authorization: Bearer tm_key_…" \
  "https://api.tellmelo.com/v2/notifications?limit=20"

响应

返回一页 Notification，形式为 `items` 和 `next`。

示例

{
  "items": [
    {
      "id": "3f2e1d0c-9b8a-4765-8432-10fedcba9876",
      "kind": "like",
      "text": null,
      "actor": {
        "handle": "jon",
        "name": "Jon"
      },
      "postId": "5f0c2a9e-8d41-4b7a-9c3e-2e61d0f4a7b1",
      "read": false,
      "more": 2,
      "createdAt": 1758624300000,
      "updatedAt": 1758624900000
    }
  ],
  "next": "MTc1ODYyNDAwMDAwMDo1ZjBjMmE5ZS04ZDQx"
}

可能的状态： 200304401429

POST`/v2/notifications/read`

将你的通知标为已读。

权限 write
自 v2.0

请求示例

curl -X POST \
  -H "Authorization: Bearer tm_key_…" \
  "https://api.tellmelo.com/v2/notifications/read"

响应

返回一个 Ok。

示例

{
  "ok": true
}

可能的状态： 200401403429

私信

你的收件箱和对话。对话以对方账号命名。

GET`/v2/conversations`

你的收件箱：每个对话一行，最新的在前。

权限 read
可分页
带 ETag
自 v2.0

参数

名称	类型	含义
`limit`在查询中	`integer`可选	每页条目数：默认 20，最多 50。
`cursor`在查询中	`string`可选	上一个响应中的 `next`。不传则从头开始。

请求示例

curl \
  -H "Authorization: Bearer tm_key_…" \
  "https://api.tellmelo.com/v2/conversations?limit=20"

响应

返回一页 Conversation，形式为 `items` 和 `next`。

示例

{
  "items": [
    {
      "with": "d4c3b2a1-6e5f-4a7b-9c8d-1e2f3a4b5c6d",
      "handle": "jon",
      "name": "Jon",
      "excerpt": "See you on Saturday at the market!",
      "truncated": false,
      "fromMe": true,
      "lastMessageId": "7c6b5a49-3827-4165-9f0e-d1c2b3a49586",
      "unread": 0,
      "updatedAt": 1758624060000
    }
  ],
  "next": "MTc1ODYyNDAwMDAwMDo1ZjBjMmE5ZS04ZDQx"
}

可能的状态： 200304401429

GET`/v2/conversations/{with}/messages`

某个对话中的私信，最新的在前。

权限 read
可分页
带 ETag
自 v2.0

读取不会将任何内容标为已读；POST /conversations/{with}/read 才会。

参数

名称	类型	含义
`with`在路径中	`string`必填	另一个账号的 `id`。对话本身没有 `id`。
`limit`在查询中	`integer`可选	每页条目数：默认 20，最多 50。
`cursor`在查询中	`string`可选	上一个响应中的 `next`。不传则从头开始。

请求示例

curl \
  -H "Authorization: Bearer tm_key_…" \
  "https://api.tellmelo.com/v2/conversations/a3e1f7c2-54b9-4d0e-8f16-7b2c9d4e1a05/messages?limit=20"

响应

返回一页 Message，形式为 `items` 和 `next`。

示例

{
  "items": [
    {
      "id": "7c6b5a49-3827-4165-9f0e-d1c2b3a49586",
      "text": "See you on Saturday at the market!",
      "from": "a3e1f7c2-54b9-4d0e-8f16-7b2c9d4e1a05",
      "to": "d4c3b2a1-6e5f-4a7b-9c8d-1e2f3a4b5c6d",
      "read": true,
      "media": [],
      "replyTo": null,
      "createdAt": 1758624060000
    }
  ],
  "next": "MTc1ODYyNDAwMDAwMDo1ZjBjMmE5ZS04ZDQx"
}

可能的状态： 200304400401404429

POST`/v2/conversations/{with}/messages`

在对话中发送私信。

权限 write
自 v2.0

适用应用的规则：屏蔽了你的人无法联系，对方的设置也会生效。

无法通过 API 给私信附加图片、GIF 或视频，只能在应用中操作。

参数

名称	类型	含义
`with`在路径中	`string`必填	另一个账号的 `id`。对话本身没有 `id`。
`text`在正文中	`string`必填	帖子、回复或私信的文字。
`replyTo`在正文中	`string`可选	本条私信所回复的本对话中较早私信的 `id`。自 2.2 起。

请求示例

curl -X POST \
  -H "Authorization: Bearer tm_key_…" \
  -H "Content-Type: application/json" \
  -d '{"text":"See you on Saturday at the market!"}' \
  "https://api.tellmelo.com/v2/conversations/a3e1f7c2-54b9-4d0e-8f16-7b2c9d4e1a05/messages"

响应

返回一个 Ok。

示例

{
  "ok": true
}

可能的状态： 200400401403404429

POST`/v2/conversations/{with}/read`

将某个对话的所有私信标为已读。

权限 write
自 v2.1

参数

名称	类型	含义
`with`在路径中	`string`必填	另一个账号的 `id`。对话本身没有 `id`。

请求示例

curl -X POST \
  -H "Authorization: Bearer tm_key_…" \
  "https://api.tellmelo.com/v2/conversations/a3e1f7c2-54b9-4d0e-8f16-7b2c9d4e1a05/read"

响应

返回一个 Ok。

示例

{
  "ok": true
}

可能的状态： 200400401403404429

DELETE`/v2/conversations/{with}/messages/{id}`

删除你的某条私信。

权限 write
自 v2.12

仅限你自己的私信，且仅在发送后 24 小时内。

参数

名称	类型	含义
`with`在路径中	`string`必填	另一个账号的 `id`。对话本身没有 `id`。
`id`在路径中	`string`必填	私信的 id。

请求示例

curl -X DELETE \
  -H "Authorization: Bearer tm_key_…" \
  "https://api.tellmelo.com/v2/conversations/a3e1f7c2-54b9-4d0e-8f16-7b2c9d4e1a05/messages/7c6b5a49-3827-4165-9f0e-d1c2b3a49586"

响应

返回一个 Ok。

示例

{
  "ok": true
}

可能的状态： 200400401403404429

POST`/v2/conversations/{with}/planned`

定时稍后发送一条私信。返回定时私信的 id。

权限 write
自 v2.19

需要包含定时私信的套餐，否则返回 403。双方都开启端到端加密时，只能在应用中使用。

参数

名称	类型	含义
`with`在路径中	`string`必填	另一个账号的 `id`。对话本身没有 `id`。
`text`在正文中	`string`必填	帖子、回复或私信的文字。
`sendAt`在正文中	`integer`必填	私信发送的时间，以 1970 年起的毫秒数表示。

请求示例

curl -X POST \
  -H "Authorization: Bearer tm_key_…" \
  -H "Content-Type: application/json" \
  -d '{"text":"Happy birthday! 🎂","sendAt":1758700000000}' \
  "https://api.tellmelo.com/v2/conversations/a3e1f7c2-54b9-4d0e-8f16-7b2c9d4e1a05/planned"

响应

返回一个 Made。

示例

{
  "id": "0d9c8b7a-6f5e-4d3c-2b1a-0f9e8d7c6b5a"
}

可能的状态： 200400401403404429

GET`/v2/me/planned-messages`

你尚未发送的定时私信，按时间排序。

权限 read
带 ETag
自 v2.19

参数

名称	类型	含义
`with`在查询中	`string`可选	只看发给这个账号的私信（它的 `id`）。

请求示例

curl \
  -H "Authorization: Bearer tm_key_…" \
  "https://api.tellmelo.com/v2/me/planned-messages"

响应

返回一页 PlannedMessage，形式为 `items` 和 `next`。

示例

{
  "items": [
    {
      "id": "3b2a1c0d-9e8f-4a7b-b6c5-d4e3f2a1b0c9",
      "to": "a3e1f7c2-54b9-4d0e-8f16-7b2c9d4e1a05",
      "text": "Happy birthday! 🎂",
      "sendAt": 1758710400000,
      "state": "waiting"
    }
  ],
  "next": null
}

可能的状态： 200304401429

POST`/v2/me/planned-messages/{id}/send`

立即发送一条被暂缓或发送失败的定时私信。

权限 write
自 v2.19

参数

名称	类型	含义
`id`在路径中	`string`必填	定时私信的 `id`。

请求示例

curl -X POST \
  -H "Authorization: Bearer tm_key_…" \
  "https://api.tellmelo.com/v2/me/planned-messages/3b2a1c0d-9e8f-4a7b-b6c5-d4e3f2a1b0c9/send"

响应

返回一个 Ok。

示例

{
  "ok": true
}

可能的状态： 200400401403404429

DELETE`/v2/me/planned-messages/{id}`

在发送前删除一条定时私信。

权限 write
自 v2.19

参数

名称	类型	含义
`id`在路径中	`string`必填	定时私信的 `id`。

请求示例

curl -X DELETE \
  -H "Authorization: Bearer tm_key_…" \
  "https://api.tellmelo.com/v2/me/planned-messages/3b2a1c0d-9e8f-4a7b-b6c5-d4e3f2a1b0c9"

响应

返回一个 Ok。

示例

{
  "ok": true
}

可能的状态： 200400401403404429

关系

点赞、收藏、转发、关注、加入、屏蔽：同一个路径，用 active 设置和解除。自 2.19 起也有列表：粉丝、关注，以及你自己的屏蔽和静音。

POST`/v2/relations`

点赞、收藏、转发、关注、加入、屏蔽、静音，取决于 kind。

权限 write
自 v2.0

对 like、save 和 repost，target 是帖子；对 join 是群组；对 follow、block 和 mute 是账号。active: false 解除关系。

参数

名称	类型	含义
`kind`在正文中	`string`必填	哪种关系：`like`、`save`、`repost`、`follow`、`join`、`block` 或 `mute`（自 2.2 起）。`likesaverepostfollowjoinblockmute`
`target`在正文中	`string`必填	帖子、个人主页或群组的 `id`，取决于 `kind`。
`active`在正文中	`boolean`可选	`true` 建立关系，`false` 解除关系。

请求示例

curl -X POST \
  -H "Authorization: Bearer tm_key_…" \
  -H "Content-Type: application/json" \
  -d '{"kind":"like","target":"5f0c2a9e-8d41-4b7a-9c3e-2e61d0f4a7b1","active":true}' \
  "https://api.tellmelo.com/v2/relations"

响应

返回一个 Ok。

示例

{
  "ok": true
}

可能的状态： 200400401403429

GET`/v2/profiles/{handle}/followers`

谁关注了某个主页，最新的在前。

权限 read
可分页
带 ETag
自 v2.19

参数

名称	类型	含义
`handle`在路径中	`string`必填	个人主页的短名称，不区分大小写。
`limit`在查询中	`integer`可选	每页条目数：默认 20，最多 50。
`cursor`在查询中	`string`可选	上一个响应中的 `next`。不传则从头开始。

请求示例

curl \
  -H "Authorization: Bearer tm_key_…" \
  "https://api.tellmelo.com/v2/profiles/mara/followers?limit=20"

响应

返回一页 ProfileBrief，形式为 `items` 和 `next`。

示例

{
  "items": [
    {
      "id": "a3e1f7c2-54b9-4d0e-8f16-7b2c9d4e1a05",
      "handle": "mara",
      "name": "Mara 🌻",
      "verified": true,
      "accountKind": "person"
    }
  ],
  "next": "MTc1ODYyNDAwMDAwMDo1ZjBjMmE5ZS04ZDQx"
}

可能的状态： 200304400401404429

GET`/v2/profiles/{handle}/following`

某个主页关注了谁，最新的在前。

权限 read
可分页
带 ETag
自 v2.19

参数

名称	类型	含义
`handle`在路径中	`string`必填	个人主页的短名称，不区分大小写。
`limit`在查询中	`integer`可选	每页条目数：默认 20，最多 50。
`cursor`在查询中	`string`可选	上一个响应中的 `next`。不传则从头开始。

请求示例

curl \
  -H "Authorization: Bearer tm_key_…" \
  "https://api.tellmelo.com/v2/profiles/mara/following?limit=20"

响应

返回一页 ProfileBrief，形式为 `items` 和 `next`。

示例

{
  "items": [
    {
      "id": "a3e1f7c2-54b9-4d0e-8f16-7b2c9d4e1a05",
      "handle": "mara",
      "name": "Mara 🌻",
      "verified": true,
      "accountKind": "person"
    }
  ],
  "next": "MTc1ODYyNDAwMDAwMDo1ZjBjMmE5ZS04ZDQx"
}

可能的状态： 200304400401404429

GET`/v2/me/relations`

你屏蔽、静音或仅在私信中屏蔽的账号，最新的在前。

权限 read
可分页
带 ETag
自 v2.19

仅限你自己的列表。设置和解除请用 POST /relations。

参数

名称	类型	含义
`kind`在查询中	`string`必填	`block` 已屏蔽，`mute` 已静音，`dm_block` 仅在私信中屏蔽。`blockmutedm_block`
`limit`在查询中	`integer`可选	每页条目数：默认 20，最多 50。
`cursor`在查询中	`string`可选	上一个响应中的 `next`。不传则从头开始。

请求示例

curl \
  -H "Authorization: Bearer tm_key_…" \
  "https://api.tellmelo.com/v2/me/relations?kind=mute&limit=20"

响应

返回一页 ProfileBrief，形式为 `items` 和 `next`。

示例

{
  "items": [
    {
      "id": "a3e1f7c2-54b9-4d0e-8f16-7b2c9d4e1a05",
      "handle": "mara",
      "name": "Mara 🌻",
      "verified": true,
      "accountKind": "person"
    }
  ],
  "next": "MTc1ODYyNDAwMDAwMDo1ZjBjMmE5ZS04ZDQx"
}

可能的状态： 200304400401429

收藏夹

把收藏的帖子整理到你自己的收藏夹里。一个帖子可以在多个收藏夹中；从收藏夹移出后仍保持收藏。

GET`/v2/me/collections`

你的收藏夹及其中的帖子数。

权限 read
带 ETag
自 v2.19

请求示例

curl \
  -H "Authorization: Bearer tm_key_…" \
  "https://api.tellmelo.com/v2/me/collections"

响应

返回一页 Collection，形式为 `items` 和 `next`。

示例

{
  "items": [
    {
      "id": "6d5c4b3a-2918-4e7f-a1b2-c3d4e5f60718",
      "name": "Recipes",
      "count": 12
    }
  ],
  "next": null
}

可能的状态： 200304401429

POST`/v2/me/collections`

创建收藏夹。返回它的 id。

权限 write
自 v2.19

能创建多少个收藏夹取决于你的套餐。

参数

名称	类型	含义
`name`在正文中	`string`必填	名称，最多 40 个字符。每个账号内唯一，不区分大小写。

请求示例

curl -X POST \
  -H "Authorization: Bearer tm_key_…" \
  -H "Content-Type: application/json" \
  -d '{"name":"Recipes"}' \
  "https://api.tellmelo.com/v2/me/collections"

响应

返回一个 Made。

示例

{
  "id": "0d9c8b7a-6f5e-4d3c-2b1a-0f9e8d7c6b5a"
}

可能的状态： 200400401403429

PUT`/v2/me/collections/{id}`

重命名收藏夹。

权限 write
自 v2.19

参数

名称	类型	含义
`id`在路径中	`string`必填	收藏夹的 `id`。
`name`在正文中	`string`必填	名称，最多 40 个字符。每个账号内唯一，不区分大小写。

请求示例

curl -X PUT \
  -H "Authorization: Bearer tm_key_…" \
  -H "Content-Type: application/json" \
  -d '{"name":"Baking"}' \
  "https://api.tellmelo.com/v2/me/collections/6d5c4b3a-2918-4e7f-a1b2-c3d4e5f60718"

响应

返回一个 Ok。

示例

{
  "ok": true
}

可能的状态： 200400401403404429

DELETE`/v2/me/collections/{id}`

删除收藏夹。

权限 write
自 v2.19

其中的帖子仍保持收藏。

参数

名称	类型	含义
`id`在路径中	`string`必填	收藏夹的 `id`。

请求示例

curl -X DELETE \
  -H "Authorization: Bearer tm_key_…" \
  "https://api.tellmelo.com/v2/me/collections/6d5c4b3a-2918-4e7f-a1b2-c3d4e5f60718"

响应

返回一个 Ok。

示例

{
  "ok": true
}

可能的状态： 200400401403404429

GET`/v2/me/collections/{id}/posts`

收藏夹中的帖子，与收藏标签页相同。

权限 read
可分页
自 v2.19

参数

名称	类型	含义
`id`在路径中	`string`必填	收藏夹的 `id`。
`limit`在查询中	`integer`可选	每页条目数：默认 20，最多 50。
`cursor`在查询中	`string`可选	上一个响应中的 `next`。不传则从头开始。

请求示例

curl \
  -H "Authorization: Bearer tm_key_…" \
  "https://api.tellmelo.com/v2/me/collections/6d5c4b3a-2918-4e7f-a1b2-c3d4e5f60718/posts?limit=20"

响应

返回一页 Post，形式为 `items` 和 `next`。

示例

{
  "items": [
    {
      "id": "5f0c2a9e-8d41-4b7a-9c3e-2e61d0f4a7b1",
      "text": "The bees are back in the garden 🐝 #garden",
      "kind": "poll",
      "author": {
        "id": "a3e1f7c2-54b9-4d0e-8f16-7b2c9d4e1a05",
        "handle": "mara",
        "name": "Mara 🌻",
        "verified": true,
        "accountKind": "person"
      },
      "community": {
        "id": "c81d4e2a-0f3b-4a6c-9e57-1d2b3c4a5f60",
        "name": "Urban Gardening"
      },
      "media": [
        {
          "url": "/api/media?id=b2d7e9f1-3c4a-4e8b-a1f0-6d5c4b3a2918",
          "kind": "image",
          "poster": null,
          "ai": "without"
        }
      ],
      "poll": {
        "options": [
          {
            "text": "Lavender",
            "votes": 12
          },
          {
            "text": "Sunflowers",
            "votes": 7
          },
          {
            "text": "Clover",
            "votes": 3
          }
        ],
        "total": 22,
        "multiple": false,
        "endsAt": null,
        "running": true,
        "resultsVisible": true,
        "myVotes": [
          0
        ]
      },
      "quotes": null,
      "continues": null,
      "counts": {
        "replies": 4,
        "likes": 31,
        "reposts": 2
      },
      "pinned": false,
      "giftDrop": {
        "item": "plan",
        "quantity": 3,
        "places": 10,
        "left": 4,
        "audience": "followers",
        "newAccounts": false,
        "status": "open",
        "claimed": true
      },
      "createdAt": 1758624000000
    }
  ],
  "next": "MTc1ODYyNDAwMDAwMDo1ZjBjMmE5ZS04ZDQx"
}

可能的状态： 200400401404429

POST`/v2/me/collections/{id}/posts`

把帖子放入收藏夹或从中移出。

权限 write
自 v2.19

放入收藏夹也会收藏该帖子。仅限可见的帖子。

参数

名称	类型	含义
`id`在路径中	`string`必填	收藏夹的 `id`。
`post`在正文中	`string`必填	帖子的 `id`。
`inside`在正文中	`boolean`可选	`true` 放入帖子（默认），`false` 移出。

请求示例

curl -X POST \
  -H "Authorization: Bearer tm_key_…" \
  -H "Content-Type: application/json" \
  -d '{"post":"5f0c2a9e-8d41-4b7a-9c3e-2e61d0f4a7b1","inside":true}' \
  "https://api.tellmelo.com/v2/me/collections/6d5c4b3a-2918-4e7f-a1b2-c3d4e5f60718/posts"

响应

返回一个 Ok。

示例

{
  "ok": true
}

可能的状态： 200400401403404429

礼物

查看合作伙伴的额度并从中赠送，在帖子下发放礼物并随时掌握情况。领取礼物只能由真人在应用中完成。

GET`/v2/partner/quota`

你的额度里还剩多少可以送。

权限 read
带 ETag
自 v2.12

仅限有额度的合作伙伴；其他人会收到 403。

请求示例

curl \
  -H "Authorization: Bearer tm_key_…" \
  "https://api.tellmelo.com/v2/partner/quota"

响应

返回一个 Quota。

示例

{
  "months": 120,
  "sparks": 500,
  "looks": [
    {
      "id": "frame-gold",
      "name": "Goldring",
      "kind": "frame",
      "quantity": 25
    }
  ]
}

可能的状态： 200304401429

GET`/v2/partner/gifts`

你从额度送出了什么、送给谁、什么时候——最新的在前。

权限 read
可分页
带 ETag
自 v2.12

仅限有额度的合作伙伴；其他人会收到 403。

参数

名称	类型	含义
`limit`在查询中	`integer`可选	每页条目数：默认 20，最多 50。
`cursor`在查询中	`string`可选	上一个响应中的 `next`。不传则从头开始。

请求示例

curl \
  -H "Authorization: Bearer tm_key_…" \
  "https://api.tellmelo.com/v2/partner/gifts?limit=20"

响应

返回一页 QuotaGift，形式为 `items` 和 `next`。

示例

{
  "items": [
    {
      "item": "plan",
      "quantity": 3,
      "itemId": null,
      "recipient": {
        "handle": "jon",
        "name": "Jon"
      },
      "createdAt": 1758627600000
    }
  ],
  "next": "MTc1ODYyNDAwMDAwMDo1ZjBjMmE5ZS04ZDQx"
}

可能的状态： 200304401429

POST`/v2/partner/gifts`

从你的额度中把套餐月数或火花送给一位成员。

权限 gifts
自 v2.12

仅限有额度的合作伙伴；其他人会收到 403。

和在应用中一样，成员会看到礼物来自谁。每小时最多 60 份礼物。

参数

名称	类型	含义
`handle`在正文中	`string`必填	你要赠送的成员的 @用户名，带不带 @ 都可以。
`item`在正文中	`string`必填	`plan` 表示套餐月数，`sparks` 表示火花，`shop` 表示你库存中的一款样式（自 2.13 起）。`plansparksshop`
`quantity`在正文中	`integer`可选	数量：每份礼物最多 12 个月或 35 个火花。
`itemId`在正文中	`string`可选	用于 `shop`：样式的 ID，即额度中 `looks` 给出的 ID。每份礼物一件；此时 `quantity` 不适用。

请求示例

curl -X POST \
  -H "Authorization: Bearer tm_key_…" \
  -H "Content-Type: application/json" \
  -d '{"handle":"jon","item":"plan","quantity":3,"itemId":"frame-gold"}' \
  "https://api.tellmelo.com/v2/partner/gifts"

响应

返回一个 Quota。

示例

{
  "months": 120,
  "sparks": 500,
  "looks": [
    {
      "id": "frame-gold",
      "name": "Goldring",
      "kind": "frame",
      "quantity": 25
    }
  ]
}

可能的状态： 200400401403429

GET`/v2/gift-drops`

你在帖子下发放的礼物：还剩多少名额，以及是怎么付款的。

权限 read
可分页
带 ETag
自 v2.12

参数

名称	类型	含义
`limit`在查询中	`integer`可选	每页条目数：默认 20，最多 50。
`cursor`在查询中	`string`可选	上一个响应中的 `next`。不传则从头开始。

请求示例

curl \
  -H "Authorization: Bearer tm_key_…" \
  "https://api.tellmelo.com/v2/gift-drops?limit=20"

响应

返回一页 OwnGiftDrop，形式为 `items` 和 `next`。

示例

{
  "items": [
    {
      "item": "plan",
      "quantity": 3,
      "places": 10,
      "left": 4,
      "audience": "followers",
      "newAccounts": false,
      "status": "open",
      "claimed": false,
      "postId": "5f0c2a9e-8d41-4b7a-9c3e-2e61d0f4a7b1",
      "funding": "quota",
      "createdAt": 1758624000000
    }
  ],
  "next": "MTc1ODYyNDAwMDAwMDo1ZjBjMmE5ZS04ZDQx"
}

可能的状态： 200304401429

POST`/v2/gift-drops`

发布一条带礼物的帖子，供他人领取。

权限 gifts
自 v2.12

所有者和拥有此权限的团队成员免费，其他情况从你的额度中扣除。需要付款的请求会被以 422 拒绝——付款只能在应用中完成。

礼物只能在应用中领取，以免有程序把名额一扫而空。还剩多少名额，请看帖子的 giftDrop。

参数

名称	类型	含义
`text`在正文中	`string`可选	帖子、回复或私信的文字。
`community`在正文中	`string`可选	帖子要发到其动态频道的群组 `id`；该频道必须开启，且你需要相应权限。不传时，帖子不属于任何群组。
`item`在正文中	`string`必填	`plan` 表示套餐月数，`sparks` 表示火花。`plansparks`
`quantity`在正文中	`integer`必填	每个名额的内容：最多 12 个月或 35 个火花。
`places`在正文中	`integer`必填	发给多少人，最多 10,000 人。
`audience`在正文中	`string`可选	谁可以领取：`all` 所有人，`followers` 仅你的关注者，`group` 仅群组成员（仅与 `community` 一起使用）。`allfollowersgroup`
`newAccounts`在正文中	`boolean`可选	设为 `true` 时，注册不满 7 天的账号也能领取。不设置则不能。

请求示例

curl -X POST \
  -H "Authorization: Bearer tm_key_…" \
  -H "Content-Type: application/json" \
  -d '{"text":"Ten times three months of Supporter – first come, first served! 🎁","item":"plan","quantity":3,"places":10,"audience":"all","newAccounts":false}' \
  "https://api.tellmelo.com/v2/gift-drops"

响应

返回一个 DropCreated。

示例

{
  "id": "5f0c2a9e-8d41-4b7a-9c3e-2e61d0f4a7b1",
  "funding": "quota"
}

可能的状态： 200400401403429

对象

所有对象，逐个字段说明。[] 表示列表。

`Service`

根路径的响应：谁在响应，以及此密钥能做什么。

字段	类型	含义
`name`	`string`	始终为 `tellmelo`。
`version`	`string`	API 版本，例如 `2.1`。
`scope`	`string`	此密钥能做什么：`read` 或 `read write`。
`rateLimit`	`RateLimit`	此密钥的额度。
`docs`	`string`	本文档的位置，即本站上的路径。
`spec`	`string`	机器可读描述的位置。

示例

{
  "name": "tellmelo",
  "version": "2.20",
  "scope": "read write",
  "rateLimit": {
    "limit": 120,
    "remaining": 117
  },
  "docs": "/developers/docs",
  "spec": "/api/v2/openapi.json"
}

`RateLimit`

此密钥在当前分钟的额度。

字段	类型	含义
`limit`	`integer`	每分钟请求数。
`remaining`	`integer`	本分钟剩余的数量。

示例

{
  "limit": 120,
  "remaining": 117
}

`Post`

帖子，在各处形式相同。

字段	类型	含义
`id`	`string`	帖子的 id。
`text`	`string`或 null	原文（只有投票或只有图片的帖子为 `null`）。
`kind`	`string`	帖子的类型。 `post` — 带文字、图片或引用的帖子。 `poll` — 带投票的帖子。
`author`	`ProfileBrief`	作者。
`community`	`CommunityBrief`或 null	所在群组（不在任何群组中时为 `null`）。
`media`	`Media[]`	其图片，按顺序；没有则为空。
`poll`	`Poll`或 null	投票（没有则为 `null`）。
`quotes`	`string`或 null	本帖引用的帖子的 id。
`continues`	`string`或 null	本帖作为补充所续写的帖子的 id。
`counts`	`Counts`	回复、赞和转发。
`pinned`	`boolean`	是否置顶在作者个人主页顶部。
`giftDrop`	`GiftDrop`或 null	帖子下可领取的礼物（没有时为 `null`）。
`createdAt`	`integer`	写作时间。

示例

{
  "id": "5f0c2a9e-8d41-4b7a-9c3e-2e61d0f4a7b1",
  "text": "The bees are back in the garden 🐝 #garden",
  "kind": "poll",
  "author": {
    "id": "a3e1f7c2-54b9-4d0e-8f16-7b2c9d4e1a05",
    "handle": "mara",
    "name": "Mara 🌻",
    "verified": true,
    "accountKind": "person"
  },
  "community": {
    "id": "c81d4e2a-0f3b-4a6c-9e57-1d2b3c4a5f60",
    "name": "Urban Gardening"
  },
  "media": [
    {
      "url": "/api/media?id=b2d7e9f1-3c4a-4e8b-a1f0-6d5c4b3a2918",
      "kind": "image",
      "poster": null,
      "ai": "without"
    }
  ],
  "poll": {
    "options": [
      {
        "text": "Lavender",
        "votes": 12
      },
      {
        "text": "Sunflowers",
        "votes": 7
      },
      {
        "text": "Clover",
        "votes": 3
      }
    ],
    "total": 22,
    "multiple": false,
    "endsAt": null,
    "running": true,
    "resultsVisible": true,
    "myVotes": [
      0
    ]
  },
  "quotes": null,
  "continues": null,
  "counts": {
    "replies": 4,
    "likes": 31,
    "reposts": 2
  },
  "pinned": false,
  "giftDrop": {
    "item": "plan",
    "quantity": 3,
    "places": 10,
    "left": 4,
    "audience": "followers",
    "newAccounts": false,
    "status": "open",
    "claimed": true
  },
  "createdAt": 1758624000000
}

`Reply`

帖子下的回复：多两个字段的帖子。

Post 的所有字段，另外还有：

字段	类型	含义
`postId`	`string`	整个讨论所属的帖子。
`parentId`	`string`或 null	本回复所回复的回复（直接回复帖子时为 `null`）。

示例

{
  "id": "9e4b1c7d-2a3f-4d5e-8b6c-0f1e2d3c4b5a",
  "text": "Same here, the lavender is full of them.",
  "kind": "post",
  "author": {
    "id": "d4c3b2a1-6e5f-4a7b-9c8d-1e2f3a4b5c6d",
    "handle": "jon",
    "name": "Jon",
    "verified": false,
    "accountKind": "person"
  },
  "community": null,
  "media": [],
  "poll": null,
  "quotes": null,
  "continues": null,
  "counts": {
    "replies": 0,
    "likes": 3,
    "reposts": 0
  },
  "pinned": false,
  "giftDrop": null,
  "createdAt": 1758624600000,
  "postId": "5f0c2a9e-8d41-4b7a-9c3e-2e61d0f4a7b1",
  "parentId": null
}

`ReplyVote`

你对一条回复的投票及其得分。

字段	类型	含义
`vote`	`string`	你的投票。 `up` — 赞成。 `down` — 反对。 `none` — 未投票。
`score`	`integer`	赞成票减去反对票，可以低于零。

示例

{
  "vote": "up",
  "score": 12
}

`PlannedReply`

你定时稍后发布的一条回复。

字段	类型	含义
`id`	`string`	定时回复的 `id`。
`parentId`	`string`或 null	它将回复的那条回复（直接回复帖子时为 `null`）。
`text`	`string`	文字。
`publishAt`	`integer`	发布时间。
`state`	`string`	状态。 `waiting` — 等待发布时间。 `failed` — 无法发送，例如帖子已不存在。

示例

{
  "id": "3b2a1c0d-9e8f-4a7b-b6c5-d4e3f2a1b0c9",
  "parentId": null,
  "text": "Count me in for Saturday!",
  "publishAt": 1758710400000,
  "state": "waiting"
}

`ReplySettings`

你某个帖子的回复设置。

字段	类型	含义
`audience`	`string`	谁可以回复。 `all` — 所有人。 `following` — 你关注的账号。 `mentioned` — 帖子中提及的人。 `nobody` — 除你之外没有人。
`approval`	`boolean`	回复是否需要你批准。
`slow`	`string`	慢速模式。 `auto` — 回复很多时自动开启。 `on` — 始终开启。 `off` — 关闭。

示例

{
  "audience": "following",
  "approval": false,
  "slow": "auto"
}

`Counts`

帖子有多少回复、赞和转发。

字段	类型	含义
`replies`	`integer`	回复，所有层级合计。
`likes`	`integer`	赞。
`reposts`	`integer`	转发。

示例

{
  "replies": 4,
  "likes": 31,
  "reposts": 2
}

`Media`

帖子或私信中的一张图片。

字段	类型	含义
`url`	`string`	图片或视频的地址，相对于本站。加载时请在请求头中带上密钥。
`kind`	`string`	`image`、`video` 或 `gif`（自 2.10 起）。视频和 GIF 均为 MP4 文件。 `image` — 一张图片（WebP 或 JPEG）。 `video` — 带声音的 MP4 视频。 `gif` — GIF，以无声循环的 MP4 形式提供。
`poster`	`string`或 null	视频和 GIF 的预览图地址，否则为 `null`（自 2.10 起）。
`ai`	`string`或 null	图片是否使用 AI 制作，依据上传者的标注或团队在举报后的标记；没有标注时为 `null`（自 2.11 起）。 `with` — 使用 AI 制作。 `without` — 未使用 AI 制作。

示例

{
  "url": "/api/media?id=b2d7e9f1-3c4a-4e8b-a1f0-6d5c4b3a2918",
  "kind": "image",
  "poster": null,
  "ai": "without"
}

`Poll`

帖子的投票。

字段	类型	含义
`options`	`PollOption[]`	选项，按顺序。投票时 `option` 从 0 开始计数。
`total`	`integer`	所有票数合计，始终存在。
`multiple`	`boolean`	是否可以选择多个选项。
`endsAt`	`integer`或 null	投票结束时间（无截止时为 `null`）。
`running`	`boolean`	是否仍可投票。
`resultsVisible`	`boolean`	是否显示各选项的票数（见 `votes`）。
`myVotes`	`integer[]`	你选择的选项，从 0 开始计数。

示例

{
  "options": [
    {
      "text": "Lavender",
      "votes": 12
    },
    {
      "text": "Sunflowers",
      "votes": 7
    },
    {
      "text": "Clover",
      "votes": 3
    }
  ],
  "total": 22,
  "multiple": false,
  "endsAt": null,
  "running": true,
  "resultsVisible": true,
  "myVotes": [
    0
  ]
}

`PollOption`

投票的一个选项。

字段	类型	含义
`text`	`string`	选项内容。
`votes`	`integer`或 null	其票数（结果隐藏期间为 `null`）。

示例

{
  "text": "Lavender",
  "votes": 12
}

`ProfileBrief`

出现在其他对象中的个人主页：作为作者或在搜索中。

字段	类型	含义
`id`	`string`	账号的 id：`/relations` 和 `/conversations/{with}` 需要的值。
`handle`	`string`	短名称，不含 `@`，按成员选择的写法显示。
`name`	`string`	显示名称。可能包含表情，包括 `:name:`。
`verified`	`boolean`	账号是否已认证。
`accountKind`	`string`	账号类型。 `person` — 个人。 `business` — 商家。 `association` — 俱乐部或社团。 `automated` — 自动化账号，例如机器人。 `bot` — 由带有自己密钥的程序运行的群组机器人（自 2.18 起）。

示例

{
  "id": "a3e1f7c2-54b9-4d0e-8f16-7b2c9d4e1a05",
  "handle": "mara",
  "name": "Mara 🌻",
  "verified": true,
  "accountKind": "person"
}

`Profile`

单独的个人主页，包含简介和关注者。

ProfileBrief 的所有字段，另外还有：

字段	类型	含义
`about`	`string`或 null	简介（没有则为 `null`）。
`website`	`string`或 null	个人主页的网站（没有则为 `null`）。自 2.3 起。
`websiteVerified`	`boolean`	网站是否通过 `rel=me` 回链到此个人主页，每周检查一次。自 2.3 起。
`followers`	`integer`	有多少账号关注它。
`createdAt`	`integer`或 null	账号创建时间（成员隐藏加入日期时为 `null`；自 2.9 起）。

示例

{
  "id": "a3e1f7c2-54b9-4d0e-8f16-7b2c9d4e1a05",
  "handle": "mara",
  "name": "Mara 🌻",
  "verified": true,
  "accountKind": "person",
  "about": "Beekeeper, allotment, too many seeds. :tellmelo:",
  "website": "https://mara-imkerei.example/",
  "websiteVerified": true,
  "followers": 148,
  "createdAt": 1750848000000
}

`CommunityBrief`

帖子所在的群组。

字段	类型	含义
`id`	`string`	群组的 id。
`name`	`string`或 null	群组名称。

示例

{
  "id": "c81d4e2a-0f3b-4a6c-9e57-1d2b3c4a5f60",
  "name": "Urban Gardening"
}

`Community`

本站的一个群组。

字段	类型	含义
`id`	`string`	群组的 id。
`name`	`string`	群组名称。
`handle`	`string`或 null	用 `@#` 提及群组时使用的短名称。自 2.15 起。
`description`	`string`或 null	简介（没有则为 `null`）。
`tags`	`string[]`	涉及的话题。
`members`	`integer`	成员数量。
`joinPolicy`	`string`	加入方式。 `open` — 任何人都可以加入。 `application` — 加入需要提交申请并获群组接受。 `invite` — 仅限邀请。
`visibility`	`string`	谁能看到它。`internal` 和 `hidden` 仅限其成员（自 2.15 起）。 `open` — 所有人可见。 `internal` — 目录中找不到，但可以通过地址访问。 `hidden` — 仅限其成员。
`feedChannel`	`boolean`	其动态频道是否开启。自 2.15 起。
`sparks`	`integer`	群组当前持有的火花数（自 2.19 起）。
`perks`	`string[]`	由其火花支付的特权（自 2.19 起）。
`membership`	`Membership`或 null	你的账号在群组中的身份和权限；不是成员时为 `null`。自 2.15 起。

示例

{
  "id": "c81d4e2a-0f3b-4a6c-9e57-1d2b3c4a5f60",
  "name": "Urban Gardening",
  "handle": "urbangardening",
  "description": "Balconies, allotments, rooftops: whatever grows.",
  "tags": [
    "garden",
    "bees"
  ],
  "members": 312,
  "joinPolicy": "open",
  "visibility": "open",
  "feedChannel": true,
  "sparks": 24,
  "perks": [
    "tint",
    "welcome"
  ],
  "membership": {
    "leader": null,
    "roles": [
      "4e5f6a7b-8c9d-4e0f-a1b2-c3d4e5f6a7b8"
    ],
    "permissions": [
      "attach",
      "invite",
      "send",
      "view"
    ],
    "mutedUntil": null
  }
}

`Membership`

你的账号在群组中的身份和权限。

字段	类型	含义
`leader`	`string`或 null	你是否创建了该群组或共同管理它；否则为 `null`。 `founder` — 创建者。 `manager` — 共同管理者。
`roles`	`string[]`	你的角色的 `id`，最高的在前。
`permissions`	`string[]`	你在群组中能做的事。
`mutedUntil`	`integer`或 null	禁言在这里持续到何时；没有则为 `null`。

示例

{
  "leader": null,
  "roles": [
    "4e5f6a7b-8c9d-4e0f-a1b2-c3d4e5f6a7b8"
  ],
  "permissions": [
    "attach",
    "invite",
    "send",
    "view"
  ],
  "mutedUntil": null
}

`Person`

一位成员的简要信息。

字段	类型	含义
`id`	`string`	账号的 `id`。
`handle`	`string`	用户名，不含 `@`。
`name`	`string`	显示名称。
`bot`	`boolean`	该账户是否为机器人（自 2.18 起）。

示例

{
  "id": "d4c3b2a1-6e5f-4a7b-9c8d-1e2f3a4b5c6d",
  "handle": "jon",
  "name": "Jon",
  "bot": false
}

`Channel`

群组的一个频道。

字段	类型	含义
`id`	`string`	`id`。
`kind`	`string`	频道类型。 `feed` — 动态频道，其帖子也会出现在公开动态中。 `chat` — 聊天。 `voice` — 语音频道；只能在应用中说话。 `hub` — 群组的大厅：介绍群组的页面。始终存在，没有消息。
`name`	`string`或 null	名称，不含 `#`；为 `null` 时使用应用在各语言中给出的名称。
`topic`	`string`	主题；没有时为空。
`category`	`ChannelCategory`或 null	分类；没有时为 `null`。
`unread`	`integer`	你尚未阅读的他人消息数，最多 100。
`permissions`	`string[]`	你在此频道中能做的事。
`symbol`	`ChannelSymbol`	它的图标；若群组设定了形状，则为群组的形状。

示例

{
  "id": "0d9c8b7a-6f5e-4d3c-2b1a-0f9e8d7c6b5a",
  "kind": "chat",
  "name": "harvest",
  "topic": "What came in this week",
  "category": {
    "id": "9a8b7c6d-5e4f-4a3b-8c2d-1e0f9a8b7c6d",
    "name": "Garden",
    "symbol": {
      "emoji": null,
      "icon": null,
      "image": null,
      "color": null,
      "shape": null
    }
  },
  "unread": 3,
  "permissions": [
    "view",
    "send"
  ],
  "symbol": {
    "emoji": "🌻",
    "icon": null,
    "image": null,
    "color": "amber",
    "shape": "circle"
  }
}

`ChannelCategory`

频道所在的分类。

字段	类型	含义
`id`	`string`	`id`。
`name`	`string`	名称。
`symbol`	`ChannelSymbol`	它的图标。

示例

{
  "id": "9a8b7c6d-5e4f-4a3b-8c2d-1e0f9a8b7c6d",
  "name": "Garden",
  "symbol": {
    "emoji": null,
    "icon": null,
    "image": null,
    "color": null,
    "shape": null
  }
}

`ChannelSymbol`

频道或分类的图标：表情、图标、图片至多其一，否则为其类型的标志。

字段	类型	含义
`emoji`	`string`或 null	表情；没有则为 `null`。
`icon`	`string`或 null	应用图标库中的图标名；没有则为 `null`。
`image`	`string`或 null	自有图片的地址；没有则为 `null`。
`color`	`string`或 null	图块颜色；`null` 表示其类型的颜色。
`shape`	`string`或 null	图块形状；`null` 表示圆形。

示例

{
  "emoji": "🌻",
  "icon": null,
  "image": null,
  "color": "amber",
  "shape": "circle"
}

`ChannelMessage`

聊天频道中的一条消息。

字段	类型	含义
`id`	`string`	`id`。
`text`	`string`或 null	文本（仅含图片或语音的消息为 `null`）。
`author`	`Person`	谁写的。
`media`	`Media[]`	其中的图片和语音消息；没有时为空。
`replyTo`	`string`或 null	所回复消息的 `id`；没有时为 `null`。
`roleColor`	`string`或 null	作者拥有颜色的最高角色的颜色；没有则为 `null`。
`threadOf`	`string`或 null	此消息在其话题中回复的消息；在聊天中为 `null`。
`threadCount`	`integer`	此消息的话题有多少条回复。
`card`	`object`或 null	机器人的卡片：`title`、`text`、`color` 和 `fields`；否则为 `null`。
`buttons`	`object[]`	机器人的按钮：每个包含 `id`、`label` 和 `style`。
`createdAt`	`integer`	何时写的。

示例

{
  "id": "61a2b3c4-d5e6-4f70-8192-a3b4c5d6e7f8",
  "text": "@jon the first tomatoes are ripe 🍅",
  "author": {
    "id": "a3e1f7c2-54b9-4d0e-8f16-7b2c9d4e1a05",
    "handle": "mara",
    "name": "Mara 🌻",
    "bot": false
  },
  "media": [
    {
      "url": "/api/media?id=b2d7e9f1-3c4a-4e8b-a1f0-6d5c4b3a2918",
      "kind": "image",
      "poster": null,
      "ai": "without"
    }
  ],
  "replyTo": "72b3c4d5-e6f7-4081-92a3-b4c5d6e7f809",
  "roleColor": "green",
  "threadOf": null,
  "threadCount": 3,
  "card": null,
  "buttons": [],
  "createdAt": 1758631200000
}

`Role`

群组的一个角色。

字段	类型	含义
`id`	`string`	`id`。
`name`	`string`或 null	名称；@everyone 为 `null`。
`everyone`	`boolean`	是否为 @everyone，即所有成员的角色。
`color`	`string`或 null	颜色：`indigo`、`violet`、`rose`、`amber`、`green` 或 `teal`；没有时为 `null`。
`permissions`	`string[]`	其权限。
`members`	`integer`	拥有它的人数；@everyone 为全体成员。
`editable`	`boolean`	你的账号是否可以修改它。
`selfable`	`boolean`	成员是否自行领取和取消该身份组。

示例

{
  "id": "4e5f6a7b-8c9d-4e0f-a1b2-c3d4e5f6a7b8",
  "name": "Gardeners",
  "everyone": false,
  "color": "green",
  "permissions": [
    "attach",
    "invite",
    "send",
    "view"
  ],
  "members": 24,
  "editable": true,
  "selfable": false
}

`GroupMember`

群组成员及其角色。

Person 的所有字段，另外还有：

字段	类型	含义
`leader`	`string`或 null	该成员是否创建了群组或共同管理它；否则为 `null`。 `founder` — 创建者。 `manager` — 共同管理者。
`roles`	`string[]`	其角色的 `id`，最高的在前。
`mutedUntil`	`integer`或 null	如果你的账号可以禁言，成员被禁言到何时；否则为 `null`。

示例

{
  "id": "d4c3b2a1-6e5f-4a7b-9c8d-1e2f3a4b5c6d",
  "handle": "jon",
  "name": "Jon",
  "bot": false,
  "leader": null,
  "roles": [
    "4e5f6a7b-8c9d-4e0f-a1b2-c3d4e5f6a7b8"
  ],
  "mutedUntil": null
}

`ChannelOverride`

某个角色在频道中与在群组中不同的权限。

字段	类型	含义
`role`	`string`	角色的 `id`。
`allow`	`string[]`	它在此额外可以做的事。
`deny`	`string[]`	它在此不能做的事。

示例

{
  "role": "4e5f6a7b-8c9d-4e0f-a1b2-c3d4e5f6a7b8",
  "allow": [
    "send"
  ],
  "deny": []
}

`Bell`

群组的铃铛。

字段	类型	含义
`level`	`string`	接收哪些通知。 `all` — 动态频道中的每条新帖子，以及 @everyone。 `important` — 管理层在动态频道中的帖子，以及 @everyone。 `off` — 不接收，除非有人用 `@名称` 提及你。

示例

{
  "level": "important"
}

`InviteLink`

群组的邀请链接。

字段	类型	含义
`code`	`string`	代码。
`url`	`string`	用于分享的地址。
`createdBy`	`Person`或 null	谁创建的；账号已删除时为 `null`。
`createdAt`	`integer`	何时创建。
`expiresAt`	`integer`或 null	有效期至何时；不过期时为 `null`。
`uses`	`integer`	已使用次数。
`maxUses`	`integer`或 null	可使用次数；不限时为 `null`。

示例

{
  "code": "k7Qm2xPa",
  "url": "https://tellmelo.com/groups?join=k7Qm2xPa",
  "createdBy": {
    "id": "d4c3b2a1-6e5f-4a7b-9c8d-1e2f3a4b5c6d",
    "handle": "jon",
    "name": "Jon",
    "bot": false
  },
  "createdAt": 1758624000000,
  "expiresAt": 1759228800000,
  "uses": 3,
  "maxUses": 10
}

`InvitePreview`

邀请链接指向何处。

字段	类型	含义
`community`	`InviteGroup`	群组。
`member`	`boolean`	你的账号是否已是成员。

示例

{
  "community": {
    "id": "c81d4e2a-0f3b-4a6c-9e57-1d2b3c4a5f60",
    "name": "Urban Gardening",
    "members": 312,
    "rules": [
      "Be kind.",
      "No advertising."
    ]
  },
  "member": false
}

`InviteGroup`

邀请链接背后的群组。

字段	类型	含义
`id`	`string`	`id`。
`name`	`string`	名称。
`members`	`integer`	成员人数。
`rules`	`string[]`	其规则，加入时需接受；没有时为空。

示例

{
  "id": "c81d4e2a-0f3b-4a6c-9e57-1d2b3c4a5f60",
  "name": "Urban Gardening",
  "members": 312,
  "rules": [
    "Be kind.",
    "No advertising."
  ]
}

`Joined`

通过邀请链接加入。

字段	类型	含义
`community`	`string`	群组的 `id`。

示例

{
  "community": "c81d4e2a-0f3b-4a6c-9e57-1d2b3c4a5f60"
}

`LogEntry`

管理层记录中的一条。

字段	类型	含义
`id`	`string`	`id`。
`action`	`string`	发生了什么。 `post_removed` — 一条帖子。 `member_removed` — 2.16 之前移除的成员（90 天内不能加入）。 `message_removed` — 聊天频道中的一条消息。 `member_kicked` — 一次踢出。 `member_banned` — 一次封禁。 `member_unbanned` — 一次解除封禁。 `member_timed_out` — 一次禁言。 `timeout_lifted` — 一次解除禁言。 `voice_muted` — 在语音频道中被静音。 `voice_removed` — 被断开语音频道。 `bot_added` — 有机器人加入了群组（自 2.18 起）。 `bot_removed` — 有机器人被移出群组（自 2.18 起）。
`member`	`Person`	涉及谁。
`reason`	`string`	理由；消息以及未给出理由时为空。
`by`	`string`或 null	执行者的名字；账号已删除时为 `null`。
`createdAt`	`integer`	何时。

示例

{
  "id": "8f7e6d5c-4b3a-4291-8f7e-6d5c4b3a2918",
  "action": "message_removed",
  "member": {
    "id": "d4c3b2a1-6e5f-4a7b-9c8d-1e2f3a4b5c6d",
    "handle": "jon",
    "name": "Jon",
    "bot": false
  },
  "reason": "",
  "by": "Mara 🌻",
  "createdAt": 1758710400000
}

`Ban`

群组中的一项封禁。

字段	类型	含义
`member`	`Person`	被封禁的人。
`until`	`integer`或 null	到何时；在被解除前为 `null`。
`createdAt`	`integer`或 null	从何时起；2.16 之前的封禁为 `null`。
`by`	`string`或 null	执行封禁者的名字；未知时为 `null`。

示例

{
  "member": {
    "id": "d4c3b2a1-6e5f-4a7b-9c8d-1e2f3a4b5c6d",
    "handle": "jon",
    "name": "Jon",
    "bot": false
  },
  "until": 1759228800000,
  "createdAt": 1758624000000,
  "by": "Mara 🌻"
}

`Until`

禁言或封禁何时结束。

字段	类型	含义
`until`	`integer`或 null	时间点；无期限封禁或已解除的禁言为 `null`。

示例

{
  "until": 1758624600000
}

`Tag`

一个标签以及有多少帖子使用它。

字段	类型	含义
`tag`	`string`	标签，不含 `#`。
`posts`	`integer`	最近有多少帖子使用它。

示例

{
  "tag": "garden",
  "posts": 58
}

`SearchResult`

三个列表，可能为空。

字段	类型	含义
`posts`	`Post[]`	匹配的帖子，最新的在前。
`profiles`	`ProfileBrief[]`	匹配的个人主页，按短名称。
`tags`	`Tag[]`	匹配的标签，最常用的在前。

示例

{
  "posts": [
    {
      "id": "5f0c2a9e-8d41-4b7a-9c3e-2e61d0f4a7b1",
      "text": "The bees are back in the garden 🐝 #garden",
      "kind": "poll",
      "author": {
        "id": "a3e1f7c2-54b9-4d0e-8f16-7b2c9d4e1a05",
        "handle": "mara",
        "name": "Mara 🌻",
        "verified": true,
        "accountKind": "person"
      },
      "community": {
        "id": "c81d4e2a-0f3b-4a6c-9e57-1d2b3c4a5f60",
        "name": "Urban Gardening"
      },
      "media": [
        {
          "url": "/api/media?id=b2d7e9f1-3c4a-4e8b-a1f0-6d5c4b3a2918",
          "kind": "image",
          "poster": null,
          "ai": "without"
        }
      ],
      "poll": {
        "options": [
          {
            "text": "Lavender",
            "votes": 12
          },
          {
            "text": "Sunflowers",
            "votes": 7
          },
          {
            "text": "Clover",
            "votes": 3
          }
        ],
        "total": 22,
        "multiple": false,
        "endsAt": null,
        "running": true,
        "resultsVisible": true,
        "myVotes": [
          0
        ]
      },
      "quotes": null,
      "continues": null,
      "counts": {
        "replies": 4,
        "likes": 31,
        "reposts": 2
      },
      "pinned": false,
      "giftDrop": {
        "item": "plan",
        "quantity": 3,
        "places": 10,
        "left": 4,
        "audience": "followers",
        "newAccounts": false,
        "status": "open",
        "claimed": true
      },
      "createdAt": 1758624000000
    }
  ],
  "profiles": [
    {
      "id": "a3e1f7c2-54b9-4d0e-8f16-7b2c9d4e1a05",
      "handle": "mara",
      "name": "Mara 🌻",
      "verified": true,
      "accountKind": "person"
    }
  ],
  "tags": [
    {
      "tag": "garden",
      "posts": 58
    }
  ]
}

`Emoji`

本站的一个表情。

字段	类型	含义
`name`	`string`	名称，即冒号之间的部分。
`url`	`string`	图片地址，相对于本站。

示例

{
  "name": "tellmelo",
  "url": "/api/media?id=e1f2a3b4-c5d6-4e7f-8a9b-0c1d2e3f4a5b"
}

`Notification`

一条通知。一行可以汇总多个同类事件。

字段	类型	含义
`id`	`string`	通知的 id。
`kind`	`string`	发生了什么。 `reply` — 有人回复了你。 `like` — 有人赞了你的帖子。 `reply_like` — 有人赞成你的回复。 `duel` — 有人向你发起动态对决挑战，或你的挑战已完成。 `reply_pick` — 帖子作者将你的回复设为精选。 `repost` — 有人转发了你的帖子。 `follow` — 有人关注了你。 `mention` — 有人提到了你。 `group_mention` — 有人提到了你管理的群组；`text` 是群组名称。 `channel_mention` — 有人在你某个群组的聊天频道中提及了你，包括 @everyone；该成员为 `actor`，句子中写明频道和群组，从不包含消息内容。 `message` — 有人给你发了私信。 `scheduled` — 你的一条定时帖子已发布。 `video` — 你的一条等待视频的帖子已发布，或已重新变为草稿。 `reminder` — 一条关于收藏帖子的提醒到期了。 `report` — 你提交的举报的处理结果。 `moderation` — 关于你账号的决定：警告、限制、申诉。 `team` — 团队有新工作（仅限所有者、管理员和版主）。 `reward` — 邀请奖励即将到期或已到期。 `gift` — 来自团队的礼物：一个套餐，或给你或你管理的群组的火花。 `present` — 来自成员的礼物：火花或套餐时长；该成员即 `actor`。 `spark` — 火花即将到期，或你管理的群组的火花不再足以支撑其特权。 `loyalty` — 关于忠诚节奏：活跃的一周被计入或还差一天，奖励是新的或即将消失。 `impact` — 你十二小时内的帖子在一天后的表现，合并为一条通知。 `discovery` — “被发现”计划的邀请，或其中某个位置开始或结束。 `group_post` — 某个群组有新帖子，且该群组的铃铛设置为提醒。 `group_moderation` — 群组管理层移除了你的一条帖子，或将你移出了群组。 `group` — 成员在群组中对你做的事：邀请、接受或拒绝你、将你设为联合管理员、移交或解散群组，或申请加入你的群组；该成员即 `actor`，群组名称位于句末。 `coauthor` — 有人邀请你成为帖子的合著者。 `partner` — 来自合作伙伴计划的提醒，或合作伙伴标识的结束。 `news` — 你关注的地区有一篇新文章。 `pick` — 你的帖子入围每周佳帖或年度佳帖评选，或已胜出。 `advent` — 降临节日历有新格子打开、有格子被打开，或今天的格子还在等待。 `team_message` — tellmelo 团队写给选定成员的消息。 `challenge` — 新的每周挑战开始了。 `nudge` — 仅一次：一条还没有人回复的帖子，或正在进行的挑战。 `signin` — 有电脑在询问你是否正在那里登录。
`text`	`string`或 null	仅用于举报和审核：相关文本，否则为 `null`。
`actor`	`Actor`	谁做的。
`postId`	`string`或 null	涉及的帖子（不涉及任何帖子时为 `null`）。
`read`	`boolean`	是否已标为已读。
`more`	`integer`	除所列事件外，这一行还代表多少其他事件。
`createdAt`	`integer`	首次发生的时间。
`updatedAt`	`integer`	最后一次汇入新事件的时间。列表按此排序。

示例

{
  "id": "3f2e1d0c-9b8a-4765-8432-10fedcba9876",
  "kind": "like",
  "text": null,
  "actor": {
    "handle": "jon",
    "name": "Jon"
  },
  "postId": "5f0c2a9e-8d41-4b7a-9c3e-2e61d0f4a7b1",
  "read": false,
  "more": 2,
  "createdAt": 1758624300000,
  "updatedAt": 1758624900000
}

`Actor`

谁触发了通知。

字段	类型	含义
`handle`	`string`	短名称。
`name`	`string`	显示名称。

示例

{
  "handle": "jon",
  "name": "Jon"
}

`Conversation`

你收件箱中的一行。

字段	类型	含义
`with`	`string`	对方账号的 id：`/conversations/{with}/messages` 需要的值。
`handle`	`string`	对方的短名称。
`name`	`string`	对方的显示名称。
`excerpt`	`string`或 null	最后一条私信的开头（没有文字时为 `null`）。
`truncated`	`boolean`	摘录是否被截断。
`fromMe`	`boolean`	最后一条私信是否是你发的。
`lastMessageId`	`string`	最后一条私信的 id。
`unread`	`integer`	对方有多少条私信你还没读。
`updatedAt`	`integer`	最后一条私信的写作时间。

示例

{
  "with": "d4c3b2a1-6e5f-4a7b-9c8d-1e2f3a4b5c6d",
  "handle": "jon",
  "name": "Jon",
  "excerpt": "See you on Saturday at the market!",
  "truncated": false,
  "fromMe": true,
  "lastMessageId": "7c6b5a49-3827-4165-9f0e-d1c2b3a49586",
  "unread": 0,
  "updatedAt": 1758624060000
}

`Message`

对话中的一条私信。

字段	类型	含义
`id`	`string`	私信的 id。
`text`	`string`或 null	文字（只有图片的私信为 `null`）。
`from`	`string`	写信账号的 id。
`to`	`string`	收信账号的 id。
`read`	`boolean`	收件人是否已读。
`media`	`Media[]`	其图片；没有则为空。
`replyTo`	`string`或 null	本条私信所回复的私信的 `id`（未回复任何私信时为 `null`）。自 2.2 起。
`createdAt`	`integer`	发送时间。

示例

{
  "id": "7c6b5a49-3827-4165-9f0e-d1c2b3a49586",
  "text": "See you on Saturday at the market!",
  "from": "a3e1f7c2-54b9-4d0e-8f16-7b2c9d4e1a05",
  "to": "d4c3b2a1-6e5f-4a7b-9c8d-1e2f3a4b5c6d",
  "read": true,
  "media": [],
  "replyTo": null,
  "createdAt": 1758624060000
}

`PlannedMessage`

你定时稍后发送的一条私信。

字段	类型	含义
`id`	`string`	定时私信的 `id`。
`to`	`string`	接收账号的 `id`。
`text`	`string`或 null	文字；端到端加密时为 `null`。
`sendAt`	`integer`	发送时间。
`state`	`string`	状态。 `waiting` — 等待发送时间。 `held` — 因套餐到期而暂缓。你可以自己发送或删除它。 `failed` — 无法发送。

示例

{
  "id": "3b2a1c0d-9e8f-4a7b-b6c5-d4e3f2a1b0c9",
  "to": "a3e1f7c2-54b9-4d0e-8f16-7b2c9d4e1a05",
  "text": "Happy birthday! 🎂",
  "sendAt": 1758710400000,
  "state": "waiting"
}

`ScheduledPost`

你一条尚未发布的帖子。

字段	类型	含义
`id`	`string`	帖子的 id。
`text`	`string`或 null	文字。
`communityId`	`string`或 null	发布到的群组（群组外为 `null`）。
`publishAt`	`integer`或 null	发布时间（在等待其他事情时为 `null`）。
`deleteAt`	`integer`或 null	自动删除时间（`null`：永不）。
`waitingFor`	`string`	在等什么。 `time` — 自己的发布时间。 `review` — 对提交审核的文字的批准。 `check` — 自动审核的检查。 `payment` — 礼物的付款。
`createdAt`	`integer`	写作时间。

示例

{
  "id": "5f0c2a9e-8d41-4b7a-9c3e-2e61d0f4a7b1",
  "text": "Market day tomorrow – see you at the bee stand! #garden",
  "communityId": null,
  "publishAt": 1758710400000,
  "deleteAt": null,
  "waitingFor": "time",
  "createdAt": 1758624000000
}

`Collection`

收藏帖子的收藏夹。

字段	类型	含义
`id`	`string`	收藏夹的 `id`。
`name`	`string`	名称。
`count`	`integer`	其中的帖子数。

示例

{
  "id": "6d5c4b3a-2918-4e7f-a1b2-c3d4e5f60718",
  "name": "Recipes",
  "count": 12
}

`Event`

某个主页即将举行的活动。

字段	类型	含义
`id`	`string`	活动的 `id`。
`title`	`string`	标题。
`startsAt`	`integer`	开始时间。
`endsAt`	`integer`或 null	结束时间；没有结束时间时为 `null`。
`place`	`string`或 null	地点。
`description`	`string`或 null	描述。
`signups`	`EventSignups`或 null	报名情况；不可报名时为 `null`。

示例

{
  "id": "2a3b4c5d-6e7f-4809-9a1b-2c3d4e5f6a7b",
  "title": "Seed swap",
  "startsAt": 1758883200000,
  "endsAt": 1758890400000,
  "place": "Community garden",
  "description": "Bring seeds, take seeds.",
  "signups": {
    "count": 14,
    "going": true
  }
}

`EventSignups`

已报名人数。

字段	类型	含义
`count`	`integer`	报名人数。
`going`	`boolean`	你是否已报名。

示例

{
  "count": 14,
  "going": true
}

`EventSignup`

报名了你某个活动的人。

字段	类型	含义
`id`	`string`	账号的 `id`。
`handle`	`string`	用户名。
`name`	`string`	显示名称。
`at`	`integer`	报名时间。

示例

{
  "id": "a3e1f7c2-54b9-4d0e-8f16-7b2c9d4e1a05",
  "handle": "mara",
  "name": "Mara 🌻",
  "at": 1758624000000
}

`Picture`

一张已上传的图片。

字段	类型	含义
`id`	`string`	图片的 `id`。
`url`	`string`	可以在哪里查看。

示例

{
  "id": "8c7b6a59-4837-4261-9f5e-d4c3b2a1f0e9",
  "url": "/api/media?id=8c7b6a59-4837-4261-9f5e-d4c3b2a1f0e9"
}

`EmojiPicture`

已上传的表情图片。

字段	类型	含义
`id`	`string`	图片的 `id`。
`url`	`string`	可以在哪里查看。
`animated`	`boolean`	是否为动态。

示例

{
  "id": "8c7b6a59-4837-4261-9f5e-d4c3b2a1f0e9",
  "url": "/api/media?id=8c7b6a59-4837-4261-9f5e-d4c3b2a1f0e9",
  "animated": false
}

`OwnEmoji`

你自己的一个表情。

字段	类型	含义
`name`	`string`	名称。
`url`	`string`	图片。
`animated`	`boolean`	是否为动态。
`resting`	`boolean`	因当前套餐允许的表情较少而暂停：会保留，但无法使用。

示例

{
  "name": "sunflower",
  "url": "/api/media?id=8c7b6a59-4837-4261-9f5e-d4c3b2a1f0e9",
  "animated": false,
  "resting": false
}

`GroupEmoji`

群组的一个表情。

字段	类型	含义
`name`	`string`	名称。
`url`	`string`	图片。
`animated`	`boolean`	是否为动态。

示例

{
  "name": "seedling",
  "url": "/api/media?id=8c7b6a59-4837-4261-9f5e-d4c3b2a1f0e9",
  "animated": false
}

`BotEvent`

机器人所在群组中的一个事件。

字段	类型	含义
`id`	`string`	其编号，递增；用它继续（`since`、`Last-Event-ID`）。
`type`	`string`	发生了什么。 `message.created` — 有人写了一条消息。 `message.deleted` — 一条消息被删除。 `member.joined` — 有人加入。 `member.left` — 有人离开或被移除。 `voice.joined` — 有人进入语音频道。 `command` — 有人使用了机器人的命令。 `interaction` — 有人按下了机器人消息中的按钮。
`community`	`string`	群组。
`channel`	`string`或 null	频道；对整个群组为 `null`。
`createdAt`	`integer`	发生时间。
`data`	`object`	按类型附带的数据：`message`、`member`（含 `reason`）、`command` 或 `interaction`。

示例

{
  "id": "4711",
  "type": "message.created",
  "community": "c81d4e2a-0f3b-4a6c-9e57-1d2b3c4a5f60",
  "channel": "0d9c8b7a-6f5e-4d3c-2b1a-0f9e8d7c6b5a",
  "createdAt": 1758634800000,
  "data": {
    "message": {
      "id": "61a2b3c4-d5e6-4f70-8192-a3b4c5d6e7f8",
      "text": "/dice 6",
      "author": {
        "id": "a3e1f7c2-54b9-4d0e-8f16-7b2c9d4e1a05",
        "handle": "mara",
        "name": "Mara 🌻",
        "bot": false
      },
      "media": 0,
      "replyTo": null,
      "threadOf": null,
      "createdAt": 1758634800000
    }
  }
}

`BotCommand`

机器人的一个命令。

字段	类型	含义
`name`	`string`	其名称，不含“/”。
`description`	`string`	它的作用。

示例

{
  "name": "dice",
  "description": "Rolls a die"
}

`VoiceSeat`

语音频道中的一个位置。

字段	类型	含义
`url`	`string`	媒体服务器的地址（LiveKit）。
`token`	`string`	此频道的令牌，有效几分钟。
`iceServers`	`object[]`	连接所用的 STUN 和 TURN 服务器。
`speak`	`boolean`	机器人能否在那里发送声音。
`video`	`boolean`	机器人能否在那里发送视频。

示例

{
  "url": "wss://voice.example.org",
  "token": "eyJhbGciOiJIUzI1NiJ9…",
  "iceServers": [
    {
      "urls": [
        "stun:turn.example.org:3478"
      ]
    }
  ],
  "speak": true,
  "video": false
}

`Webhook`

你的一个 Webhook。

字段	类型	含义
`id`	`string`	Webhook 的 `id`。
`url`	`string`	地址。
`kinds`	`string[]`	接收哪些通知。
`active`	`boolean`	是否接收推送。连续多次失败后会被关闭。
`lastStatus`	`integer`或 null	上次推送的 HTTP 状态。
`lastAt`	`integer`或 null	上次推送时间。
`failures`	`integer`	连续失败次数。

示例

{
  "id": "1f2e3d4c-5b6a-4798-8a7b-6c5d4e3f2a1b",
  "url": "https://example.org/tellmelo-hook",
  "kinds": [
    "reply",
    "mention"
  ],
  "active": true,
  "lastStatus": 200,
  "lastAt": 1758624000000,
  "failures": 0
}

`WebhookCreated`

新建的 Webhook 及其密钥。

字段	类型	含义
`id`	`string`	Webhook 的 `id`。
`secret`	`string`	签名用的密钥，仅此一次。

示例

{
  "id": "1f2e3d4c-5b6a-4798-8a7b-6c5d4e3f2a1b",
  "secret": "whsec_3f9a…"
}

`GroupBot`

群组的一个机器人。

字段	类型	含义
`id`	`string`	机器人账号的 `id`。
`handle`	`string`	短名。
`name`	`string`	名称。
`description`	`string`	它的用途，由所有者描述。
`permissions`	`string[]`	它在群组中的角色允许的操作。

示例

{
  "id": "a3e1f7c2-54b9-4d0e-8f16-7b2c9d4e1a05",
  "handle": "gardenbot",
  "name": "Garden bot",
  "description": "Reminds the group of watering days.",
  "permissions": [
    "send",
    "view"
  ]
}

`VoiceRoom`

一个语音频道及其中的人。

字段	类型	含义
`channel`	`string`	频道的 `id`。
`people`	`VoicePerson[]`	当前在其中的人。

示例

{
  "channel": "0d9c8b7a-6f5e-4d3c-2b1a-0f9e8d7c6b5a",
  "people": [
    {
      "id": "a3e1f7c2-54b9-4d0e-8f16-7b2c9d4e1a05",
      "handle": "mara",
      "name": "Mara 🌻",
      "muted": false,
      "deaf": false,
      "camera": false,
      "screen": true
    }
  ]
}

`VoicePerson`

语音频道中的某人。

字段	类型	含义
`id`	`string`	账号的 `id`。
`handle`	`string`	短名。
`name`	`string`	显示名称。
`muted`	`boolean`	麦克风是否关闭。
`deaf`	`boolean`	是否什么都听不到（本人选择）。
`camera`	`boolean`	摄像头是否开启。
`screen`	`boolean`	是否在共享屏幕。

示例

{
  "id": "a3e1f7c2-54b9-4d0e-8f16-7b2c9d4e1a05",
  "handle": "mara",
  "name": "Mara 🌻",
  "muted": true,
  "deaf": false,
  "camera": false,
  "screen": false
}

`GiftDrop`

帖子下的礼物——绝不包含领取者的名字。

字段	类型	含义
`item`	`string`	每个名额的内容。 `plan` — 套餐月数（支持者）。 `sparks` — 火花。
`quantity`	`integer`	每个名额有多少：月数或火花数。
`places`	`integer`	名额总数。
`left`	`integer`	还剩多少名额。
`audience`	`string`	谁可以领取。 `all` — 所有人。 `followers` — 仅发放者的关注者。 `group` — 仅帖子所在群组的成员。
`newAccounts`	`boolean`	注册不满 7 天的账号是否也能领取。
`status`	`string`	当前状态。 `awaiting_payment` — 等待付款；帖子尚未发布。 `open` — 还有名额可以领取。 `closed` — 已结束：全部领完、款项已退或帖子已删除。
`claimed`	`boolean`	你自己是否已领取（公开路径上始终为 `false`）。

示例

{
  "item": "plan",
  "quantity": 3,
  "places": 10,
  "left": 4,
  "audience": "followers",
  "newAccounts": false,
  "status": "open",
  "claimed": true
}

`OwnGiftDrop`

你在某条帖子下发放的礼物，附带帖子和付款方式。

GiftDrop 的所有字段，另外还有：

字段	类型	含义
`postId`	`string`	礼物所在的帖子。
`funding`	`string`	付款方式。 `free` — 免费。 `quota` — 来自额度。 `payment` — 已付款。
`createdAt`	`integer`	创建时间。

示例

{
  "item": "plan",
  "quantity": 3,
  "places": 10,
  "left": 4,
  "audience": "followers",
  "newAccounts": false,
  "status": "open",
  "claimed": false,
  "postId": "5f0c2a9e-8d41-4b7a-9c3e-2e61d0f4a7b1",
  "funding": "quota",
  "createdAt": 1758624000000
}

`Quota`

额度里有什么。

字段	类型	含义
`months`	`integer`	还可以送出的套餐月数。
`sparks`	`integer`	还可以送出的火花数。
`looks`	`QuotaLook[]`	库存中还可以送出的样式（自 2.13 起）。

示例

{
  "months": 120,
  "sparks": 500,
  "looks": [
    {
      "id": "frame-gold",
      "name": "Goldring",
      "kind": "frame",
      "quantity": 25
    }
  ]
}

`QuotaLook`

合作伙伴库存中的一款样式，附剩余件数（自 2.13 起）。

字段	类型	含义
`id`	`string`	样式的 ID；送出时作为 `itemId` 传入。
`name`	`string`	样式的名称。
`kind`	`string`	样式的类型。 `frame` — 头像框。 `background` — 封面特效。 `card` — 主页卡片。
`quantity`	`integer`	还剩多少件。

示例

{
  "id": "frame-gold",
  "name": "Goldring",
  "kind": "frame",
  "quantity": 25
}

`QuotaGift`

一份来自额度的礼物。

字段	类型	含义
`item`	`string`	送出了什么。 `plan` — 套餐月数（支持者）。 `sparks` — 火花。 `shop` — 库存中的一款样式（自 2.13 起）。
`quantity`	`integer`	数量。
`itemId`	`string`或 null	当 `item` 为 `shop` 时，为送出的样式；否则为 `null`。
`recipient`	`Actor`	送给谁。
`createdAt`	`integer`	什么时候。

示例

{
  "item": "plan",
  "quantity": 3,
  "itemId": null,
  "recipient": {
    "handle": "jon",
    "name": "Jon"
  },
  "createdAt": 1758627600000
}

`MediaItem`

媒体库中的一个 GIF 或视频（自 2.14 起）。

字段	类型	含义
`id`	`string`	ID；发帖时用于 `media`。
`kind`	`string`	GIF 或视频。 `gif` — 一个 GIF，以无声循环的 MP4 形式。 `video` — 一个 MP4 格式的视频，带声音。
`name`	`string`	名称。
`keywords`	`string`	关键词，小写。
`width`	`integer`	宽度，以像素为单位。
`height`	`integer`	高度，以像素为单位。
`seconds`	`integer`	时长，以秒为单位；GIF 为 `0`。
`url`	`string`	MP4 文件，相对于此实例。用请求头中的密钥加载。
`poster`	`string`	预览图，同样需要密钥。
`uploader`	`Actor`	上传者。
`mine`	`boolean`	是否是你的。
`shared`	`boolean`	是否在 tellmelo 上与所有人分享。
`anywhere`	`boolean`	是否也允许出现在其他网站上。
`embed`	`Embed`或 null	用于其他网站的地址；在那里未获允许时为 `null`。

示例

{
  "id": "b2d7e9f1-3c4a-4e8b-a1f0-6d5c4b3a2918",
  "kind": "gif",
  "name": "Happy bees",
  "keywords": "bees garden happy",
  "width": 480,
  "height": 270,
  "seconds": 0,
  "url": "/api/media?id=b2d7e9f1-3c4a-4e8b-a1f0-6d5c4b3a2918",
  "poster": "/api/media?id=b2d7e9f1-3c4a-4e8b-a1f0-6d5c4b3a2918&poster=1",
  "uploader": {
    "handle": "mara",
    "name": "Mara 🌻"
  },
  "mine": false,
  "shared": true,
  "anywhere": true,
  "embed": {
    "page": "https://tellmelo.com/media-embed/b2d7e9f1-3c4a-4e8b-a1f0-6d5c4b3a2918",
    "file": "https://tellmelo.com/media-embed/b2d7e9f1-3c4a-4e8b-a1f0-6d5c4b3a2918/file",
    "poster": "https://tellmelo.com/media-embed/b2d7e9f1-3c4a-4e8b-a1f0-6d5c4b3a2918/poster",
    "code": "<iframe src=\"https://tellmelo.com/media-embed/b2d7e9f1-3c4a-4e8b-a1f0-6d5c4b3a2918\" width=\"480\" height=\"300\" title=\"Happy bees\" style=\"border:0;max-width:100%\" loading=\"lazy\" allowfullscreen></iframe>"
  }
}

`Embed`

用于其他网站的地址。无需密钥即可使用。

字段	类型	含义
`page`	`string`	用于 `<iframe>` 的播放器。
`file`	`string`	供你自己的播放器使用的 MP4 文件。
`poster`	`string`	预览图。
`code`	`string`	现成的嵌入代码。

示例

{
  "page": "https://tellmelo.com/media-embed/b2d7e9f1-3c4a-4e8b-a1f0-6d5c4b3a2918",
  "file": "https://tellmelo.com/media-embed/b2d7e9f1-3c4a-4e8b-a1f0-6d5c4b3a2918/file",
  "poster": "https://tellmelo.com/media-embed/b2d7e9f1-3c4a-4e8b-a1f0-6d5c4b3a2918/poster",
  "code": "<iframe src=\"https://tellmelo.com/media-embed/b2d7e9f1-3c4a-4e8b-a1f0-6d5c4b3a2918\" width=\"480\" height=\"300\" title=\"Happy bees\" style=\"border:0;max-width:100%\" loading=\"lazy\" allowfullscreen></iframe>"
}

`UploadStarted`

已开始的上传。

字段	类型	含义
`upload`	`string`	此次上传的 ID。
`piece`	`integer`	一块最大可以有多少字节。

示例

{
  "upload": "e7c1a2b3-4d5e-4f60-8a9b-0c1d2e3f4a5b",
  "piece": 4194304
}

`UploadPiece`

已收到的一块。

字段	类型	含义
`received`	`integer`	已收到多少字节。
`item`	`MediaItem`或 null	最后一块之后为新的 GIF 或视频，否则为 `null`。

示例

{
  "received": 4194304,
  "item": null
}

`Created`

创建了内容的写入操作的响应。

字段	类型	含义
`id`	`string`	所创建内容的 id。
`scheduledFor`	`integer`或 null	如果设置了定时发布，则为出现时间（否则为 `null`）。
`deleteAt`	`integer`或 null	如果设置了自动删除，则为删除时间（否则为 `null`）。

示例

{
  "id": "5f0c2a9e-8d41-4b7a-9c3e-2e61d0f4a7b1",
  "scheduledFor": null,
  "deleteAt": null
}

`DropCreated`

创建带礼物的帖子后的响应。

字段	类型	含义
`id`	`string`	新帖子的 id。
`funding`	`string`	礼物的付款方式。 `free` — 免费。 `quota` — 来自额度。

示例

{
  "id": "5f0c2a9e-8d41-4b7a-9c3e-2e61d0f4a7b1",
  "funding": "quota"
}

`Made`

刚刚创建或修改的内容。

字段	类型	含义
`id`	`string`	`id`；邀请链接则为其代码。

示例

{
  "id": "0d9c8b7a-6f5e-4d3c-2b1a-0f9e8d7c6b5a"
}

`Ok`

无需返回内容的写入操作的响应。

字段	类型	含义
`ok`	`boolean`	始终为 `true`。

示例

{
  "ok": true
}

机器可读的描述

本页背后的表格以 OpenAPI 形式提供，地址为 https://api.tellmelo.com/v2/openapi.json。

https://api.tellmelo.com/v2/openapi.json

其他网站上的 GIF 和视频

成员分享并允许在其他网站上使用的内容，任何网站都可以展示：使用 anywhere=true 的搜索能找到它，它的 embed 中包含地址。如果成员撤回，它会在几分钟内从那里消失。

分块上传

先开始上传，然后分块发送文件。较大的文件要分成每块 piece 字节，并用 offset 标明每块的位置。最后一块之后，你会得到完成的 GIF 或视频。

curl -X POST -H "Authorization: Bearer tm_key_…" \
  -H "Content-Type: application/json" \
  -d '{"kind":"gif","size":2400000,"name":"Happy bees","shared":true,"anywhere":true}' \
  "https://api.tellmelo.com/v2/media/uploads"
→ { "upload": "e7c1a2b3-4d5e-4f60-8a9b-0c1d2e3f4a5b", "piece": 4194304 }

curl -X PUT -H "Authorization: Bearer tm_key_…" \
  -H "Content-Type: application/octet-stream" \
  --data-binary @bees.gif \
  "https://api.tellmelo.com/v2/media/uploads/e7c1a2b3-4d5e-4f60-8a9b-0c1d2e3f4a5b?offset=0"
→ { "received": 2400000, "item": { "id": "…", "embed": { … } } }

嵌入

播放器会循环播放 GIF，或带控件播放视频，下方显示名称和分享者。把 embed.code 中的代码放到页面里：

<iframe src="https://tellmelo.com/media-embed/b2d7e9f1-3c4a-4e8b-a1f0-6d5c4b3a2918" width="480" height="300" title="Happy bees" style="border:0;max-width:100%" loading="lazy" allowfullscreen></iframe>

支持 oEmbed 的论坛和程序，只要给它们播放器的地址，就会自己获取代码：

https://tellmelo.com/api/oembed?url=https%3A%2F%2Ftellmelo.com%2Fmedia-embed%2Fb2d7e9f1-3c4a-4e8b-a1f0-6d5c4b3a2918

密钥应放在你的服务器上，绝不能放在网页的代码里。通过你的服务器进行搜索和上传；embed 中的地址不需要密钥。

用于你网站的 GIF 选择器

有了站点密钥（开发者区 → 用于你网站的 GIF 选择器），你的网站就能获得现成的搜索：在页面里加两行代码，点击按钮即可打开。密钥是公开的，只在你为它填写的地址上有效。选择器只显示成员允许在其他网站上使用的内容。

<script src="https://tellmelo.com/picker.js" data-key="tmsk_…" defer></script>
<button type="button" data-tellmelo-picker>GIF</button>

选中内容后，按钮会触发 tellmelo:pick 事件并附带所选条目：用于嵌入的 code，以及 file、poster、name 和 author。设置 data-target="#field" 后，它会把 code 直接填入文本框；设置 data-kind="video" 后，它会搜索视频。如果你自己嵌入文件，请显示分享者的名字。

document.addEventListener('tellmelo:pick', (event) => {
  const { code, file, name, author } = event.detail;
});

使用 tellmelo 登录

其他网站可以通过 OpenID Connect（带 PKCE 的授权码）让成员用 tellmelo 账号登录。网站只会得到用户名、已确认的邮箱地址以及每位成员一个它专属的标识（sub）。

你可以在“开发者区 → 使用 tellmelo 登录”中申请应用。团队会审核每个应用；之后你会在那里看到客户端 ID，有服务器的应用还要创建只显示一次的客户端密钥。

库所需的一切都在发现文档中：

https://tellmelo.com/.well-known/openid-configuration

把成员发送到 /oauth/authorize，并带上 response_type=code、client_id、redirect_uri（与登记的完全一致）、scope=openid profile email、state、nonce 以及配合 code_challenge_method=S256 的 code_challenge。
在一分钟内到 /oauth/token 兑换授权码：grant_type=authorization_code、code、redirect_uri 和 code_verifier；有服务器的应用还要通过 Basic 认证或表单发送密钥。
ID 令牌（RS256，密钥在 /oauth/jwks）包含 sub，带 profile 时还有 preferred_username，带 email 时还有 email 和 email_verified。访问令牌有效期 10 分钟，只能读取 /oauth/userinfo。

https://tellmelo.com/oauth/authorize?response_type=code&client_id=tm_…
  &redirect_uri=https%3A%2F%2Fexample.com%2Fcallback&scope=openid%20profile%20email
  &state=…&nonce=…&code_challenge=…&code_challenge_method=S256

curl -u "tm_…:tms_…" https://tellmelo.com/oauth/token \
  -d grant_type=authorization_code -d code=… \
  -d redirect_uri=https://example.com/callback -d code_verifier=…

{
  "iss": "https://example.social",
  "sub": "Xq3vR0b8yJm1cW4tZ2kPn6sLd9fHa7gE5uTo0iBeVxY",
  "aud": "tm_5f2c9e1a7b3d4c6e8f0a1b2c",
  "iat": 1760432400,
  "exp": 1760433000,
  "nonce": "n-0S6_WzA2Mj",
  "at_hash": "HK6E_P6Dh8Y93mRNtsDB1Q",
  "preferred_username": "anna",
  "email": "anna@example.com",
  "email_verified": true
}

没有刷新令牌：tellmelo 只负责登录，不提供长期访问。如果成员移除了该网站或团队暂停了该应用，/oauth/userinfo 会立即返回 401。prompt=none 不显示页面直接检查，prompt=consent 会重新询问。

我们的期望

规则和其他地方一样：不骚扰、不发垃圾信息、不发你无权发布的内容。你的密钥发布的内容由你负责。

只有当其他成员的 GIF 和视频带有 embed 时，你才能在你的网站上展示它们，并且要通过这些地址，注明分享者的名字。某项内容不再可用时，就停止展示。不要把这些文件复制到你自己的收藏中。

API

我想要 …

概览

快速开始

试一试

你的密钥

密钥能做什么

任何密钥都做不到的事

机器人

请求与响应

分页

只取新内容

限额

请求头

你发送的

返回的

出错时

版本

端点

入口

GET/v2

请求示例

响应

帖子

GET/v2/posts

参数

请求示例

响应

GET/v2/posts/{id}

参数

请求示例

响应

POST/v2/posts

参数

请求示例

响应

DELETE/v2/posts/{id}

参数

请求示例

响应

GET/v2/me/scheduled

请求示例

响应

POST/v2/posts/{id}/schedule

参数

请求示例

响应

POST/v2/posts/{id}/edit

参数

请求示例

响应

GET/v2/posts/{id}/reply-settings

参数

请求示例

响应

PUT/v2/posts/{id}/reply-settings

参数

请求示例

响应

POST/v2/posts/{id}/coauthor

参数

请求示例

响应

DELETE/v2/posts/{id}/coauthor

参数

请求示例

响应

POST/v2/posts/{id}/pin

参数

请求示例

响应

回复

GET/v2/posts/{id}/replies

参数

请求示例

响应

POST/v2/posts/{id}/replies

参数

请求示例

响应

GET`/v2`

GET`/v2/posts`

GET`/v2/posts/{id}`

POST`/v2/posts`

DELETE`/v2/posts/{id}`

GET`/v2/me/scheduled`

POST`/v2/posts/{id}/schedule`

POST`/v2/posts/{id}/edit`

GET`/v2/posts/{id}/reply-settings`

PUT`/v2/posts/{id}/reply-settings`

POST`/v2/posts/{id}/coauthor`

DELETE`/v2/posts/{id}/coauthor`

POST`/v2/posts/{id}/pin`

GET`/v2/posts/{id}/replies`

POST`/v2/posts/{id}/replies`

POST`/v2/replies/{id}/edit`

DELETE`/v2/replies/{id}`

POST`/v2/replies/{id}/like`

POST`/v2/replies/{id}/vote`

POST`/v2/replies/{id}/pick`

GET`/v2/posts/{id}/replies/waiting`

POST`/v2/replies/{id}/decide`

GET`/v2/posts/{id}/replies/planned`

PUT`/v2/me/planned-replies/{id}`

POST`/v2/me/planned-replies/{id}/send`

DELETE`/v2/me/planned-replies/{id}`

POST`/v2/posts/{id}/vote`

GET`/v2/profiles/{handle}`

GET`/v2/profiles/{handle}/posts`

GET`/v2/profiles/{handle}/events`

POST`/v2/me/events`

PUT`/v2/me/events/{id}`