Developers
Build with Zync
Bots with their own token, slash commands and incoming webhooks. The public API lives at https://usezync.com/api/v1.
1. Quick start
- In Settings → Developer, create the application and copy the token.
- In Add to a server, put the bot in a server you manage.
- Copy a channel ID (right-click the channel → Copy channel ID) and send the first message:
curl -X POST "https://usezync.com/api/v1/channels/<channel-id>/messages" \
-H "Authorization: Bot $ZYNC_TOKEN" \
-H "Content-Type: application/json" \
-d '{"content":"Hello, server! 👋"}'
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": "Hello, server! 👋"
}),
});
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": "Hello, server! 👋"
},
)
res.raise_for_status()
print(res.json())
Done: the message shows up in the channel with the bot’s name and the Bot badge.
Start here: the example bot comes with slash commands, signed interactions and a webhook, in JavaScript with no dependencies. Don’t code? Build a bot without coding.
2. Create the application
In the app, open Settings → Developer:
- Create application: it gets a bot account, with the Bot badge.
- Copy the token. It is shown only once; Generate new token invalidates the old one right away.
- Under Add to a server, put the bot in a server you manage.
3. Authentication
Every bot request carries the header:
Authorization: Bot zb.<app-id>.<secret>
The bot uses the same routes as the app to list channels, read and send messages, edit and delete its own messages, and react:
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
Every route has curl, JavaScript and Python examples in the route reference.
Account routes (password, sessions, friends, creating servers) answer 403 BOT_FORBIDDEN. Keep the token like a password: whoever has it acts as the bot.
4. Messages
To send, put the text in content. The optional fields are:
replyToId: replies to a message in the same channel;nonce: 8 to 64 characters. Resending with the samenoncedoes not duplicate the message.
POST /api/v1/channels/:id/messages
Authorization: Bot <token>
Content-Type: application/json
{
"content": "Deploy finished ✅",
"replyToId": "<id da mensagem>",
"nonce": "deploy-2026-11-07-01"
}
- A message holds up to 4000 characters and supports chat formatting (bold, lists, code, mentions).
- To read, use
GET /channels/:id/messages: newest first, up to 100 per page (50 by default). For older ones, passbefore=<id of the oldest>. - The bot only sees and writes in channels its roles allow, like any member.
5. Slash commands
Register the command list (each call replaces the whole list):
curl -X PUT "https://usezync.com/api/v1/applications/<app-id>/commands" \
-H "Authorization: Bot $ZYNC_TOKEN" \
-H "Content-Type: application/json" \
-d '[{"name":"weather","description":"Weather forecast","options":[{"name":"city","description":"Which city","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": "weather",
"description": "Weather forecast",
"options": [
{
"name": "city",
"description": "Which city",
"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": "weather",
"description": "Weather forecast",
"options": [
{
"name": "city",
"description": "Which city",
"required": True
}
]
}
],
)
res.raise_for_status()
print(res.json())
- up to 25 commands per application;
- names up to 32 characters
[a-z0-9_-]; - up to 5 text options per command.
Server members type / in the message box to see the commands. Text after the name goes to the first option (/weather Lisbon); for several options, use option: value.
6. Interactions
Set the application's Interactions URL. Each command arrives there like this:
POST <interactions URL>
Content-Type: application/json
X-Zync-Timestamp: 1794012351192
X-Zync-Signature: sha256=<hex>
{
"type": "command",
"id": "…",
"applicationId": "…",
"serverId": "…",
"channelId": "…",
"command": { "name": "weather", "options": { "city": "Lisbon" } },
"user": { "id": "…", "username": "rafa", "displayName": "Rafa" },
"timestamp": "2026-11-06T21:00:00.000Z"
}
The signature is HMAC-SHA256(signing secret, "<X-Zync-Timestamp>.<body>"). The secret is under Settings → Developer → Show signing secret. Check the signature and reject timestamps older than 5 minutes:
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));
}
Reply with status 200 within 3 seconds:
HTTP/1.1 200 OK
Content-Type: application/json
{ "content": "Lisbon: 24 °C and sunny.", "ephemeral": false }
"ephemeral": false(default): the bot posts the reply in the channel, with "Someone used /weather"."ephemeral": true: only the person who used it sees it, and nothing stays in the channel.
If the reply doesn't arrive in time or has the wrong format, the person who used the command sees that the bot didn't respond (502 INTERACTION_FAILED). The URL must be public, http(s) on standard ports; private and loopback addresses are refused, and redirects are not followed.
7. Incoming webhooks
In Edit channel → Webhooks (Manage webhooks permission), create a webhook and copy its URL — it is shown only once. Any service posts in the channel with:
curl -X POST "https://usezync.com/api/v1/webhooks/<webhook-id>/<webhook-token>" \
-H "Content-Type: application/json" \
-d '{"content":"Version 1.2 released ✅"}'
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": "Version 1.2 released ✅"
}),
});
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": "Version 1.2 released ✅"
},
)
res.raise_for_status()
print(res.json())
- the message shows the webhook's name and the Bot badge;
- text up to 2000 characters, with chat formatting;
- deleting the webhook invalidates the URL right away.
8. Real time
Today Zync’s real-time channel (the gateway) belongs to the apps and only accepts people’s sessions. That is why bots do not get live events yet. A bot finds out what happens in two ways:
- slash commands, which arrive right away at the interactions URL;
- polling the channel’s messages with
GET /channels/:id/messages, no more than one call every few seconds.
Real-time events for bots are on the roadmap. When they ship, this page will explain the connection.
9. Limits and errors
| What | Limit |
|---|---|
| API calls | 600 per minute per IP address |
| Messages sent | 10 every 10 seconds per account (same as people) |
| Message length | 4000 characters (2000 in command replies and webhooks) |
| Commands | 25 per application, 5 options per command |
| Interaction reply | 3 seconds |
| Webhooks | 10 per channel |
Every error comes back as JSON, inside error, with a stable code for your code and a readable message in Portuguese (translate by code, as the Zync apps do). Over the limit? Wait for error.details.retryAfterMs and try again:
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: invalid body, with the field indetails;401 UNAUTHORIZED: missing or revoked token;403 BOT_FORBIDDEN: route for people only;403 FORBIDDEN: missing permission in the channel;404 NOT_FOUND: the channel, message or server does not exist or is not visible to the bot;429 RATE_LIMITED: over the limit;502 INTERACTION_FAILED: your interactions URL did not answer in time.
10. Route reference
The examples read the token from ZYNC_TOKEN (in the shell, export ZYNC_TOKEN=zb.…). Replace the values between < > with your server’s IDs; in the app, right-click → Copy ID. The JavaScript runs on Node 18 or newer; the Python uses requests.
List a server’s channels
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())
Read a channel’s messages
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())
Send a message
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 finished ✅","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 finished ✅",
"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 finished ✅",
"nonce": "deploy-2026-11-07-01"
},
)
res.raise_for_status()
print(res.json())
Edit a bot message
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 finished ✅ (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 finished ✅ (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 finished ✅ (v1.2)"
},
)
res.raise_for_status()
print(res.json())
Delete a bot message
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()
React with an 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()
Remove the reaction
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()
List pinned messages
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())
Pin a message
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()
Unpin
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()
Search messages
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())
Register slash commands
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":"weather","description":"Weather forecast","options":[{"name":"city","description":"Which city","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": "weather",
"description": "Weather forecast",
"options": [
{
"name": "city",
"description": "Which city",
"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": "weather",
"description": "Weather forecast",
"options": [
{
"name": "city",
"description": "Which city",
"required": True
}
]
}
],
)
res.raise_for_status()
print(res.json())
Post through a 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":"Version 1.2 released ✅"}'
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": "Version 1.2 released ✅"
}),
});
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": "Version 1.2 released ✅"
},
)
res.raise_for_status()
print(res.json())
Questions
To use commands and webhooks in the app, see Bots and integrations in the help center. Found a security issue? Follow the Security page.