Desarrolladores
Construye con Zync
Bots con token propio, comandos de barra y webhooks de entrada. La API pública está en https://usezync.com/api/v1.
1. Inicio rápido
- En Configuración → Desarrollador, crea la aplicación y copia el token.
- En Añadir a un servidor, pon el bot en un servidor que gestionas.
- Copia el ID de un canal (clic derecho en el canal → Copiar ID del canal) y envía el primer mensaje:
curl -X POST "https://usezync.com/api/v1/channels/<channel-id>/messages" \
-H "Authorization: Bot $ZYNC_TOKEN" \
-H "Content-Type: application/json" \
-d '{"content":"¡Hola, 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": "¡Hola, 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": "¡Hola, servidor! 👋"
},
)
res.raise_for_status()
print(res.json())
Listo: el mensaje aparece en el canal con el nombre del bot y la insignia Bot.
Empieza aquí: el bot de ejemplo ya trae comandos de barra, interacciones firmadas y un webhook, en JavaScript y sin dependencias. ¿No programas? Crea un bot sin programar.
2. Crea la aplicación
En la app, abre Configuración → Desarrollador:
- Crear aplicación: recibe una cuenta de bot, con la insignia Bot.
- Copia el token. Aparece una sola vez; Generar nuevo token invalida el anterior al instante.
- En Añadir a un servidor, pon el bot en un servidor que gestiones.
3. Autenticación
Cada llamada del bot lleva la cabecera:
Authorization: Bot zb.<app-id>.<secret>
El bot usa las mismas rutas que la app para listar canales, leer y enviar mensajes, editar y borrar sus propios mensajes y reaccionar:
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 ruta tiene ejemplos en curl, JavaScript y Python en la referencia de rutas.
Las rutas de cuenta (contraseña, sesiones, amistades, crear servidor) responden 403 BOT_FORBIDDEN. Guarda el token como una contraseña: quien lo tiene actúa como el bot.
4. Mensajes
Para enviar, pon el texto en content. Los campos opcionales son:
replyToId: responde a un mensaje del mismo canal;nonce: de 8 a 64 caracteres. Reenviar con el mismononceno duplica el mensaje.
POST /api/v1/channels/:id/messages
Authorization: Bot <token>
Content-Type: application/json
{
"content": "Deploy terminado ✅",
"replyToId": "<id da mensagem>",
"nonce": "deploy-2026-11-07-01"
}
- Un mensaje admite hasta 4000 caracteres y el formato del chat (negrita, listas, código, menciones).
- Para leer, usa
GET /channels/:id/messages: del más nuevo al más antiguo, hasta 100 por página (50 por defecto). Para los anteriores, pasabefore=<id del más antiguo>. - El bot solo ve y escribe en los canales que sus roles permiten, como cualquier miembro.
5. Comandos de barra
Registra la lista de comandos (cada llamada reemplaza la lista completa):
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":"Pronóstico del tiempo","options":[{"name":"ciudad","description":"Qué ciudad","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": "Pronóstico del tiempo",
"options": [
{
"name": "ciudad",
"description": "Qué ciudad",
"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": "Pronóstico del tiempo",
"options": [
{
"name": "ciudad",
"description": "Qué ciudad",
"required": True
}
]
}
],
)
res.raise_for_status()
print(res.json())
- hasta 25 comandos por aplicación;
- nombre de hasta 32 caracteres
[a-z0-9_-]; - hasta 5 opciones de texto por comando.
Quien participa del servidor escribe / en el campo de mensaje y ve los comandos. El texto después del nombre va a la primera opción (/clima Bogotá); para varias opciones, usa opción: valor.
6. Interacciones
Define la URL de interacciones de la aplicación. Cada comando llega así:
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": { "ciudad": "Bogotá" } },
"user": { "id": "…", "username": "rafa", "displayName": "Rafa" },
"timestamp": "2026-11-06T21:00:00.000Z"
}
La firma es HMAC-SHA256(secreto de firma, "<X-Zync-Timestamp>.<cuerpo>"). El secreto está en Configuración → Desarrollador → Mostrar secreto de firma. Verifica la firma y rechaza timestamps de más 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));
}
Responde con estado 200 en menos de 3 segundos:
HTTP/1.1 200 OK
Content-Type: application/json
{ "content": "Bogotá: 19 °C y nublado.", "ephemeral": false }
"ephemeral": false(por defecto): el bot publica la respuesta en el canal, con "Alguien usó /clima"."ephemeral": true: solo quien lo usó la ve, y nada queda en el canal.
Si la respuesta no llega a tiempo o tiene otro formato, quien usó el comando ve que el bot no respondió (502 INTERACTION_FAILED). La URL debe ser pública, http(s) en los puertos estándar; las direcciones privadas y de loopback se rechazan, y no se siguen redirecciones.
7. Webhooks de entrada
En Editar canal → Webhooks (permiso Gestionar webhooks), crea un webhook y copia la URL — aparece una sola vez. Cualquier servicio publica en el canal con:
curl -X POST "https://usezync.com/api/v1/webhooks/<webhook-id>/<webhook-token>" \
-H "Content-Type: application/json" \
-d '{"content":"Versión 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": "Versión 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": "Versión 1.2 publicada ✅"
},
)
res.raise_for_status()
print(res.json())
- el mensaje sale con el nombre del webhook y la insignia Bot;
- el texto llega hasta 2000 caracteres y admite el formato del chat;
- borrar el webhook invalida la URL al instante.
8. Tiempo real
Hoy el canal de tiempo real de Zync (el gateway) es el de las apps y solo acepta sesiones de personas. Por eso los bots todavía no reciben eventos en vivo. Un bot se entera de lo que pasa de dos maneras:
- comandos de barra, que llegan al instante a la URL de interacciones;
- consulta de los mensajes del canal con
GET /channels/:id/messages, sin pasar de una llamada cada pocos segundos.
Los eventos en tiempo real para bots están en la hoja de ruta. Cuando salgan, esta página explicará la conexión.
9. Límites y errores
| Qué | Límite |
|---|---|
| Llamadas a la API | 600 por minuto por dirección IP |
| Mensajes enviados | 10 cada 10 segundos por cuenta (igual que las personas) |
| Tamaño del mensaje | 4000 caracteres (2000 en las respuestas de comando y los webhooks) |
| Comandos | 25 por aplicación, 5 opciones por comando |
| Respuesta de interacción | 3 segundos |
| Webhooks | 10 por canal |
Todo error vuelve en JSON, dentro de error, con un code estable para tu código y un message legible en portugués (traduce por code, como hacen las apps de Zync). ¿Pasaste el límite? Espera el tiempo de error.details.retryAfterMs e inténtalo de nuevo:
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: cuerpo inválido, con el campo endetails;401 UNAUTHORIZED: token ausente o revocado;403 BOT_FORBIDDEN: ruta solo para personas;403 FORBIDDEN: falta permiso en el canal;404 NOT_FOUND: el canal, el mensaje o el servidor no existe o no es visible para el bot;429 RATE_LIMITED: pasaste el límite;502 INTERACTION_FAILED: tu URL de interacciones no respondió a tiempo.
10. Referencia de rutas
Los ejemplos leen el token de ZYNC_TOKEN (en el shell, export ZYNC_TOKEN=zb.…). Cambia los valores entre < > por los IDs de tu servidor; en la app, clic derecho → Copiar ID. El JavaScript corre en Node 18 o más nuevo; el Python usa requests.
Listar los canales de un 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())
Leer los mensajes de un 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 un mensaje
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 terminado ✅","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 terminado ✅",
"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 terminado ✅",
"nonce": "deploy-2026-11-07-01"
},
)
res.raise_for_status()
print(res.json())
Editar un mensaje del 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 terminado ✅ (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 terminado ✅ (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 terminado ✅ (v1.2)"
},
)
res.raise_for_status()
print(res.json())
Borrar un mensaje del 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()
Reaccionar con un 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()
Quitar la reacción
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 los mensajes fijados
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())
Fijar un mensaje
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()
Desfijar
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 mensajes
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 los 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":"Pronóstico del tiempo","options":[{"name":"ciudad","description":"Qué ciudad","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": "Pronóstico del tiempo",
"options": [
{
"name": "ciudad",
"description": "Qué ciudad",
"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": "Pronóstico del tiempo",
"options": [
{
"name": "ciudad",
"description": "Qué ciudad",
"required": True
}
]
}
],
)
res.raise_for_status()
print(res.json())
Publicar por un 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":"Versión 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": "Versión 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": "Versión 1.2 publicada ✅"
},
)
res.raise_for_status()
print(res.json())
Dudas
Para usar comandos y webhooks en la app, mira Bots e integraciones en el centro de ayuda. ¿Encontraste un fallo de seguridad? Sigue la página Seguridad.