Hızlı başlangıç

Bu rehberde küçük bir manifestten özel bir Kit oluşturacak, çalışma alanınıza kuracak, botunu bir kanala ekleyecek, bir bot token’ı oluşturacak ve Blocks içeren bir mesaj göndereceksiniz: önce curl ile, sonra @ketvia/kit SDK’sı ile. Sonda iki dakikalık bir gelen webhook seçeneği var.

Gerekenler: bir Ketvia çalışma alanında yönetici yetkisi, üyesi olduğunuz bir kanal ve curl olan bir terminal. SDK adımı için Node.js 22 veya üstü.

1. Manifesti yazın

Manifest, Kit’inizin ne olduğunu ve neler yapabileceğini söyleyen JSON belgesidir. Bunu manifest.json olarak kaydedin; slug değerini, adları ve adresleri değiştirin:

manifest.json

{
  "schemaVersion": 1,
  "slug": "hello-acme",
  "version": "0.1.0",
  "displayName": { "en": "Hello Acme" },
  "description": { "en": "Posts a first message through the Ketvia Web API." },
  "developer": {
    "name": "Acme Inc.",
    "url": "https://acme.example",
    "supportEmail": "[email protected]"
  },
  "privacyPolicyUrl": "https://acme.example/privacy",
  "bot": {
    "displayName": { "en": "Hello Acme" },
    "scopes": ["conversations:read", "messages:write"]
  },
  "distribution": "private"
}

• slug tüm Ketvia genelinde tektir: başkasının almamış olacağı bir değer seçin (küçük harf, rakam ve kısa çizgi; 2 ile 40 karakter; harfle başlar). Bazı slug’lar ayrılmıştır.
• bot.scopes iki izin ister: Kit botunun eklendiği kanalları listelemek (conversations:read) ve mesaj göndermek (messages:write). Bkz. Kapsamlar.
• Tüm adresler https olmalıdır. Bilinmeyen anahtarlar reddedilir. Görünen metinlerde en zorunlu, tr isteğe bağlıdır. Tüm alanlar manifest başvurusunda.

2. Kit’i oluşturun ve kurun

1. Ketvia web uygulamasında Yönetim → Bağlantılar sayfasını (“Kit’ler ve bağlantılar”, https://ketvia.com/app/w/<workspaceId>/yonetim/baglantilar) açın.

2. Özel Kit oluştur’u seçin, manifesti yapıştırın ve onaylayın. Ketvia manifesti doğrular; bir sorun varsa alanın yolunu gösterir.

3. Kit ekle ile yeni Kit’inizi kurun. Kurulum yalnızca bu çalışma alanına aittir.

4. Kit’in sayfasını açın ve API erişimi bölümüne gidin.

5. Kanallar bölümünde Kit botunu mesaj göndermek istediğiniz kanala ekleyin. Yalnızca üyesi olduğunuz kanalları ekleyebilirsiniz.

6. Bir bot token’ı oluşturun. kbot_ ile başlar ve yalnızca bir kez gösterilir: hemen kopyalayın. Ketvia token’ın yalnızca özetini (hash) saklar; kaybolan bir token yeniden gösterilemez. İptal edip yenisini oluşturun.

Token’ı kaynak koda koymayın. Terminalinizde:

export KETVIA_TOKEN='kbot_…'

3. Token’ı kontrol edin

GET /auth/test, token’ın ne olduğunu ve neler yapabileceğini söyler.

curl -s https://api.ketvia.com/api/v1/auth/test \
  -H "Authorization: Bearer $KETVIA_TOKEN"

{
  "ok": true,
  "tokenType": "bot",
  "workspaceId": "0b9f6c1e-2f4d-4c55-9a51-6f7f3c1d2e10",
  "installationId": "5d1a8e7c-93b2-4f3e-8c0d-2a6b4e9f1c37",
  "kitSlug": "hello-acme",
  "botId": "9c4e2b7a-1d3f-4a6e-b8c5-0f2d7e6a9b14",
  "userId": null,
  "scopes": ["conversations:read", "messages:write"]
}

invalid_token ile gelen bir 401, token’ın yanlış yazıldığı, iptal edildiği ya da Kit’in kaldırıldığı anlamına gelir.

4. Kanalı bulun

Kit botu yalnızca eklendiği kanalları görür:

curl -s https://api.ketvia.com/api/v1/conversations \
  -H "Authorization: Bearer $KETVIA_TOKEN"

{
  "conversations": [
    {
      "id": "3e7c1a9d-5b2f-4d8e-a6c4-1f0b9e2d7a53",
      "kind": "channel",
      "visibility": "public",
      "name": "deployments",
      "topic": null,
      "archived": false,
      "createdAt": "2026-09-14T08:12:44.000Z"
    }
  ],
  "nextCursor": null
}

export CHANNEL_ID='3e7c1a9d-5b2f-4d8e-a6c4-1f0b9e2d7a53'

5. Blocks ile mesaj gönderin

text zorunludur: bildirimler ve arama onu kullanır. blocks isteğe bağlıdır ve kart olarak görünür. Idempotency-Key başlığı yeniden denemeyi güvenli kılar: aynı anahtarla 24 saat içinde tekrar gönderirseniz mesaj ikinci kez gönderilmez, kayıtlı mesaj döner.

curl -s https://api.ketvia.com/api/v1/messages \
  -H "Authorization: Bearer $KETVIA_TOKEN" \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: quickstart-hello-1' \
  -d @- <<EOF
{
  "conversationId": "$CHANNEL_ID",
  "text": "Hello from Hello Acme",
  "blocks": [
    { "type": "header", "text": "Hello from a Kit" },
    {
      "type": "section",
      "text": { "type": "mrkdwn", "text": "This message was posted with the *Ketvia Web API*." }
    },
    {
      "type": "fields",
      "fields": [
        { "label": "Kit", "value": "hello-acme" },
        { "label": "Version", "value": "0.1.0" }
      ]
    },
    { "type": "context", "elements": [{ "type": "plain", "text": "Sent by the quickstart" }] }
  ]
}
EOF

Yanıt, mesajla birlikte 201 Created olur (aynı anahtarla tekrar, aynı mesajı 200 ile döndürür):

{
  "message": {
    "id": "7a2d9f4b-6c1e-4b3a-9e8d-5f0c2b1a7d64",
    "conversationId": "3e7c1a9d-5b2f-4d8e-a6c4-1f0b9e2d7a53",
    "author": { "kind": "bot", "id": "9c4e2b7a-1d3f-4a6e-b8c5-0f2d7e6a9b14" },
    "text": "Hello from Hello Acme",
    "blocks": [{ "type": "header", "text": "Hello from a Kit" }],
    "threadParentId": null,
    "createdAt": "2026-10-05T09:30:00.000Z",
    "editedAt": null,
    "deletedAt": null
  }
}

(blocks dizisi burada kısaltıldı.) Kanalı Ketvia’da açın: mesaj orada, Kit botu tarafından gönderilmiş olarak duruyor.

İpucu

Burada bir 404 çoğunlukla Kit botunun o kanala eklenmediği anlamına gelir: bir token, göremediği bir konuşmanın var olup olmadığını hiçbir zaman öğrenemez. missing_scope ile gelen bir 403, eksik kapsamı X-Ketvia-Required-Scope başlığında bildirir.

6. Aynısı SDK ile

@ketvia/kit, Web API için çalışma zamanı bağımlılığı olmayan küçük bir TypeScript istemcisidir.

npm install @ketvia/kit

hello.ts

import { KetviaClient, blocks } from '@ketvia/kit';

const ketvia = new KetviaClient({ token: process.env.KETVIA_TOKEN ?? '' });

const me = await ketvia.auth.test();
console.log(`Token for ${me.kitSlug} with scopes ${me.scopes.join(', ')}`);

const { conversations } = await ketvia.conversations.list();
const channel = conversations.find((conversation) => conversation.name === 'deployments');
if (!channel) throw new Error('Add the Kit bot to #deployments first');

const { message, created } = await ketvia.messages.post(
  {
    conversationId: channel.id,
    text: 'Hello from Hello Acme',
    blocks: [
      blocks.header('Hello from a Kit'),
      blocks.section(blocks.mrkdwn('This message was posted with the *Ketvia SDK*.')),
      blocks.fields({ Kit: 'hello-acme', Version: '0.1.0' }),
      blocks.context(['Sent by the quickstart']),
    ],
  },
  { idempotencyKey: 'quickstart-hello-2' },
);
console.log(created ? `Posted ${message.id}` : `Already posted ${message.id}`);

Herhangi bir TypeScript çalıştırıcısıyla çalıştırın, örneğin npx tsx hello.ts. Hatalar status, code ve correlationId alanlarıyla KetviaApiError olarak fırlatılır; bkz. SDK.

İki dakikalık seçenek: gelen webhook

Tek ihtiyacınız bir kanala bildirim göndermekse token’ları tamamen atlayıp gelen webhook kullanın.

1. Bu manifestle özel bir Kit oluşturun (slug’ı değiştirin):

   manifest.json

   {
     "schemaVersion": 1,
     "slug": "acme-ci-notify",
     "version": "0.1.0",
     "displayName": { "en": "Acme CI" },
     "description": { "en": "Posts build results to a channel." },
     "developer": {
       "name": "Acme Inc.",
       "url": "https://acme.dev",
       "supportEmail": "[email protected]"
     },
     "privacyPolicyUrl": "https://acme.dev/privacy",
     "bot": { "displayName": { "en": "Acme CI" }, "scopes": ["incoming-webhook"] },
     "incomingWebhooks": { "maxPerInstallation": 5 },
     "distribution": "private"
   }

2. Kit ekle ile kurun, sayfasını açın, API erişimi bölümünde bir kanal için gelen webhook oluşturun. Kit botu o kanala eklenir. Adres yalnızca bir kez gösterilir; tek kimlik bilgisi odur, bir parola gibi saklayın.

3. Adrese gönderin:

   curl -s -X POST "$KETVIA_WEBHOOK_URL" \
     -H 'Content-Type: application/json' \
     -d '{"text":"Build #42 passed","blocks":[{"type":"header","text":"Build #42 passed"}]}'

   Yanıt {"ok":true} olur ve mesaj kanalda görünür.

Kurallar ve yanıtlar için Gelen webhook’lar, GitHub Actions kurulumu için ci-webhook örneği.

Sonraki adımlar

• Kavramlar: kurulum, Kit botu ve token türleri nedir.
• Token’lar ve kimlik doğrulama: kullanıcı token’ları, yenileme ve kit.access akışı.
• Web API başvurusu: tüm metotlar.