Desenvolvedores
Construa com o Zync
Bots com token próprio, comandos de barra e webhooks de entrada. A API pública fica em https://usezync.com/api/v1.
1. Começo rápido
- Em Configurações → Desenvolvedor, crie a aplicação e copie o token.
- Em Adicionar a um servidor, coloque o bot num servidor que você gerencia.
- Copie o ID de um canal (botão direito no canal → Copiar ID do canal) e mande a primeira mensagem:
curl -X POST "https://usezync.com/api/v1/channels/<channel-id>/messages" \
-H "Authorization: Bot $ZYNC_TOKEN" \
-H "Content-Type: application/json" \
-d '{"content":"Olá, servidor! 👋"}'
const res = await fetch('https://usezync.com/api/v1/channels/<channel-id>/messages', {
method: 'POST',
headers: { Authorization: `Bot ${process.env.ZYNC_TOKEN}`, 'Content-Type': 'application/json' },
body: JSON.stringify({
"content": "Olá, servidor! 👋"
}),
});
if (!res.ok) throw new Error((await res.json()).error.message);
console.log(await res.json());
import os
import requests
res = requests.post(
"https://usezync.com/api/v1/channels/<channel-id>/messages",
headers={"Authorization": f"Bot {os.environ['ZYNC_TOKEN']}"},
json={
"content": "Olá, servidor! 👋"
},
)
res.raise_for_status()
print(res.json())
Pronto: a mensagem aparece no canal com o nome do bot e o selo Bot.
Comece por aqui: o bot de exemplo já traz comandos de barra, interações assinadas e um webhook, em JavaScript e sem dependências. Não programa? Crie um bot sem programar.
2. Crie a aplicação
No app, abra Configurações → Desenvolvedor:
- Criar aplicação: ela ganha uma conta de bot, com o selo Bot.
- Copie o token. Ele aparece uma vez só; Gerar novo token invalida o anterior na hora.
- Em Adicionar a um servidor, coloque o bot num servidor que você gerencia.
3. Autenticação
Toda chamada do bot leva o cabeçalho:
Authorization: Bot zb.<app-id>.<secret>
O bot usa as mesmas rotas do app para listar os canais, ler e enviar mensagens, editar e apagar as próprias mensagens e reagir:
GET /api/v1/servers/:serverId/channels
GET /api/v1/channels/:channelId/messages
POST /api/v1/channels/:channelId/messages
PATCH /api/v1/messages/:messageId
DELETE /api/v1/messages/:messageId
PUT /api/v1/messages/:messageId/reactions/:emoji
DELETE /api/v1/messages/:messageId/reactions/:emoji
GET /api/v1/channels/:channelId/pins
PUT /api/v1/messages/:messageId/pin
DELETE /api/v1/messages/:messageId/pin
GET /api/v1/search/messages
PUT /api/v1/applications/:applicationId/commands
Cada rota tem exemplos em curl, JavaScript e Python na referência das rotas.
As rotas de conta (senha, sessões, amizades, criar servidor) respondem 403 BOT_FORBIDDEN. Guarde o token como uma senha: quem tem o token age como o bot.
4. Mensagens
Para enviar, mande o texto em content. Os campos opcionais são:
replyToId: responde a uma mensagem do mesmo canal;nonce: 8 a 64 caracteres. Reenviar com o mesmononcenão duplica a mensagem.
POST /api/v1/channels/:id/messages
Authorization: Bot <token>
Content-Type: application/json
{
"content": "Deploy concluído ✅",
"replyToId": "<id da mensagem>",
"nonce": "deploy-2026-11-07-01"
}
- Uma mensagem vai até 4000 caracteres e aceita a formatação do chat (negrito, listas, código, menções).
- Para ler, use
GET /channels/:id/messages: vem da mais nova para a mais antiga, até 100 por página (50 por padrão). Para as anteriores, passebefore=<id da mais antiga>. - O bot só vê e escreve nos canais em que os cargos dele dão permissão, como qualquer membro.
5. Comandos de barra
Registre a lista de comandos (cada chamada substitui a lista inteira):
curl -X PUT "https://usezync.com/api/v1/applications/<app-id>/commands" \
-H "Authorization: Bot $ZYNC_TOKEN" \
-H "Content-Type: application/json" \
-d '[{"name":"clima","description":"Previsão do tempo","options":[{"name":"cidade","description":"Qual cidade","required":true}]}]'
const res = await fetch('https://usezync.com/api/v1/applications/<app-id>/commands', {
method: 'PUT',
headers: { Authorization: `Bot ${process.env.ZYNC_TOKEN}`, 'Content-Type': 'application/json' },
body: JSON.stringify([
{
"name": "clima",
"description": "Previsão do tempo",
"options": [
{
"name": "cidade",
"description": "Qual cidade",
"required": true
}
]
}
]),
});
if (!res.ok) throw new Error((await res.json()).error.message);
console.log(await res.json());
import os
import requests
res = requests.put(
"https://usezync.com/api/v1/applications/<app-id>/commands",
headers={"Authorization": f"Bot {os.environ['ZYNC_TOKEN']}"},
json=[
{
"name": "clima",
"description": "Previsão do tempo",
"options": [
{
"name": "cidade",
"description": "Qual cidade",
"required": True
}
]
}
],
)
res.raise_for_status()
print(res.json())
- até 25 comandos por aplicação;
- nome com até 32 caracteres
[a-z0-9_-]; - até 5 opções de texto por comando.
Quem participa do servidor digita / no campo de mensagem e vê os comandos. O texto depois do nome vai para a primeira opção (/clima Recife); para várias opções, use opção: valor.
6. Interações
Defina a URL de interações da aplicação. Cada comando chega nela assim:
POST <interactions URL>
Content-Type: application/json
X-Zync-Timestamp: 1794012351192
X-Zync-Signature: sha256=<hex>
{
"type": "command",
"id": "…",
"applicationId": "…",
"serverId": "…",
"channelId": "…",
"command": { "name": "clima", "options": { "cidade": "Recife" } },
"user": { "id": "…", "username": "rafa", "displayName": "Rafa" },
"timestamp": "2026-11-06T21:00:00.000Z"
}
A assinatura é HMAC-SHA256(segredo de assinatura, "<X-Zync-Timestamp>.<corpo>"). O segredo fica em Configurações → Desenvolvedor → Mostrar segredo de assinatura. Confira a assinatura e recuse timestamps com mais de 5 minutos:
import { createHmac, timingSafeEqual } from 'node:crypto';
function verify(req, rawBody, signingSecret) {
const ts = req.headers['x-zync-timestamp'];
const sig = req.headers['x-zync-signature'] ?? '';
if (!ts || Math.abs(Date.now() - Number(ts)) > 5 * 60_000) return false;
const expected =
'sha256=' + createHmac('sha256', signingSecret).update(`${ts}.${rawBody}`).digest('hex');
return sig.length === expected.length && timingSafeEqual(Buffer.from(sig), Buffer.from(expected));
}
Responda com status 200 em até 3 segundos:
HTTP/1.1 200 OK
Content-Type: application/json
{ "content": "Recife: 31 °C e sol.", "ephemeral": false }
"ephemeral": false(padrão): o bot publica a resposta no canal, com "Fulano usou /clima"."ephemeral": true: só quem usou vê, e nada fica no canal.
Sem resposta a tempo, ou fora do formato, quem usou o comando vê que o bot não respondeu (502 INTERACTION_FAILED). A URL precisa ser pública, em http(s) nas portas padrão; endereços privados e de loopback são recusados, e redirecionamentos não são seguidos.
7. Webhooks de entrada
Em Editar canal → Webhooks (permissão Gerenciar webhooks), crie um webhook e copie a URL — ela aparece uma vez só. Qualquer serviço publica no canal com:
curl -X POST "https://usezync.com/api/v1/webhooks/<webhook-id>/<webhook-token>" \
-H "Content-Type: application/json" \
-d '{"content":"Versão 1.2 publicada ✅"}'
const res = await fetch('https://usezync.com/api/v1/webhooks/<webhook-id>/<webhook-token>', {
method: 'POST',
headers: { 'Content-Type': 'application/json' },
body: JSON.stringify({
"content": "Versão 1.2 publicada ✅"
}),
});
if (!res.ok) throw new Error((await res.json()).error.message);
console.log(await res.json());
import requests
res = requests.post(
"https://usezync.com/api/v1/webhooks/<webhook-id>/<webhook-token>",
json={
"content": "Versão 1.2 publicada ✅"
},
)
res.raise_for_status()
print(res.json())
- a mensagem sai com o nome do webhook e o selo Bot;
- o texto vai até 2000 caracteres e aceita a formatação do chat;
- apagar o webhook invalida a URL na hora.
8. Tempo real
Hoje o canal de tempo real do Zync (o gateway) é o dos apps e aceita só sessões de pessoas. Por isso os bots ainda não recebem eventos ao vivo. Um bot fica sabendo do que acontece de dois jeitos:
- comandos de barra, que chegam na hora na URL de interações;
- consulta às mensagens do canal com
GET /channels/:id/messages, sem passar de uma chamada a cada poucos segundos.
Eventos em tempo real para bots estão no roadmap. Quando saírem, esta página explica a conexão.
9. Limites e erros
| O quê | Limite |
|---|---|
| Chamadas à API | 600 por minuto por endereço IP |
| Mensagens enviadas | 10 a cada 10 segundos por conta (o mesmo das pessoas) |
| Tamanho da mensagem | 4000 caracteres (2000 nas respostas de comando e nos webhooks) |
| Comandos | 25 por aplicação, 5 opções por comando |
| Resposta de interação | 3 segundos |
| Webhooks | 10 por canal |
Todo erro volta em JSON, dentro de error, com um code estável para o seu código e uma message legível. Passou do limite? Espere o tempo de error.details.retryAfterMs e tente de novo:
HTTP/1.1 429 Too Many Requests
Content-Type: application/json
{
"error": {
"code": "RATE_LIMITED",
"message": "Você está enviando mensagens rápido demais. Espere um pouco.",
"requestId": "4df2399b-6650-44dc-be61-c61fc284f76f",
"details": { "retryAfterMs": 4200 }
}
}
400 VALIDATION_FAILED: corpo inválido, com o campo emdetails;401 UNAUTHORIZED: token ausente ou revogado;403 BOT_FORBIDDEN: rota só para pessoas;403 FORBIDDEN: falta permissão no canal;404 NOT_FOUND: o canal, a mensagem ou o servidor não existe ou não está visível para o bot;429 RATE_LIMITED: passou do limite;502 INTERACTION_FAILED: sua URL de interações não respondeu a tempo.
10. Referência das rotas
Os exemplos usam o token em ZYNC_TOKEN (no shell, export ZYNC_TOKEN=zb.…). Troque os valores entre < > pelos IDs do seu servidor; no app, botão direito → Copiar ID. O JavaScript roda no Node 18 ou mais novo; o Python usa requests.
Listar os canais de um servidor
GET /api/v1/servers/:serverId/channels
curl -X GET "https://usezync.com/api/v1/servers/<server-id>/channels" \
-H "Authorization: Bot $ZYNC_TOKEN"
const res = await fetch('https://usezync.com/api/v1/servers/<server-id>/channels', {
method: 'GET',
headers: { Authorization: `Bot ${process.env.ZYNC_TOKEN}` },
});
if (!res.ok) throw new Error((await res.json()).error.message);
console.log(await res.json());
import os
import requests
res = requests.get(
"https://usezync.com/api/v1/servers/<server-id>/channels",
headers={"Authorization": f"Bot {os.environ['ZYNC_TOKEN']}"},
)
res.raise_for_status()
print(res.json())
Ler as mensagens de um canal
GET /api/v1/channels/:channelId/messages
curl -X GET "https://usezync.com/api/v1/channels/<channel-id>/messages?limit=50" \
-H "Authorization: Bot $ZYNC_TOKEN"
const res = await fetch('https://usezync.com/api/v1/channels/<channel-id>/messages?limit=50', {
method: 'GET',
headers: { Authorization: `Bot ${process.env.ZYNC_TOKEN}` },
});
if (!res.ok) throw new Error((await res.json()).error.message);
console.log(await res.json());
import os
import requests
res = requests.get(
"https://usezync.com/api/v1/channels/<channel-id>/messages?limit=50",
headers={"Authorization": f"Bot {os.environ['ZYNC_TOKEN']}"},
)
res.raise_for_status()
print(res.json())
Enviar uma mensagem
POST /api/v1/channels/:channelId/messages
curl -X POST "https://usezync.com/api/v1/channels/<channel-id>/messages" \
-H "Authorization: Bot $ZYNC_TOKEN" \
-H "Content-Type: application/json" \
-d '{"content":"Deploy concluído ✅","nonce":"deploy-2026-11-07-01"}'
const res = await fetch('https://usezync.com/api/v1/channels/<channel-id>/messages', {
method: 'POST',
headers: { Authorization: `Bot ${process.env.ZYNC_TOKEN}`, 'Content-Type': 'application/json' },
body: JSON.stringify({
"content": "Deploy concluído ✅",
"nonce": "deploy-2026-11-07-01"
}),
});
if (!res.ok) throw new Error((await res.json()).error.message);
console.log(await res.json());
import os
import requests
res = requests.post(
"https://usezync.com/api/v1/channels/<channel-id>/messages",
headers={"Authorization": f"Bot {os.environ['ZYNC_TOKEN']}"},
json={
"content": "Deploy concluído ✅",
"nonce": "deploy-2026-11-07-01"
},
)
res.raise_for_status()
print(res.json())
Editar uma mensagem do bot
PATCH /api/v1/messages/:messageId
curl -X PATCH "https://usezync.com/api/v1/messages/<message-id>" \
-H "Authorization: Bot $ZYNC_TOKEN" \
-H "Content-Type: application/json" \
-d '{"content":"Deploy concluído ✅ (v1.2)"}'
const res = await fetch('https://usezync.com/api/v1/messages/<message-id>', {
method: 'PATCH',
headers: { Authorization: `Bot ${process.env.ZYNC_TOKEN}`, 'Content-Type': 'application/json' },
body: JSON.stringify({
"content": "Deploy concluído ✅ (v1.2)"
}),
});
if (!res.ok) throw new Error((await res.json()).error.message);
console.log(await res.json());
import os
import requests
res = requests.patch(
"https://usezync.com/api/v1/messages/<message-id>",
headers={"Authorization": f"Bot {os.environ['ZYNC_TOKEN']}"},
json={
"content": "Deploy concluído ✅ (v1.2)"
},
)
res.raise_for_status()
print(res.json())
Apagar uma mensagem do bot
DELETE /api/v1/messages/:messageId
curl -X DELETE "https://usezync.com/api/v1/messages/<message-id>" \
-H "Authorization: Bot $ZYNC_TOKEN"
const res = await fetch('https://usezync.com/api/v1/messages/<message-id>', {
method: 'DELETE',
headers: { Authorization: `Bot ${process.env.ZYNC_TOKEN}` },
});
if (!res.ok) throw new Error((await res.json()).error.message);
import os
import requests
res = requests.delete(
"https://usezync.com/api/v1/messages/<message-id>",
headers={"Authorization": f"Bot {os.environ['ZYNC_TOKEN']}"},
)
res.raise_for_status()
Reagir com um emoji
PUT /api/v1/messages/:messageId/reactions/:emoji
curl -X PUT "https://usezync.com/api/v1/messages/<message-id>/reactions/%F0%9F%91%8D" \
-H "Authorization: Bot $ZYNC_TOKEN"
const res = await fetch('https://usezync.com/api/v1/messages/<message-id>/reactions/%F0%9F%91%8D', {
method: 'PUT',
headers: { Authorization: `Bot ${process.env.ZYNC_TOKEN}` },
});
if (!res.ok) throw new Error((await res.json()).error.message);
import os
import requests
res = requests.put(
"https://usezync.com/api/v1/messages/<message-id>/reactions/%F0%9F%91%8D",
headers={"Authorization": f"Bot {os.environ['ZYNC_TOKEN']}"},
)
res.raise_for_status()
Tirar a reação
DELETE /api/v1/messages/:messageId/reactions/:emoji
curl -X DELETE "https://usezync.com/api/v1/messages/<message-id>/reactions/%F0%9F%91%8D" \
-H "Authorization: Bot $ZYNC_TOKEN"
const res = await fetch('https://usezync.com/api/v1/messages/<message-id>/reactions/%F0%9F%91%8D', {
method: 'DELETE',
headers: { Authorization: `Bot ${process.env.ZYNC_TOKEN}` },
});
if (!res.ok) throw new Error((await res.json()).error.message);
import os
import requests
res = requests.delete(
"https://usezync.com/api/v1/messages/<message-id>/reactions/%F0%9F%91%8D",
headers={"Authorization": f"Bot {os.environ['ZYNC_TOKEN']}"},
)
res.raise_for_status()
Listar as mensagens fixadas
GET /api/v1/channels/:channelId/pins
curl -X GET "https://usezync.com/api/v1/channels/<channel-id>/pins" \
-H "Authorization: Bot $ZYNC_TOKEN"
const res = await fetch('https://usezync.com/api/v1/channels/<channel-id>/pins', {
method: 'GET',
headers: { Authorization: `Bot ${process.env.ZYNC_TOKEN}` },
});
if (!res.ok) throw new Error((await res.json()).error.message);
console.log(await res.json());
import os
import requests
res = requests.get(
"https://usezync.com/api/v1/channels/<channel-id>/pins",
headers={"Authorization": f"Bot {os.environ['ZYNC_TOKEN']}"},
)
res.raise_for_status()
print(res.json())
Fixar uma mensagem
PUT /api/v1/messages/:messageId/pin
curl -X PUT "https://usezync.com/api/v1/messages/<message-id>/pin" \
-H "Authorization: Bot $ZYNC_TOKEN"
const res = await fetch('https://usezync.com/api/v1/messages/<message-id>/pin', {
method: 'PUT',
headers: { Authorization: `Bot ${process.env.ZYNC_TOKEN}` },
});
if (!res.ok) throw new Error((await res.json()).error.message);
import os
import requests
res = requests.put(
"https://usezync.com/api/v1/messages/<message-id>/pin",
headers={"Authorization": f"Bot {os.environ['ZYNC_TOKEN']}"},
)
res.raise_for_status()
Desafixar
DELETE /api/v1/messages/:messageId/pin
curl -X DELETE "https://usezync.com/api/v1/messages/<message-id>/pin" \
-H "Authorization: Bot $ZYNC_TOKEN"
const res = await fetch('https://usezync.com/api/v1/messages/<message-id>/pin', {
method: 'DELETE',
headers: { Authorization: `Bot ${process.env.ZYNC_TOKEN}` },
});
if (!res.ok) throw new Error((await res.json()).error.message);
import os
import requests
res = requests.delete(
"https://usezync.com/api/v1/messages/<message-id>/pin",
headers={"Authorization": f"Bot {os.environ['ZYNC_TOKEN']}"},
)
res.raise_for_status()
Buscar mensagens
GET /api/v1/search/messages
curl -X GET "https://usezync.com/api/v1/search/messages?q=deploy&channelId=<channel-id>" \
-H "Authorization: Bot $ZYNC_TOKEN"
const res = await fetch('https://usezync.com/api/v1/search/messages?q=deploy&channelId=<channel-id>', {
method: 'GET',
headers: { Authorization: `Bot ${process.env.ZYNC_TOKEN}` },
});
if (!res.ok) throw new Error((await res.json()).error.message);
console.log(await res.json());
import os
import requests
res = requests.get(
"https://usezync.com/api/v1/search/messages?q=deploy&channelId=<channel-id>",
headers={"Authorization": f"Bot {os.environ['ZYNC_TOKEN']}"},
)
res.raise_for_status()
print(res.json())
Registrar os comandos de barra
PUT /api/v1/applications/:applicationId/commands
curl -X PUT "https://usezync.com/api/v1/applications/<app-id>/commands" \
-H "Authorization: Bot $ZYNC_TOKEN" \
-H "Content-Type: application/json" \
-d '[{"name":"clima","description":"Previsão do tempo","options":[{"name":"cidade","description":"Qual cidade","required":true}]}]'
const res = await fetch('https://usezync.com/api/v1/applications/<app-id>/commands', {
method: 'PUT',
headers: { Authorization: `Bot ${process.env.ZYNC_TOKEN}`, 'Content-Type': 'application/json' },
body: JSON.stringify([
{
"name": "clima",
"description": "Previsão do tempo",
"options": [
{
"name": "cidade",
"description": "Qual cidade",
"required": true
}
]
}
]),
});
if (!res.ok) throw new Error((await res.json()).error.message);
console.log(await res.json());
import os
import requests
res = requests.put(
"https://usezync.com/api/v1/applications/<app-id>/commands",
headers={"Authorization": f"Bot {os.environ['ZYNC_TOKEN']}"},
json=[
{
"name": "clima",
"description": "Previsão do tempo",
"options": [
{
"name": "cidade",
"description": "Qual cidade",
"required": True
}
]
}
],
)
res.raise_for_status()
print(res.json())
Publicar por um webhook
POST /api/v1/webhooks/:webhookId/:token
curl -X POST "https://usezync.com/api/v1/webhooks/<webhook-id>/<webhook-token>" \
-H "Content-Type: application/json" \
-d '{"content":"Versão 1.2 publicada ✅"}'
const res = await fetch('https://usezync.com/api/v1/webhooks/<webhook-id>/<webhook-token>', {
method: 'POST',
headers: { 'Content-Type': 'application/json' },
body: JSON.stringify({
"content": "Versão 1.2 publicada ✅"
}),
});
if (!res.ok) throw new Error((await res.json()).error.message);
console.log(await res.json());
import requests
res = requests.post(
"https://usezync.com/api/v1/webhooks/<webhook-id>/<webhook-token>",
json={
"content": "Versão 1.2 publicada ✅"
},
)
res.raise_for_status()
print(res.json())
Dúvidas
Para usar comandos e webhooks no app, veja Bots e integrações na central de ajuda. Achou uma falha de segurança? Siga a página Segurança.