Quickstart

1. Create an application

Opening an application in the portal creates a bot user behind it. The application name becomes the bot’s display name.

2. Mint a token and keep it

Mint a token on the application page. It is shown once; if you lose it you have to rotate.

TALKITH_BOT_TOKEN=nsb_...
TALKITH_API_ORIGIN=https://api.talkith.com
TALKITH_GATEWAY_ORIGIN=wss://api.talkith.com

Never commit the token. If you suspect it leaked, revoke it in the portal — the old token dies immediately.

3. Connect to the gateway

The socket opens with HELLO, you authenticate with IDENTIFY, and heartbeat on the interval HELLO gave you.

const socket = new WebSocket(
  `${process.env.TALKITH_GATEWAY_ORIGIN}/gateway/bot`
);

socket.addEventListener('message', (event) => {
  const frame = JSON.parse(event.data);

  if (frame.op === 'HELLO') {
    // HELLO kalp atışı aralığını taşır; IDENTIFY ile kimliği bildir.
    socket.send(JSON.stringify({
      op: 'IDENTIFY',
      d: {
        token: process.env.TALKITH_BOT_TOKEN,
        intents: ['APPLICATION_COMMANDS', 'SERVER_MESSAGES'],
      },
    }));

    setInterval(
      () => socket.send(JSON.stringify({ op: 'HEARTBEAT' })),
      frame.d.heartbeatInterval
    );
  }
});

A heartbeat with no HEARTBEAT_ACK means the connection is gone; back off progressively when reconnecting.

4. Register your commands

Slash commands are registered by the bot, not in the portal. This endpoint replaces the whole list.

await fetch(`${API}/api/bot/v1/commands`, {
  method: 'PUT',
  headers: {
    Authorization: `Bot ${token}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    commands: [
      { name: 'ping', description: 'Botun ayakta olduğunu doğrular' },
    ],
  }),
});

Commands you leave out are deleted. The registered list is visible on the application page.

5. Answer the command

When a user runs the command an APPLICATION_COMMAND arrives; answer the interaction promptly.

if (frame.op === 'DISPATCH' && frame.t === 'APPLICATION_COMMAND') {
  const interactionId = frame.d.interactionId;

  await fetch(
    `${API}/api/bot/v1/interactions/${interactionId}/response`,
    {
      method: 'POST',
      headers: {
        Authorization: `Bot ${token}`,
        'Content-Type': 'application/json',
      },
      body: JSON.stringify({ content: 'pong' }),
    }
  );
}

If the work is slow, defer first and update the response once the result is ready.

6. Take the rest from the reference

Messages, reactions, attachments, voice and WHIP are all in the reference, with parameters and bodies.