Bot API rehberiBot 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önKimlik
Token’ın hangi bota ait olduğunu doğrula.
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.
Ö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.
Botun kurulu olduğu sunucular.
Yalnızca kurulum yapılmış sunucular listelenir; kurulum kullanıcı tarafından portaldan yapılır.
Örnek istek
curl -X GET 'https://api.talkith.com/api/bot/v1/servers' \
-H 'Authorization: Bot <token>'
GET/api/bot/v1/servers/{serverId}/channelsBir sunucudaki kanallar.
Botun göremediği kanallar listeye girmez — kanal izin override’ları burada da geçerlidir.
Parametreler
| serverId | string<uuid> | path | zorunlu |
|---|
Ö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}/emojisSunucunun özel emoji kataloğu.
Reaksiyon eklerken `customEmojiId` bu listeden gelir.
Parametreler
| serverId | string<uuid> | path | zorunlu |
|---|
Ö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}/messagesKanal mesajlarını sayfalı okur.
`before` ile eskiye doğru sayfalanır; `limit` varsayılanı 50’dir.
Parametreler
| channelId | string<uuid> | path | zorunlu |
|---|
| before | string<uuid> | query | isteğe bağlı |
|---|
| limit | integer<int32> | query | varsayılan: 50 |
|---|
Ö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}/messagesKanala mesaj gönderir.
Ek dosya göndermek için önce yükleme oturumu aç, dönen anahtarları `attachments` içinde ilet.
Parametreler
| channelId | string<uuid> | path | zorunlu |
|---|
İstek gövdesi CreateBotMessageRequest
| content | string | zorunlu |
|---|
| replyToMessageId | string<uuid>? | isteğe bağlı |
|---|
| attachments | MessageAttachmentDraftRequest[]? | isteğe bağlı |
|---|
Ö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
| channelId | string<uuid> | path | zorunlu |
|---|
| messageId | string<uuid> | path | zorunlu |
|---|
Ö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
| channelId | string<uuid> | path | zorunlu |
|---|
| messageId | string<uuid> | path | zorunlu |
|---|
Ö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
| channelId | string<uuid> | path | zorunlu |
|---|
| messageId | string<uuid> | path | zorunlu |
|---|
İstek gövdesi EditMessageRequest
| content | string | zorunlu |
|---|
| suppressLinkPreview | boolean | isteğe bağlı |
|---|
Ö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}/contextBir 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
| channelId | string<uuid> | path | zorunlu |
|---|
| messageId | string<uuid> | path | zorunlu |
|---|
| before | integer<int32> | query | varsayılan: 25 |
|---|
| after | integer<int32> | query | varsayılan: 25 |
|---|
Ö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}/typingKanalda “yazıyor” göstergesi yakar.
Gösterge birkaç saniyede söner; uzun işlemlerde tekrar çağır.
Parametreler
| channelId | string<uuid> | path | zorunlu |
|---|
Ö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}/reactionsMesajdaki tüm reaksiyonları temizler.
Botun ManageReactions ya da ManageMessages yetkisi gerekir.
Parametreler
| channelId | string<uuid> | path | zorunlu |
|---|
| messageId | string<uuid> | path | zorunlu |
|---|
Ö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}/reactionsMesajın reaksiyon özetini döner.
Parametreler
| channelId | string<uuid> | path | zorunlu |
|---|
| messageId | string<uuid> | path | zorunlu |
|---|
| unicodeEmoji | string | query | isteğe bağlı |
|---|
| customEmojiId | string<uuid> | query | isteğ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/detailsReaksiyonları veren kullanıcılarla birlikte döner.
Parametreler
| channelId | string<uuid> | path | zorunlu |
|---|
| messageId | string<uuid> | path | zorunlu |
|---|
| unicodeEmoji | string | query | isteğe bağlı |
|---|
| customEmojiId | string<uuid> | query | isteğ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/meBotun kendi reaksiyonunu kaldırır.
Parametreler
| channelId | string<uuid> | path | zorunlu |
|---|
| messageId | string<uuid> | path | zorunlu |
|---|
İstek gövdesi ReactionMutationRequest
| unicodeEmoji | string? | zorunlu |
|---|
| customEmojiId | string<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/meBot adına reaksiyon ekler.
Gövdede ya `unicodeEmoji` ya da `customEmojiId` gönderilir, ikisi birden değil.
Parametreler
| channelId | string<uuid> | path | zorunlu |
|---|
| messageId | string<uuid> | path | zorunlu |
|---|
İstek gövdesi ReactionMutationRequest
| unicodeEmoji | string? | zorunlu |
|---|
| customEmojiId | string<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
| channelId | string<uuid> | path | zorunlu |
|---|
| messageId | string<uuid> | path | zorunlu |
|---|
| userId | string<uuid> | path | zorunlu |
|---|
İstek gövdesi ReactionMutationRequest
| unicodeEmoji | string? | zorunlu |
|---|
| customEmojiId | string<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-urlBir ek için süreli indirme adresi üretir.
Adres kısa ömürlüdür; saklamak yerine ihtiyaç anında üret.
Parametreler
| channelId | string<uuid> | path | zorunlu |
|---|
| messageId | string<uuid> | path | zorunlu |
|---|
| attachmentId | string<uuid> | path | zorunlu |
|---|
Ö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-sessionEk dosya için imzalı yükleme oturumu açar.
Dönen adrese dosyayı doğrudan yükle, sonra mesajı `attachments` ile gönder.
Parametreler
| channelId | string<uuid> | path | zorunlu |
|---|
İstek gövdesi CreateMessageAttachmentUploadSessionRequest
| fileName | string | zorunlu |
|---|
| contentType | string | zorunlu |
|---|
| size | integer<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/ingressWHIP ingress oturumunu kapatır.
Yayın bitince mutlaka çağır; açık kalan oturum kanalda sessiz bir katılımcı bırakır.
Parametreler
| channelId | string<uuid> | path | zorunlu |
|---|
Ö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/ingressWHIP 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
| channelId | string<uuid> | path | zorunlu |
|---|
Ö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/joinBotu 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
| channelId | string<uuid> | path | zorunlu |
|---|
Ö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/leaveBotu ses kanalından çıkarır.
Parametreler
| channelId | string<uuid> | path | zorunlu |
|---|
Ö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-stateSunucudaki 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
| serverId | string<uuid> | path | zorunlu |
|---|
Ö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.
Uygulamanın kayıtlı slash komutları.
Örnek istek
curl -X GET 'https://api.talkith.com/api/bot/v1/commands' \
-H 'Authorization: Bot <token>'
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
| commands | SyncBotCommandItemDto[] | zorunlu |
|---|
Ö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}/ackEtkileşimi aldığını bildirir.
Kullanıcı komutu çalıştırdıktan sonra kısa sürede yanıtlanmalı; yoksa etkileşim düşer.
Parametreler
| interactionId | string<uuid> | path | zorunlu |
|---|
Ö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}/deferYanıtı erteler, “düşünüyor” durumu gösterir.
Uzun süren işlerde önce defer et, işlem bitince response ile doldur.
Parametreler
| interactionId | string<uuid> | path | zorunlu |
|---|
Ö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-upsYanıtın ardından ek mesaj gönderir.
Parametreler
| interactionId | string<uuid> | path | zorunlu |
|---|
İstek gövdesi CreateBotInteractionResponseRequest
| content | string? | zorunlu |
|---|
| replyToMessageId | string<uuid>? | isteğe bağlı |
|---|
| attachments | MessageAttachmentDraftRequest[]? | isteğe bağlı |
|---|
| ephemeral | boolean | isteğe bağlı |
|---|
Ö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}/responseGönderilmiş yanıtı günceller.
Parametreler
| interactionId | string<uuid> | path | zorunlu |
|---|
İstek gövdesi EditMessageRequest
| content | string | zorunlu |
|---|
| suppressLinkPreview | boolean | isteğe bağlı |
|---|
Ö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}/responseEtkileşime yanıt gönderir.
Parametreler
| interactionId | string<uuid> | path | zorunlu |
|---|
İstek gövdesi CreateBotInteractionResponseRequest
| content | string? | zorunlu |
|---|
| replyToMessageId | string<uuid>? | isteğe bağlı |
|---|
| attachments | MessageAttachmentDraftRequest[]? | isteğe bağlı |
|---|
| ephemeral | boolean | isteğe bağlı |
|---|
Ö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.
| applicationId | string<uuid> | zorunlu |
|---|
| botUserId | string<uuid> | zorunlu |
|---|
| username | string | zorunlu |
|---|
| displayName | string | zorunlu |
|---|
| id | string<uuid> | zorunlu |
|---|
| name | string | zorunlu |
|---|
| memberCount | integer<int32> | zorunlu |
|---|
| id | string<uuid> | zorunlu |
|---|
| serverId | string<uuid> | zorunlu |
|---|
| name | string | zorunlu |
|---|
| type | string | zorunlu |
|---|
| position | integer<int32> | zorunlu |
|---|
| topic | string? | zorunlu |
|---|
| id | string<uuid> | zorunlu |
|---|
| name | string | zorunlu |
|---|
| description | string | zorunlu |
|---|
| options | BotCommandOptionDto[] | zorunlu |
|---|
| createdAt | string<date-time> | zorunlu |
|---|
| id | string<uuid> | zorunlu |
|---|
| name | string | zorunlu |
|---|
| imageUrl | string | zorunlu |
|---|
| sourceServerId | string<uuid> | zorunlu |
|---|
| sourceServerName | string | zorunlu |
|---|
| isExternal | boolean | zorunlu |
|---|
| isAnimated | boolean | zorunlu |
|---|
| messages | MessageDto[] | zorunlu |
|---|
| hasMore | boolean | zorunlu |
|---|
| oldestId | string<uuid>? | zorunlu |
|---|
| id | string<uuid> | zorunlu |
|---|
| channelId | string<uuid> | zorunlu |
|---|
| authorId | string<uuid> | zorunlu |
|---|
| authorUsername | string | zorunlu |
|---|
| authorDisplayName | string | zorunlu |
|---|
| authorAvatarUrl | string? | zorunlu |
|---|
| replyTo | object | zorunlu |
|---|
| content | string | zorunlu |
|---|
| attachments | MessageAttachmentDto[] | zorunlu |
|---|
| linkPreview | object | zorunlu |
|---|
| reactions | ReactionSummaryDto[] | zorunlu |
|---|
| poll | object | zorunlu |
|---|
| forwardedFrom | object | zorunlu |
|---|
| editedAt | string<date-time>? | zorunlu |
|---|
| pinnedAt | string<date-time>? | zorunlu |
|---|
| pinnedByUserId | string<uuid>? | zorunlu |
|---|
| isDeleted | boolean | zorunlu |
|---|
| createdAt | string<date-time> | zorunlu |
|---|
| content | string | zorunlu |
|---|
| suppressLinkPreview | boolean | isteğe bağlı |
|---|
| serverId | string<uuid> | zorunlu |
|---|
| channelId | string<uuid> | zorunlu |
|---|
| messageId | string<uuid> | zorunlu |
|---|
| messages | MessageDto[] | zorunlu |
|---|
| hasOlder | boolean | zorunlu |
|---|
| hasNewer | boolean | zorunlu |
|---|
CreateMessageAttachmentUploadSessionRequest| fileName | string | zorunlu |
|---|
| contentType | string | zorunlu |
|---|
| size | integer<int64> | zorunlu |
|---|
MessageAttachmentUploadSessionDto| uploadUrl | string | zorunlu |
|---|
| objectKey | string | zorunlu |
|---|
| publicUrl | string | zorunlu |
|---|
| fields | object | zorunlu |
|---|
| expiresAt | string<date-time> | zorunlu |
|---|
| maxBytes | integer<int64> | zorunlu |
|---|
MessageAttachmentAccessUrlDto| attachmentId | string<uuid> | zorunlu |
|---|
| url | string | zorunlu |
|---|
| expiresAt | string<date-time> | zorunlu |
|---|
| unicodeEmoji | string? | zorunlu |
|---|
| customEmojiId | string<uuid>? | zorunlu |
|---|
MessageReactionDetailsDtoBotVoiceIngressResponseDto| ingressId | string | zorunlu |
|---|
| url | string | zorunlu |
|---|
| streamKey | string | zorunlu |
|---|
| channelId | string<uuid> | zorunlu |
|---|
| participants | VoiceParticipantDto[] | zorunlu |
|---|
CreateBotInteractionResponseRequestOlay 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
| HELLO | sunucudan | Bağlantı açılır açılmaz sunucudan gelir; kalp atışı aralığını taşır. |
|---|
| IDENTIFY | bottan | Bot token’ını ve istediği intent listesini gönderir. |
|---|
| READY | sunucudan | Kimlik doğrulandı; bot artık olay alabilir. |
|---|
| HEARTBEAT | bottan | HELLO’daki aralıkla düzenli gönderilir. |
|---|
| HEARTBEAT_ACK | sunucudan | Her kalp atışına verilen yanıt; gelmezse bağlantı ölmüş sayılır. |
|---|
| DISPATCH | sunucudan | Bü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ı.