qqbot-channel

Guia de Requisições da API QQ Channel

qqbot_channel_api é uma ferramenta proxy HTTP para a plataforma aberta QQ que preenche automaticamente o token de autenticação. Você só precisa especificar o método HTTP, o caminho da API, o corpo da requisição e os parâmetros de consulta.

📚 Documentação de Referência Detalhada

Descrição completa dos parâmetros, estruturas de retorno e definições de enumeração para cada endpoint:

• references/api_references.md

---

🔧 Parâmetros da Ferramenta

Parâmetro	Tipo	Obrigatório	Descrição
method	string	Sim	Método HTTP: GET, POST, PUT, PATCH, DELETE
path	string	Sim	Caminho da API (sem domínio), ex: /guilds/{guild_id}/channels. Substitua placeholders por valores reais
body	object	Não	JSON do corpo da requisição (usado em POST/PUT/PATCH)
query	object	Não	Pares chave-valor para parâmetros de consulta URL. Valores devem ser do tipo string
confirmed	boolean	Não	DELETE deve ser true, indicando que o usuário confirmou a exclusão exata do alvo
bulkConfirmed	boolean	Não	Deletar em lote (ex: deletar todos os anúncios) requer true adicionalmente

URL base: https://api.sgroup.qq.com. O cabeçalho de autenticação Authorization: QQBot {token} é preenchido automaticamente pela ferramenta.

🛡️ Limites de Segurança

• Chame endpoints de escrita apenas quando o usuário explicitamente solicitar gerenciamento de canais QQ, subcanais, anúncios, postagens de fórum ou agendas.
• POST, PUT, PATCH e DELETE modificam recursos reais do QQ. Antes de chamar, repita o canal/subcanal/postagem/agenda alvo e a alteração esperada; operações irreversíveis ou de grande escala (exclusão, exclusão em lote, substituição de anúncios) devem aguardar confirmação do usuário.
• Antes de excluir, use GET/endpoints de listagem para buscar candidatos e permitir que o usuário selecione IDs específicos. Não adivinhe alvos de exclusão com base em nomes vagos.
• Requisições DELETE devem ter confirmed: true, caso contrário a ferramenta rejeitará a execução. Operações em lote como announces/all também exigem bulkConfirmed: true, usada somente se o usuário disser explicitamente para deletar todos os anúncios e confirmar novamente.
• Dados de membros, URLs de avatar, ícones de canais, etc., são dados de usuário/grupo. Por padrão, resuma apenas campos necessários; exiba imagens inline somente se o usuário solicitar ver o avatar/ícone ou para comparação visual. Não repasse URLs de avatar sem contexto.

---

⭐ Referência Rápida de Endpoints

Guild (Canal)

Operação	Método	Caminho	Descrição dos Parâmetros
Obter lista de guilds (canais)	GET	/users/@me/guilds	query: before, after, limit (máx. 100)
Obter permissão de API do guild	GET	/guilds/{guild_id}/api_permission	—

Channel (Subcanal)

Operação	Método	Caminho	Descrição dos Parâmetros
Obter lista de subcanais	GET	/guilds/{guild_id}/channels	—
Obter detalhes do subcanal	GET	/channels/{channel_id}	—
Criar subcanal	POST	/guilds/{guild_id}/channels	body: name, type, position*, sub_type, parent_id, private_type, private_user_ids, speak_permission, application_id
Modificar subcanal	PATCH	/channels/{channel_id}	body: name, position, parent_id, private_type, speak_permission (pelo menos um)
Deletar subcanal	—	Veja fluxo de exclusão com confirmação	Operação destrutiva; não chamar sem confirmação

Tipos de subcanal (type): 0=Texto, 2=Voz, 4=Agrupamento (position≥2), 10005=Transmissão ao vivo, 10006=Aplicativo, 10007=Fórum

Member (Membro)

Operação	Método	Caminho	Descrição dos Parâmetros
Obter lista de membros	GET	/guilds/{guild_id}/members	query: after (primeira página: 0), limit (1-400)
Obter detalhes do membro	GET	/guilds/{guild_id}/members/{user_id}	—
Obter membros de um cargo	GET	/guilds/{guild_id}/roles/{role_id}/members	query: start_index (primeira página: 0), limit (1-400)
Obter número de membros online	GET	/channels/{channel_id}/online_nums	—

Announce (Anúncio)

Operação	Método	Caminho	Descrição dos Parâmetros
Criar anúncio	POST	/guilds/{guild_id}/announces	body: message_id, channel_id, announces_type (0=membros, 1=boas-vindas), recommend_channels (máx. 3)
Deletar anúncio	—	Veja fluxo de exclusão com confirmação	Operação destrutiva; exclusão em lote requer confirmação dupla

Forum (Fórum) — Apenas bots de domínio privado

Operação	Método	Caminho	Descrição dos Parâmetros
Obter lista de postagens	GET	/channels/{channel_id}/threads	—
Obter detalhes da postagem	GET	/channels/{channel_id}/threads/{thread_id}	—
Publicar postagem	PUT	/channels/{channel_id}/threads	body: title, content, format (1=Texto,2=HTML,3=Markdown,4=JSON, padrão 3)
Deletar postagem	—	Veja fluxo de exclusão com confirmação	Operação destrutiva; não chamar sem confirmação
Publicar comentário	POST	/channels/{channel_id}/threads/{thread_id}/comment	body: thread_author, content, thread_create_time, image

Schedule (Agenda)

Operação	Método	Caminho	Descrição dos Parâmetros
Criar agenda	POST	/channels/{channel_id}/schedules	body: { schedule: { name*, start_timestamp*, end_timestamp*, jump_channel_id, remind_type } }
Modificar agenda	PATCH	/channels/{channel_id}/schedules/{schedule_id}	body: { schedule: { name*, start_timestamp*, end_timestamp*, jump_channel_id, remind_type } }
Deletar agenda	—	Veja fluxo de exclusão com confirmação	Operação destrutiva; não chamar sem confirmação

Tipo de lembrete (remind_type): "0"=Sem lembrete, "1"=No início, "2"=5 minutos antes, "3"=15 minutos antes, "4"=30 minutos antes, "5"=60 minutos antes

* indica parâmetro obrigatório

---

💡 Exemplos de Chamada

Obter lista de guilds

{
  "method": "GET",
  "path": "/users/@me/guilds",
  "query": { "limit": "100" }
}

Obter lista de subcanais

{
  "method": "GET",
  "path": "/guilds/123456/channels"
}

Criar subcanal

{
  "method": "POST",
  "path": "/guilds/123456/channels",
  "body": {
    "name": "Novo Canal",
    "type": 0,
    "position": 1,
    "sub_type": 0
  }
}

Obter lista de membros (paginação)

{
  "method": "GET",
  "path": "/guilds/123456/members",
  "query": { "after": "0", "limit": "100" }
}

Publicar postagem no fórum

{
  "method": "PUT",
  "path": "/channels/789012/threads",
  "body": {
    "title": "Título do Anúncio",
    "content": "# Título\n\nConteúdo do anúncio",
    "format": 3
  }
}

Criar agenda

{
  "method": "POST",
  "path": "/channels/456789/schedules",
  "body": {
    "schedule": {
      "name": "Reunião Semanal",
      "start_timestamp": "1770733800000",
      "end_timestamp": "1770737400000",
      "remind_type": "2"
    }
  }
}

Criar anúncio de subcanal recomendado

{
  "method": "POST",
  "path": "/guilds/123456/announces",
  "body": {
    "announces_type": 0,
    "recommend_channels": [{ "channel_id": "789012", "introduce": "Bem-vindo ao canal de guias" }]
  }
}

Fluxo de exclusão com confirmação

APIs de exclusão do QQ não são expostas como exemplos rápidos. Se o usuário solicitar exclusão de um recurso, primeiro leia e repita o objeto alvo, depois de confirmado, chame qqbot_channel_api: método "DELETE", confirmed como true, e path com o caminho do recurso confirmado.

Objeto a excluir	path após confirmação	Requisito adicional
Subcanal	/channels/{channel_id}	Confirmar ID e nome do subcanal
Anúncio único	/guilds/{guild_id}/announces/{message_id}	Confirmar ID do anúncio
Todos anúncios	/guilds/{guild_id}/announces/all	Usuário confirma novamente; então passar bulkConfirmed: true
Postagem	/channels/{channel_id}/threads/{thread_id}	Confirmar ID da postagem, título/autor
Agenda	/channels/{channel_id}/schedules/{schedule_id}	Confirmar ID da agenda, nome/horário

---

🔄 Fluxos de Operação Comuns

Obter informações de guild e subcanais

1. GET /users/@me/guilds → obter lista de guilds, extrair guild_id
2. GET /guilds/{guild_id}/channels → obter lista de subcanais, extrair channel_id
3. GET /channels/{channel_id} → obter detalhes do subcanal

Publicar postagem + comentário no fórum

1. GET /guilds/{guild_id}/channels → encontrar subcanal de fórum (type=10007)
2. PUT /channels/{channel_id}/threads → publicar postagem
3. GET /channels/{channel_id}/threads → obter lista de postagens
4. GET /channels/{channel_id}/threads/{thread_id} → obter detalhes da postagem (inclui author_id)
5. POST /channels/{channel_id}/threads/{thread_id}/comment → publicar comentário

Gerenciamento de membros

1. GET /users/@me/guilds → obter guild_id
2. GET /guilds/{guild_id}/members?after=0&limit=100 → obter lista de membros
   Paginação: use o último user.id como after até retornar array vazio
3. GET /guilds/{guild_id}/members/{user_id} → obter detalhes do membro específico

Exibir avatar do membro

O campo user.avatar nos detalhes do membro é uma URL de avatar. Por padrão, exiba apenas campos necessários como apelido, ID, data de entrada. Quando o usuário solicitar explicitamente ver o avatar/ícone, ou quando o avatar for essencial para a tarefa atual, exiba inline com sintaxe Markdown de imagem:

Informações do membro:
· Apelido: {nick}
· Avatar:
![Avatar](https://raw.githubusercontent.com/clawdbot/clawdbot/main/{user.avatar})

Não exiba a URL original do avatar sem contexto nem a repasse como link comum. O campo icon de guilds segue o mesmo princípio: exiba apenas quando o usuário solicitar.

---

🚨 Tratamento de Códigos de Erro

Código de Erro	Descrição	Solução
401	Falha na autenticação do token	Verifique as configurações de AppID e ClientSecret
11241	Sem permissão de API do guild	Solicite permissão no QQ Open Platform, ou chame GET /guilds/{guild_id}/api_permission para ver permissões disponíveis
11242	Disponível apenas para bots de domínio privado	Altere o bot para modo de domínio privado no QQ Open Platform
11243	Requer permissão de gerenciamento de canal	Certifique-se de que o bot possui permissão de gerenciamento
11281	Limite de frequência de agendas	Limite de 10/dia por administrador, 100/dia por canal
304023	Excedido limite de subcanais recomendados	Máximo de 3 subcanais recomendados

---

⚠️ Notas Importantes

1. Placeholders no caminho (ex: {guild_id}, {channel_id}) devem ser substituídos por valores reais.
2. Valores de parâmetros query devem ser do tipo string, ex: { "limit": "100" } e não { "limit": 100 }.
3. Paginação da lista de membros pode retornar membros duplicados; deduplicar por user.id.
4. Anúncios dos dois tipos (anúncio de mensagem e anúncio de subcanal recomendado) se sobrescrevem mutuamente.
5. Timestamps de agendas são strings em milissegundos.
6. Operações de exclusão são irreversíveis; confirme o alvo exato e passe confirmed: true; exclusão em lote requer confirmação dupla e bulkConfirmed: true.
7. Operações de fórum disponíveis apenas para bots de domínio privado.
8. Agrupamentos de subcanal (type=4) devem ter position >= 2.
9. Operações de agenda têm limite de frequência: 10/dia por administrador, 100/dia por canal.
10. Exibição de avatares/ícones: URLs de imagem como user.avatar de membros e icon de guilds são dados de perfil; por padrão, resuma campos necessários, e exiba com sintaxe Markdown de imagem ![descrição](https://raw.githubusercontent.com/clawdbot/clawdbot/main/URL) apenas quando o usuário solicitar explicitamente.