Skip to content
MarkdownBots com IA

Painel da empresa (widgets) ​

Todo servidor Empresa tem um Painel: uma página, ao lado do Escritório, com widgets que quem gerencia o servidor monta e que todo mundo da empresa vê. Ele é programável: um bot com a permissão Gerenciar servidor (MANAGE_GUILD) cria e atualiza widgets pela API, e cada mudança aparece na hora para todos.

Ideias: as vendas do dia vindas do ERP, os chamados abertos do suporte, o status dos sistemas, o cardápio da semana, um dashboard do Grafana.

Os tipos ​

kindo que mostradata
noteTexto com formatação, como numa mensagem.{ "text": "**Reunião** às 10h" } (até 4000 caracteres)
numbersAté 12 números com nome.{ "items": [{ "label": "Vendas", "value": "R$ 12.400", "hint": "meta R$ 15 mil" }] }
cardUm cartão igual aos das mensagens de bot.{ "card": { "title": "…", "fields": [ … ] } } (veja cartões)
embedUma página https dentro do painel.{ "url": "https://…", "height": 360 } (altura de 120 a 900)

Em numbers, label vai até 60 caracteres, value até 24 (número ou texto) e hint até 80. Uma página (embed) precisa permitir ser exibida em outros sites, e páginas do próprio Zynko não podem entrar. Campos que o tipo não usa são descartados.

As rotas ​

Todas pedem um token de bot (ou de pessoa) com MANAGE_GUILD no servidor, menos a listagem, que qualquer membro faz.

rotacorpo
listarGET /api/v1/guilds/{guild_id}/widgets
criarPOST /api/v1/guilds/{guild_id}/widgets{ "kind", "title", "width"?, "data"? }
atualizarPATCH /api/v1/guilds/{guild_id}/widgets/{widget_id}{ "title"?, "width"?, "data"? }
reordenarPATCH /api/v1/guilds/{guild_id}/widgets{ "order": [ids de todos os widgets] }
removerDELETE /api/v1/guilds/{guild_id}/widgets/{widget_id}

width é 1 ou 2 (colunas da grade). Em PATCH, data substitui o conteúdo inteiro. O painel tem até 30 widgets. Todos os membros recebem o evento GUILD_WIDGETS_UPDATE com a lista inteira a cada mudança.

O widget ​

json
{
  "id": "117070000000000000",
  "guild_id": "117060000000000000",
  "kind": "numbers",
  "title": "Vendas",
  "position": 0,
  "width": 2,
  "data": { "items": [{ "label": "Hoje", "value": "43" }] },
  "updated_at": 1795136000000,
  "updated_by": "117069000000000000"
}

Exemplo: um bot que atualiza as vendas ​

O ID do widget aparece no app (menu do widget → Copiar ID do widget) ou na listagem.

js
const API = 'https://zynko.org/api/v1';
const headers = { Authorization: `Bot ${process.env.ZYNKO_TOKEN}`, 'Content-Type': 'application/json' };

async function atualizar(guildId, widgetId, vendasHoje, chamados) {
  const res = await fetch(`${API}/guilds/${guildId}/widgets/${widgetId}`, {
    method: 'PATCH',
    headers,
    body: JSON.stringify({
      data: {
        items: [
          { label: 'Vendas hoje', value: vendasHoje.toLocaleString('pt-BR', { style: 'currency', currency: 'BRL' }) },
          { label: 'Chamados abertos', value: chamados, hint: 'fila do suporte' },
        ],
      },
    }),
  });
  if (!res.ok) throw new Error(`${res.status} ${await res.text()}`);
}

// A cada 5 minutos, com os números do seu sistema.
setInterval(() => atualizar('117060000000000000', '117070000000000000', 12400, 7), 5 * 60_000);

O bot precisa estar no servidor com Gerenciar servidor: marque essa permissão no link de convite (permissions com o bit 2, veja Convite e permissões).

Zynko · zynko.org