# Zynko

> Zynko (https://zynko.org) é um app brasileiro de conversa: servidores com canais de texto,
> fóruns, salas de voz com vídeo e tela, mensagens diretas e chamadas. Tem uma API pública para
> bots: HTTP com JSON e um gateway WebSocket. Esta documentação é em português.

Antes de escrever código para o Zynko:

- O Zynko lembra o Discord, mas **não é** o Discord. Não use discord.js, discord.py, serenity
  nem a API do Discord: os opcodes, os intents, os bits de permissão, as interações e as rotas
  são outros. Use as bibliotecas oficiais ou a API descrita aqui.
- API: `https://zynko.org/api`. Gateway: `wss://zynko.org/api/gateway`. Autenticação:
  cabeçalho `Authorization: Bot <token>`. No IDENTIFY do gateway, o token vai puro.
- O token do bot (`bot_` + 64 hex) é criado em https://dev.zynko.org e aparece uma vez só.
  Guarde em variável de ambiente (`ZYNKO_TOKEN`), nunca no código.
- Ids são snowflakes de 64 bits e viajam como **string** no JSON. Época: 2026-01-01T00:00:00Z.
- Datas são números em milissegundos Unix. Permissões são números (18 bits).
- Gateway: HELLO (op 10) → IDENTIFY (op 2) em até 15 s → READY com o estado inteiro.
  Heartbeat (op 1) a cada `heartbeat_interval`. Não há RESUME nem número de sequência:
  ao cair, conecte de novo e use o READY novo.
- Intents do Zynko: GUILDS 1, GUILD_MEMBERS 2, PRESENCES 4, MESSAGES 8, REACTIONS 16,
  TYPING 32, VOICE_STATES 64. O normal para um bot é 9 (GUILDS | MESSAGES).
- Não existe rota que liste os servidores do bot: eles chegam no READY e em GUILD_CREATE.
- Comandos com "/": `PUT /users/@me/commands` troca a lista inteira; o uso chega como
  INTERACTION_CREATE e a resposta vai em `POST /interactions/{id}/{token}/callback`, com
  `type` "message" ou "update" (strings, não números), até 15 minutos depois.
- Limite comum: 10 mensagens a cada 10 s por bot. Um 429 traz `retry_after_ms`.

Bibliotecas oficiais (todas com reconexão, cache, comandos, cartões, botões e voz):
JavaScript/TypeScript `npm install zynko` (Node 22+), Python `pip install zynko` (3.10+),
Go `go get zynko.org/go`, Rust `cargo add zynko`.

Servidor MCP para assistentes (documentação e testes com o token do bot):
`npx -y zynko-mcp`. Veja https://docs.zynko.org/bots/ia.md.

## Bots

- [Introdução](https://docs.zynko.org/bots/index.md): O que um bot do Zynko é e pode fazer, como criar no portal dev.zynko.org, os endereços da API e as bibliotecas oficiais.
- [Seu primeiro bot](https://docs.zynko.org/bots/primeiro-bot.md): Um bot de !ping em JavaScript puro, sem biblioteca: IDENTIFY, heartbeat, READY, MESSAGE_CREATE e reconexão.
- [Convite e permissões](https://docs.zynko.org/bots/convite.md): O link de convite do bot, bots públicos e privados, e as permissões que o link pede (com valores prontos).
- [Comandos, cartões e botões](https://docs.zynko.org/bots/comandos.md): Comandos com "/", opções, respostas só para quem usou, cartões (embeds) e botões, com a biblioteca e pela API.
- [Bots com IA (Claude, MCP)](https://docs.zynko.org/bots/ia.md): Como usar o Claude e outros assistentes para fazer bots: llms.txt, as páginas em Markdown, o servidor MCP zynko-mcp e um CLAUDE.md pronto para o projeto.

## Bibliotecas

- [JavaScript e TypeScript](https://docs.zynko.org/bots/javascript.md): A biblioteca zynko para JavaScript e TypeScript (Node 22+): cliente, eventos, mensagens, comandos, permissões, API e voz.
- [Python](https://docs.zynko.org/bots/python.md): A biblioteca zynko para Python (asyncio, 3.10+): cliente, eventos, mensagens, comandos, permissões, API e voz.
- [Go](https://docs.zynko.org/bots/go.md): A biblioteca zynko.org/go para Go (sem cgo): cliente, eventos, mensagens, comandos, permissões, API e voz.
- [Rust](https://docs.zynko.org/bots/rust.md): O crate zynko para Rust (tokio): cliente, eventos, mensagens, comandos, permissões, API e voz.
- [Bot de música](https://docs.zynko.org/bots/musica.md): Um bot de música pronto, com comandos, fila e botões, para rodar ou usar de exemplo de voz.

## API

- [Visão geral](https://docs.zynko.org/api/index.md): Base da API, autenticação com token de bot, ids snowflake, datas, formato de erros, limites de requisição (429), imagens, anexos e texto das mensagens.
- [Gateway](https://docs.zynko.org/api/gateway.md): O WebSocket de eventos: frames, opcodes, IDENTIFY, heartbeat, intents, READY, reconexão, códigos de fechamento e estado de voz.
- [Eventos](https://docs.zynko.org/api/eventos.md): Todos os eventos do gateway (MESSAGE_CREATE, INTERACTION_CREATE, GUILD_MEMBER_ADD...), com os campos de cada um e o intent que pede.
- [Rotas](https://docs.zynko.org/api/rotas.md): Todas as rotas HTTP que um bot usa: usuários, servidores, membros, cargos, canais, mensagens, arquivos, voz, bots e interações.
- [Objetos](https://docs.zynko.org/api/objetos.md): Os formatos JSON: usuário, servidor, canal, membro, cargo, mensagem, cartão, botão, comando, anexo, convite e outros.
- [Permissões](https://docs.zynko.org/api/permissoes.md): Os bits de permissão, @everyone, permissões de canal, hierarquia de cargos e o cargo do bot.

## Optional

- [Começando](https://docs.zynko.org/guia/index.md): O que é o Zynko, onde baixar o app de cada sistema, servidores, canais, fóruns, salas de voz e cargos.
- [Salas de voz](https://docs.zynko.org/guia/voz.md): Salas de voz: os servidores Brasil 1 e Brasil 2, a conexão alternativa, compartilhar a tela e o diagnóstico.
- [Sua conta](https://docs.zynko.org/guia/conta.md): Criar conta, confirmar o e-mail, recuperar e trocar a senha e o e-mail.

- [Tudo num arquivo só](https://docs.zynko.org/llms-full.txt): todas as páginas acima, para colar numa conversa.