Bot API rehberi

Bot API referansı

Botun konuşabileceği her uç: yol, parametre, gövde ve yanıt. Yapı backend’in OpenAPI belgesinden üretiliyor, açıklamalar elle yazılıyor.

31 uç, backend’in OpenAPI belgesinden üretildi.

Dokümantasyona dön

Kimlik

Token’ın hangi bota ait olduğunu doğrula.

GET/api/bot/v1/users/@me

Token’ın hangi bota ait olduğunu döner.

Bağlantı kurulduktan sonraki ilk çağrı olarak kullanılır; token geçersizse 401 gelir.

Yanıtlar

Örnek istek
curl -X GET 'https://api.talkith.com/api/bot/v1/users/@me' \
  -H 'Authorization: Bot <token>'

Sunucu ve kanal

Kurulu sunucular, kanallar, emoji kataloğu ve ses durumu.

GET/api/bot/v1/servers

Botun kurulu olduğu sunucular.

Yalnızca kurulum yapılmış sunucular listelenir; kurulum kullanıcı tarafından portaldan yapılır.

Yanıtlar

Örnek istek
curl -X GET 'https://api.talkith.com/api/bot/v1/servers' \
  -H 'Authorization: Bot <token>'
GET/api/bot/v1/servers/{serverId}/channels

Bir sunucudaki kanallar.

Botun göremediği kanallar listeye girmez — kanal izin override’ları burada da geçerlidir.

Parametreler

serverIdstring<uuid>pathzorunlu

Yanıtlar

Örnek istek
curl -X GET 'https://api.talkith.com/api/bot/v1/servers/<serverId>/channels' \
  -H 'Authorization: Bot <token>'
GET/api/bot/v1/servers/{serverId}/emojis

Sunucunun özel emoji kataloğu.

Reaksiyon eklerken `customEmojiId` bu listeden gelir.

Parametreler

serverIdstring<uuid>pathzorunlu

Yanıtlar

Örnek istek
curl -X GET 'https://api.talkith.com/api/bot/v1/servers/<serverId>/emojis' \
  -H 'Authorization: Bot <token>'

Mesaj

Okuma, gönderme, düzenleme, silme ve yazıyor göstergesi.

GET/api/bot/v1/channels/{channelId}/messages

Kanal mesajlarını sayfalı okur.

`before` ile eskiye doğru sayfalanır; `limit` varsayılanı 50’dir.

Parametreler

channelIdstring<uuid>pathzorunlu
beforestring<uuid>queryisteğe bağlı
limitinteger<int32>queryvarsayılan: 50

Yanıtlar

Örnek istek
curl -X GET 'https://api.talkith.com/api/bot/v1/channels/<channelId>/messages' \
  -H 'Authorization: Bot <token>'
POST/api/bot/v1/channels/{channelId}/messages

Kanala mesaj gönderir.

Ek dosya göndermek için önce yükleme oturumu aç, dönen anahtarları `attachments` içinde ilet.

Parametreler

channelIdstring<uuid>pathzorunlu

İstek gövdesi CreateBotMessageRequest

contentstringzorunlu
replyToMessageIdstring<uuid>?isteğe bağlı
attachmentsMessageAttachmentDraftRequest[]?isteğe bağlı

Yanıtlar

Örnek istek
curl -X POST 'https://api.talkith.com/api/bot/v1/channels/<channelId>/messages' \
  -H 'Authorization: Bot <token>' \
  -H 'Content-Type: application/json' \
  -d '{"content":"<string>"}'
DELETE/api/bot/v1/channels/{channelId}/messages/{messageId}

Mesajı siler.

Kendi mesajı için yeterli; başkasının mesajı için botun ManageMessages yetkisi gerekir.

Parametreler

channelIdstring<uuid>pathzorunlu
messageIdstring<uuid>pathzorunlu

Yanıtlar

  • 200gövde yok
Örnek istek
curl -X DELETE 'https://api.talkith.com/api/bot/v1/channels/<channelId>/messages/<messageId>' \
  -H 'Authorization: Bot <token>'
GET/api/bot/v1/channels/{channelId}/messages/{messageId}

Tek bir mesajı getirir.

Parametreler

channelIdstring<uuid>pathzorunlu
messageIdstring<uuid>pathzorunlu

Yanıtlar

Örnek istek
curl -X GET 'https://api.talkith.com/api/bot/v1/channels/<channelId>/messages/<messageId>' \
  -H 'Authorization: Bot <token>'
PATCH/api/bot/v1/channels/{channelId}/messages/{messageId}

Botun kendi mesajını düzenler.

Yalnızca botun yazdığı mesajlar düzenlenebilir; başkasının mesajında 403 döner.

Parametreler

channelIdstring<uuid>pathzorunlu
messageIdstring<uuid>pathzorunlu

İstek gövdesi EditMessageRequest

contentstringzorunlu
suppressLinkPreviewbooleanisteğe bağlı

Yanıtlar

Örnek istek
curl -X PATCH 'https://api.talkith.com/api/bot/v1/channels/<channelId>/messages/<messageId>' \
  -H 'Authorization: Bot <token>' \
  -H 'Content-Type: application/json' \
  -d '{"content":"<string>"}'
GET/api/bot/v1/channels/{channelId}/messages/{messageId}/context

Bir mesajın çevresindeki mesajları getirir.

Bir bildirime ya da yanıta bağlam kurmak için; `before` ve `after` sayılarıyla pencere ayarlanır.

Parametreler

channelIdstring<uuid>pathzorunlu
messageIdstring<uuid>pathzorunlu
beforeinteger<int32>queryvarsayılan: 25
afterinteger<int32>queryvarsayılan: 25

Yanıtlar

Örnek istek
curl -X GET 'https://api.talkith.com/api/bot/v1/channels/<channelId>/messages/<messageId>/context' \
  -H 'Authorization: Bot <token>'
POST/api/bot/v1/channels/{channelId}/typing

Kanalda “yazıyor” göstergesi yakar.

Gösterge birkaç saniyede söner; uzun işlemlerde tekrar çağır.

Parametreler

channelIdstring<uuid>pathzorunlu

Yanıtlar

  • 200gövde yok
Örnek istek
curl -X POST 'https://api.talkith.com/api/bot/v1/channels/<channelId>/typing' \
  -H 'Authorization: Bot <token>'

Reaksiyon

Bot adına tepki ver, başkasınınkini kaldır, hepsini temizle.

DELETE/api/bot/v1/channels/{channelId}/messages/{messageId}/reactions

Mesajdaki tüm reaksiyonları temizler.

Botun ManageReactions ya da ManageMessages yetkisi gerekir.

Parametreler

channelIdstring<uuid>pathzorunlu
messageIdstring<uuid>pathzorunlu
Örnek istek
curl -X DELETE 'https://api.talkith.com/api/bot/v1/channels/<channelId>/messages/<messageId>/reactions' \
  -H 'Authorization: Bot <token>'
GET/api/bot/v1/channels/{channelId}/messages/{messageId}/reactions

Mesajın reaksiyon özetini döner.

Parametreler

channelIdstring<uuid>pathzorunlu
messageIdstring<uuid>pathzorunlu
unicodeEmojistringqueryisteğe bağlı
customEmojiIdstring<uuid>queryisteğe bağlı
Örnek istek
curl -X GET 'https://api.talkith.com/api/bot/v1/channels/<channelId>/messages/<messageId>/reactions' \
  -H 'Authorization: Bot <token>'
GET/api/bot/v1/channels/{channelId}/messages/{messageId}/reactions/details

Reaksiyonları veren kullanıcılarla birlikte döner.

Parametreler

channelIdstring<uuid>pathzorunlu
messageIdstring<uuid>pathzorunlu
unicodeEmojistringqueryisteğe bağlı
customEmojiIdstring<uuid>queryisteğe bağlı
Örnek istek
curl -X GET 'https://api.talkith.com/api/bot/v1/channels/<channelId>/messages/<messageId>/reactions/details' \
  -H 'Authorization: Bot <token>'
DELETE/api/bot/v1/channels/{channelId}/messages/{messageId}/reactions/me

Botun kendi reaksiyonunu kaldırır.

Parametreler

channelIdstring<uuid>pathzorunlu
messageIdstring<uuid>pathzorunlu

İstek gövdesi ReactionMutationRequest

unicodeEmojistring?zorunlu
customEmojiIdstring<uuid>?zorunlu
Örnek istek
curl -X DELETE 'https://api.talkith.com/api/bot/v1/channels/<channelId>/messages/<messageId>/reactions/me' \
  -H 'Authorization: Bot <token>' \
  -H 'Content-Type: application/json' \
  -d '{"unicodeEmoji":"<string?>","customEmojiId":"<string<uuid>?>"}'
PUT/api/bot/v1/channels/{channelId}/messages/{messageId}/reactions/me

Bot adına reaksiyon ekler.

Gövdede ya `unicodeEmoji` ya da `customEmojiId` gönderilir, ikisi birden değil.

Parametreler

channelIdstring<uuid>pathzorunlu
messageIdstring<uuid>pathzorunlu

İstek gövdesi ReactionMutationRequest

unicodeEmojistring?zorunlu
customEmojiIdstring<uuid>?zorunlu
Örnek istek
curl -X PUT 'https://api.talkith.com/api/bot/v1/channels/<channelId>/messages/<messageId>/reactions/me' \
  -H 'Authorization: Bot <token>' \
  -H 'Content-Type: application/json' \
  -d '{"unicodeEmoji":"<string?>","customEmojiId":"<string<uuid>?>"}'
DELETE/api/bot/v1/channels/{channelId}/messages/{messageId}/reactions/users/{userId}

Başka bir kullanıcının reaksiyonunu kaldırır.

Botun ManageReactions yetkisi gerekir.

Parametreler

channelIdstring<uuid>pathzorunlu
messageIdstring<uuid>pathzorunlu
userIdstring<uuid>pathzorunlu

İstek gövdesi ReactionMutationRequest

unicodeEmojistring?zorunlu
customEmojiIdstring<uuid>?zorunlu
Örnek istek
curl -X DELETE 'https://api.talkith.com/api/bot/v1/channels/<channelId>/messages/<messageId>/reactions/users/<userId>' \
  -H 'Authorization: Bot <token>' \
  -H 'Content-Type: application/json' \
  -d '{"unicodeEmoji":"<string?>","customEmojiId":"<string<uuid>?>"}'

Ek dosya

İmzalı yükleme oturumu ve süreli indirme adresi.

GET/api/bot/v1/channels/{channelId}/messages/{messageId}/attachments/{attachmentId}/access-url

Bir ek için süreli indirme adresi üretir.

Adres kısa ömürlüdür; saklamak yerine ihtiyaç anında üret.

Parametreler

channelIdstring<uuid>pathzorunlu
messageIdstring<uuid>pathzorunlu
attachmentIdstring<uuid>pathzorunlu
Örnek istek
curl -X GET 'https://api.talkith.com/api/bot/v1/channels/<channelId>/messages/<messageId>/attachments/<attachmentId>/access-url' \
  -H 'Authorization: Bot <token>'
POST/api/bot/v1/channels/{channelId}/messages/attachments/upload-session

Ek dosya için imzalı yükleme oturumu açar.

Dönen adrese dosyayı doğrudan yükle, sonra mesajı `attachments` ile gönder.

Parametreler

channelIdstring<uuid>pathzorunlu

İstek gövdesi CreateMessageAttachmentUploadSessionRequest

fileNamestringzorunlu
contentTypestringzorunlu
sizeinteger<int64>zorunlu
Örnek istek
curl -X POST 'https://api.talkith.com/api/bot/v1/channels/<channelId>/messages/attachments/upload-session' \
  -H 'Authorization: Bot <token>' \
  -H 'Content-Type: application/json' \
  -d '{"fileName":"<string>","contentType":"<string>","size":"<integer<int64>>"}'

Ses ve WHIP

Ses kanalına katıl, ayrıl ve müzik yayını için ingress aç.

DELETE/api/bot/v1/channels/{channelId}/voice/ingress

WHIP ingress oturumunu kapatır.

Yayın bitince mutlaka çağır; açık kalan oturum kanalda sessiz bir katılımcı bırakır.

Parametreler

channelIdstring<uuid>pathzorunlu

Yanıtlar

  • 200gövde yok
Örnek istek
curl -X DELETE 'https://api.talkith.com/api/bot/v1/channels/<channelId>/voice/ingress' \
  -H 'Authorization: Bot <token>'
POST/api/bot/v1/channels/{channelId}/voice/ingress

WHIP yayını için ingress oturumu açar.

Müzik botları stereo Opus yayınını buradan gönderir; WebRTC yayıncısı olarak bağlanılır.

Parametreler

channelIdstring<uuid>pathzorunlu
Örnek istek
curl -X POST 'https://api.talkith.com/api/bot/v1/channels/<channelId>/voice/ingress' \
  -H 'Authorization: Bot <token>'
POST/api/bot/v1/channels/{channelId}/voice/join

Botu ses kanalına bağlar ve LiveKit token’ı döner.

Dönen token ile LiveKit’e doğrudan bağlanılır; sunucu aracı değildir.

Parametreler

channelIdstring<uuid>pathzorunlu
Örnek istek
curl -X POST 'https://api.talkith.com/api/bot/v1/channels/<channelId>/voice/join' \
  -H 'Authorization: Bot <token>'
POST/api/bot/v1/channels/{channelId}/voice/leave

Botu ses kanalından çıkarır.

Parametreler

channelIdstring<uuid>pathzorunlu

Yanıtlar

  • 200gövde yok
Örnek istek
curl -X POST 'https://api.talkith.com/api/bot/v1/channels/<channelId>/voice/leave' \
  -H 'Authorization: Bot <token>'
GET/api/bot/v1/servers/{serverId}/voice-state

Sunucudaki ses kanallarının anlık katılımcıları.

Anlık bir görüntüdür; değişiklikleri olay geçidinden `VoiceStateChanged` ile takip et.

Parametreler

serverIdstring<uuid>pathzorunlu
Örnek istek
curl -X GET 'https://api.talkith.com/api/bot/v1/servers/<serverId>/voice-state' \
  -H 'Authorization: Bot <token>'

Komut

Slash komutlarını listele ve tümünü birden senkronize et.

GET/api/bot/v1/commands

Uygulamanın kayıtlı slash komutları.

Yanıtlar

Örnek istek
curl -X GET 'https://api.talkith.com/api/bot/v1/commands' \
  -H 'Authorization: Bot <token>'
PUT/api/bot/v1/commands

Komut listesini bütünüyle değiştirir.

Gönderilmeyen komutlar silinir — bu bir birleştirme değil, tam senkronizasyondur.

İstek gövdesi SyncBotCommandsRequest

commandsSyncBotCommandItemDto[]zorunlu

Yanıtlar

Örnek istek
curl -X PUT 'https://api.talkith.com/api/bot/v1/commands' \
  -H 'Authorization: Bot <token>' \
  -H 'Content-Type: application/json' \
  -d '{"commands":"<SyncBotCommandItemDto[]>"}'

Etkileşim

Komut çalıştırıldığında gelen etkileşimi onayla, ertele ve yanıtla.

POST/api/bot/v1/interactions/{interactionId}/ack

Etkileşimi aldığını bildirir.

Kullanıcı komutu çalıştırdıktan sonra kısa sürede yanıtlanmalı; yoksa etkileşim düşer.

Parametreler

interactionIdstring<uuid>pathzorunlu

Yanıtlar

  • 200gövde yok
Örnek istek
curl -X POST 'https://api.talkith.com/api/bot/v1/interactions/<interactionId>/ack' \
  -H 'Authorization: Bot <token>'
POST/api/bot/v1/interactions/{interactionId}/defer

Yanıtı erteler, “düşünüyor” durumu gösterir.

Uzun süren işlerde önce defer et, işlem bitince response ile doldur.

Parametreler

interactionIdstring<uuid>pathzorunlu

Yanıtlar

  • 200gövde yok
Örnek istek
curl -X POST 'https://api.talkith.com/api/bot/v1/interactions/<interactionId>/defer' \
  -H 'Authorization: Bot <token>'
POST/api/bot/v1/interactions/{interactionId}/follow-ups

Yanıtın ardından ek mesaj gönderir.

Parametreler

interactionIdstring<uuid>pathzorunlu

İstek gövdesi CreateBotInteractionResponseRequest

contentstring?zorunlu
replyToMessageIdstring<uuid>?isteğe bağlı
attachmentsMessageAttachmentDraftRequest[]?isteğe bağlı
ephemeralbooleanisteğe bağlı

Yanıtlar

Örnek istek
curl -X POST 'https://api.talkith.com/api/bot/v1/interactions/<interactionId>/follow-ups' \
  -H 'Authorization: Bot <token>' \
  -H 'Content-Type: application/json' \
  -d '{"content":"<string?>"}'
PATCH/api/bot/v1/interactions/{interactionId}/response

Gönderilmiş yanıtı günceller.

Parametreler

interactionIdstring<uuid>pathzorunlu

İstek gövdesi EditMessageRequest

contentstringzorunlu
suppressLinkPreviewbooleanisteğe bağlı

Yanıtlar

Örnek istek
curl -X PATCH 'https://api.talkith.com/api/bot/v1/interactions/<interactionId>/response' \
  -H 'Authorization: Bot <token>' \
  -H 'Content-Type: application/json' \
  -d '{"content":"<string>"}'
POST/api/bot/v1/interactions/{interactionId}/response

Etkileşime yanıt gönderir.

Parametreler

interactionIdstring<uuid>pathzorunlu

İstek gövdesi CreateBotInteractionResponseRequest

contentstring?zorunlu
replyToMessageIdstring<uuid>?isteğe bağlı
attachmentsMessageAttachmentDraftRequest[]?isteğe bağlı
ephemeralbooleanisteğe bağlı

Yanıtlar

Örnek istek
curl -X POST 'https://api.talkith.com/api/bot/v1/interactions/<interactionId>/response' \
  -H 'Authorization: Bot <token>' \
  -H 'Content-Type: application/json' \
  -d '{"content":"<string?>"}'

Şemalar

Uçların döndürdüğü ve beklediği gövdelerin alanları. Bu liste de OpenAPI belgesinden üretiliyor.

BotMeDto
applicationIdstring<uuid>zorunlu
botUserIdstring<uuid>zorunlu
usernamestringzorunlu
displayNamestringzorunlu
BotServerDto
idstring<uuid>zorunlu
namestringzorunlu
memberCountinteger<int32>zorunlu
BotChannelDto
idstring<uuid>zorunlu
serverIdstring<uuid>zorunlu
namestringzorunlu
typestringzorunlu
positioninteger<int32>zorunlu
topicstring?zorunlu
BotCommandDto
idstring<uuid>zorunlu
namestringzorunlu
descriptionstringzorunlu
optionsBotCommandOptionDto[]zorunlu
createdAtstring<date-time>zorunlu
CustomEmojiDto
idstring<uuid>zorunlu
namestringzorunlu
imageUrlstringzorunlu
sourceServerIdstring<uuid>zorunlu
sourceServerNamestringzorunlu
isExternalbooleanzorunlu
isAnimatedbooleanzorunlu
MessagePageDto
messagesMessageDto[]zorunlu
hasMorebooleanzorunlu
oldestIdstring<uuid>?zorunlu
MessageDto
idstring<uuid>zorunlu
channelIdstring<uuid>zorunlu
authorIdstring<uuid>zorunlu
authorUsernamestringzorunlu
authorDisplayNamestringzorunlu
authorAvatarUrlstring?zorunlu
replyToobjectzorunlu
contentstringzorunlu
attachmentsMessageAttachmentDto[]zorunlu
linkPreviewobjectzorunlu
reactionsReactionSummaryDto[]zorunlu
pollobjectzorunlu
forwardedFromobjectzorunlu
editedAtstring<date-time>?zorunlu
pinnedAtstring<date-time>?zorunlu
pinnedByUserIdstring<uuid>?zorunlu
isDeletedbooleanzorunlu
createdAtstring<date-time>zorunlu
EditMessageRequest
contentstringzorunlu
suppressLinkPreviewbooleanisteğe bağlı
MessageContextDto
serverIdstring<uuid>zorunlu
channelIdstring<uuid>zorunlu
messageIdstring<uuid>zorunlu
messagesMessageDto[]zorunlu
hasOlderbooleanzorunlu
hasNewerbooleanzorunlu
CreateMessageAttachmentUploadSessionRequest
fileNamestringzorunlu
contentTypestringzorunlu
sizeinteger<int64>zorunlu
MessageAttachmentUploadSessionDto
uploadUrlstringzorunlu
objectKeystringzorunlu
publicUrlstringzorunlu
fieldsobjectzorunlu
expiresAtstring<date-time>zorunlu
maxBytesinteger<int64>zorunlu
MessageAttachmentAccessUrlDto
attachmentIdstring<uuid>zorunlu
urlstringzorunlu
expiresAtstring<date-time>zorunlu
ReactionMutationRequest
unicodeEmojistring?zorunlu
customEmojiIdstring<uuid>?zorunlu
MessageReactionUpdateDto
channelIdstring<uuid>zorunlu
messageIdstring<uuid>zorunlu
reactionsReactionSummaryDto[]zorunlu
MessageReactionDetailsDto
channelIdstring<uuid>zorunlu
messageIdstring<uuid>zorunlu
reactionsReactionUsersGroupDto[]zorunlu
BotVoiceJoinResponseDto
tokenstringzorunlu
urlstringzorunlu
channelIdstring<uuid>zorunlu
participantsVoiceParticipantDto[]zorunlu
BotVoiceIngressResponseDto
ingressIdstringzorunlu
urlstringzorunlu
streamKeystringzorunlu
channelIdstring<uuid>zorunlu
participantsVoiceParticipantDto[]zorunlu
CreateBotInteractionResponseRequest
contentstring?zorunlu
replyToMessageIdstring<uuid>?isteğe bağlı
attachmentsMessageAttachmentDraftRequest[]?isteğe bağlı
ephemeralbooleanisteğe bağlı

Olay geçidi

REST uçları isteği sen başlattığında çalışır; olay geçidi olan biteni sana bildirir. WebSocket bağlantısı HELLO ile başlar, IDENTIFY ile kimlik doğrular ve intent’lerle hangi olayları istediğini söyler.

Bağlantı çerçeveleri

HELLOsunucudanBağlantı açılır açılmaz sunucudan gelir; kalp atışı aralığını taşır.
IDENTIFYbottanBot token’ını ve istediği intent listesini gönderir.
READYsunucudanKimlik doğrulandı; bot artık olay alabilir.
HEARTBEATbottanHELLO’daki aralıkla düzenli gönderilir.
HEARTBEAT_ACKsunucudanHer kalp atışına verilen yanıt; gelmezse bağlantı ölmüş sayılır.
DISPATCHsunucudanBütün olaylar bu zarfın içinde taşınır; olay adı zarfın alanındadır.

SERVER_MESSAGES

Botun kurulu olduğu sunucularda mesaj olayları.

  • MESSAGE_CREATEKanala yeni mesaj düştü.
  • MESSAGE_UPDATEMevcut bir mesaj düzenlendi.
  • MESSAGE_DELETEBir mesaj silindi; gövdede yalnızca kimlikler bulunur.

MESSAGE_REACTIONS

Mesajlara eklenen ve kaldırılan reaksiyonlar.

  • MESSAGE_REACTION_ADDBir mesaja reaksiyon eklendi.
  • MESSAGE_REACTION_REMOVEBir reaksiyon kaldırıldı.

SERVER_VOICE

Ses kanallarına katılma ve ayrılma.

  • VOICE_STATE_UPDATEBir kullanıcı ses kanalına katıldı ya da ayrıldı.

APPLICATION_COMMANDS

Kullanıcı bir slash komutu çalıştırdığında gelen etkileşim.

  • APPLICATION_COMMANDSlash komutu çalıştırıldı; etkileşim uçlarıyla yanıtlanmalı.