---
title: "Slack veya bir sohbet uygulamasından aramaları yürütün"
description: "Genel API'yi kullanarak arama başlatan, aramaları canlı takip eden, yapay zeka ajanını yönlendiren ve sorularını yanıtlayan kendi Slack, Teams veya web sohbet botunuzu oluşturun."
---

Ekibinizin zaten kullandığı sohbet uygulamasından bir ajanı yönlendirebilirsiniz. Bir mesaj
aramayı başlatır. Arama bir ileti dizisinde canlı olarak ilerler. İleti dizisindeki
bir yanıt ajanı yönlendirir. Ajanın bir karara ihtiyacı olduğunda, size orada sorar ve
yanıtınızı bekler.

ThunderPhone bu botu sizin için barındırmaz. Siz (veya kodlama ajanınız), sohbet uygulamanızı
genel API'ye bağlayan küçük bir sunucu oluşturursunuz. Bu sayfa bileşenleri gösterir.
Slack, Microsoft Teams, Discord veya özel bir web sohbet sayfası için aynıdırlar; örneklerde Slack kullanılır.

## Nasıl çalışır

| Sohbette bunu yaparsınız | Botunuz bunu çağırır | Olanlar |
|---|---|---|
| "Comcast'i ara ve kesintinin tahmini bitiş saatini öğren" mesajını gönderin | Mesaj `context` olarak [`POST /v1/call`](/api-reference/outbound-calls) | Ajan arama yapar. Botunuz arama için bir ileti dizisi açar |
| İleti dizisini izleyin | [`telephony.turn`](/tr/webhooks/events) webhook'larını alır | Ajanın veya diğer kişinin söylediği her satır ileti dizisinde görünür |
| Arama sırasında ileti dizisinde yanıt verin | [`POST /v1/calls/{call_id}/whisper`](/api-reference/calls#whisper-to-the-agent) | Ajan notunuzu özel olarak alır ve buna göre hareket eder. Diğer kişi bunu asla duymaz |
| Ajanın sorusunu yanıtlayın | [Araç uç noktanız](/tr/guides/build-tool-integration) yanıtınızı döndürür veya daha sonra [`POST /v1/calls/{call_id}/tool-results`](/api-reference/calls#deliver-a-tool-result) ile iletir | Ajan aramaya bununla devam eder; bekletme modunda diğer kişi bu sırada bekletme müziği duyar |
| Sonucu okuyun | [`telephony.complete`](/tr/webhooks/events) alır | Botunuz özeti ve sonucu gönderir |

Botunuz tek bir eşleme tutar: hangi sohbet ileti dizisinin hangi `call_id` değerine ait olduğu.

## Başlamadan önce

- **Bir API anahtarı**; sunucunuzda saklanmalı, tarayıcıda veya sohbette asla bulunmamalıdır.
  **Entegrasyonlar → API anahtarları** altında bir tane oluşturun (bkz.
  [Sunucu API anahtarı oluşturma](/tr/guides/api-keys)).
- Aramalar için **giden arama etkin bir numara ve bir yapay zeka ajanı**. Mesaj,
  arama başına `context` olur; böylece tek bir genel ajan her görevi yönetir.
- Railway, Fly.io, Render veya kendi barındırıcınız gibi webhook alabilen
  **bir sunucu**.
- Bu sunucuyu işaret eden ve `telephony.turn` ile `telephony.complete`
  aboneliği olan **bir webhook uç noktası**. Tur olayları yalnızca bunları
  listeleyen uç noktalara gönderilir. Bkz. [Webhook'lar](/tr/webhooks/endpoints).
  Tur olayları için ajanın arama kaydının açık olması, arama sonu
  `summary` içinse ajanın **Arama özeti oluştur** ayarının etkin olması gerekir;
  bunlar olmadan bu alanlar boş kalır.
- **Kendi sohbet uygulamanız.** Slack için çalışma alanınızda
  [api.slack.com/apps](https://api.slack.com/apps) adresinden bir uygulama oluşturun.

<Tip>
  Kendi çalışma alanınız için oluşturduğunuz bir Slack uygulamasını kullanın ve kanal geçmişini
  okumak yerine Slack Events API aracılığıyla mesajları alın. Slack, Marketplace dışında
  diğer çalışma alanlarına dağıtılan uygulamalara sıkı okuma sınırları uygular; kendi çalışma
  alanınız için oluşturduğunuz bir uygulama bu sınırlamalara tabi değildir ve olaylar herhangi
  bir okuma işlemi olmadan gerçekleştiği anda size ulaşır. Tipik bot kapsamları: `chat:write`,
  `app_mentions:read`, `im:history` (doğrudan mesajlar), `channels:history` ve
  `groups:history` (botun bulunduğu genel ve özel kanallardaki ileti dizisi yanıtları).
  `app_mention`, `message.im`, `message.channels` ve `message.groups` bot olaylarına abone olun
  ve kişilerin bota doğrudan mesaj gönderebilmesi için App Home altındaki Messages sekmesini açın.
</Tip>

## 1. Bir mesajdan arama başlatın

Botunuz bir mesaj aldığında (doğrudan mesaj veya @bahsetme),
Slack'in isteğini hemen onaylayın (Slack, 3 saniye içinde onaylanmayan her şeyi
yeniden dener) ve kalan işlemleri arka planda yapın. Gönderenin arama yapma
yetkisi olduğunu kontrol edin, ardından mesajı `context` olarak kullanarak
aramayı başlatın:

```bash
curl -X POST https://api.thunderphone.com/v1/call \
  -H "Authorization: Bearer sk_live_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "from_number": "+15551234567",
    "to_number":   "+18005550100",
    "agent_id":    12,
    "context":     "Matthew asked: get the outage ETA for account 4471. Wait on hold if needed.",
    "idempotency_key": "slack-D012AB3CD-1731000000.000100"
  }'
```

Döndürülen `call_id` değerini Slack ileti dizisiyle (`channel` ve mesajın
`ts` değeri) birlikte kaydedin ve ileti dizisinde yanıt verin ("Aranıyor…").
`idempotency_key` değerini kanal ve mesajın `ts` değerinden oluşturun (bir
`ts` yalnızca kendi kanalı içinde benzersizdir); böylece yeniden denenen bir
Slack etkinliği ikinci bir arama başlatmaz. İstek numara yerine bir kişi
belirtiyorsa botunuz önce numarayı bulur. ThunderPhone yalnızca gönderdiğiniz
`to_number` değerini arar.

## 2. Aramayı ileti dizisinde takip edin

Her `telephony.turn` webhook'u `call_id`, konuşmacı (`role`:
ajan için `assistant`, diğer kişi için `user`), `text` ve dönüşün
`position` değerini içerir. İleti dizisini `call_id` ile bulun ve
satırı yayınlayın.

- İşlem yapmadan önce **her webhook'u doğrulayın**. Bkz.
  [Webhook imzalarını doğrulama](/tr/guides/verify-webhook-signatures).
- **Zarfın `event_id` değerine göre yinelenenleri kaldırın ve `position` değerine göre sıralayın.**
  Teslimat en az bir kez yapılır ve dönüşler sırasız gelebilir.
- Yoğun bir arama ileti dizisini dolduracaksa **satırları toplu gönderin**;
  her satır için bir mesaj yerine birkaç saniyede bir gönderi yapmak daha
  okunaklıdır.

`telephony.complete` geldiğinde, aramanın nasıl bittiğini (`status`
ve `end_reason`), `summary` değerini ve çıkarılan tüm verileri yayınlayın,
ardından ileti dizisini kapatın. Alanlar için bkz.
[Arama tamamlandı](/tr/webhooks/call-complete).

## 3. Aramayı ileti dizisinden yönlendirin

Birisi canlı bir aramanın ileti dizisinde yanıt verdiğinde, sesli AI ajanı
bir soru için yanıt beklemiyorsa (4. adım) yanıtı fısıltı olarak gönderin;
bu durumda yanıt, sorunun cevabıdır:

```bash
curl -X POST https://api.thunderphone.com/v1/calls/987654321/whisper \
  -H "Authorization: Bearer sk_live_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"text": "Ask whether they can waive the late fee."}'
```

Ajan bunu özel olarak duyar ve sonraki dönüşüne dahil eder; karşı taraf
fısıltının kendisini asla duymaz. Fısıltı 1 ila 1000 karakter olabilir. Bir
`409`, aramanın artık canlı olmadığı anlamına gelir: ileti dizisine aramanın
sona erdiğini bildirin.

## 4. Ajanın size soru sormasını sağlayın

Ajana, sunucunuzu çağıran tek `question`
parametresine sahip `ask_owner` gibi bir araç verin. Bunu bir
[API bağlantısı](/tr/guides/build-tool-integration) olarak oluşturun ve ajana bağlayın.
Her araç isteği, çağrıyı `X-ThunderPhone-Call-ID` başlığında taşır.

Yanıtı geri almanın üç yolu vardır.

**Aramayı bekletin (10 dakikaya kadar).** Aracı bekletme moduna ayarlayın: `spec.wait_mode`
`"hold"` ve `spec.timeout` en fazla 600 saniye olsun (zaman aşımı olmadan bekletme
20 saniye sürer). Bunu [API](/api-reference/integrations#timeout-and-wait-mode) üzerinden yapabilir veya Zeus'tan
ayarlamasını isteyebilirsiniz (uygulamanın düzenleyicilerinde henüz bu alanların hiçbiri yoktur). Uç noktanız soruyu aramanın ileti dizisine gönderir ve hemen
beklemede olan bir sonuçla yanıt verir:

```json
{"status": "pending", "request_id": "q-C012AB3CD-1731000042.000300"}
```

Karşı taraf ajandan bir cümle duyar, ardından bekletme müziği başlar. Telefon
menüsünde veya sesli mesajda ajan bunun yerine sesli güncellemeler kullanır ve
tam çift yönlü bir ajan bekletmez: bekleyen yanıtı sonuç olarak alır. Yanıt
ileti dizisine ulaştığında, şu yöntemle teslim edin:
[`POST /v1/calls/{call_id}/tool-results`](/api-reference/calls#deliver-a-tool-result):

```bash
curl -X POST https://api.thunderphone.com/v1/calls/987654321/tool-results \
  -H "Authorization: Bearer sk_live_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"request_id": "q-C012AB3CD-1731000042.000300", "result": {"answer": "Yes, book Tuesday at 10."}}'
```

Müzik yavaşça kesilir ve ajan yanıtınızla devam eder. `timeout` süresinden önce
kimse yanıt vermezse, ajana yanıt gelmediği bildirilir ve karşı tarafa sonraki
adımları sunar. Bir çağrı için soru beklemedeyken, ileti dizisindeki sonraki
yanıt soruyu yanıtlar: bunu araç sonucu olarak teslim edin ve ayrıca fısıltı
olarak göndermeyin (fısıltı, aracı yalnızca araç döndükten sonra ajana ulaşır).
Bkz.
[Uzun beklemeler](/tr/tools/overview).

**İstekte bekleyin (3 dakikaya kadar).** Uç noktanız soruyu gönderir,
yanıt bekler ve örneğin `{"answer": "Yes, book Tuesday at 10."}` şeklinde döndürür.
Aracın `spec.timeout` değerini API üzerinden en fazla 180 saniye olarak ayarlayın
(varsayılan değer 20'dir). Uç noktanıza birkaç saniye daha kısa kendi zaman
sınırını verin (örneğin 170 saniye); böylece kimse yanıtlamadığında bile ajanın
işlem yapabileceği bir şey döndürür, örneğin
`{"answer": null, "note": "No reply yet. Offer to take a message."}`. `timeout`
sınırına ulaşan bir araç ajana hata olarak ulaşır ve barındırıcınızın isteği bu
süre boyunca açık tutması gerekir. Beklerken ajan karşı tarafa kontrol ettiğini
söyler, yaklaşık 12 saniye sonra hâlâ çalıştığını belirtir ve ardından yaklaşık
her 15 saniyede bir kısa güncelleme verir. Bekletme modu burada da çalışır:
`spec.wait_mode` değerini `"hold"` olarak ayarlayın; böylece karşı taraf
güncellemeler yerine müzik duyar.

**Fısıltıyla yanıtlayın.** Uç noktanız soruyu gönderir ve hemen döner,
örneğin `{"status": "asked", "note": "Matthew has been asked; his answer will come as guidance."}`.
Yanıt ulaştığında bunu fısıltı olarak gönderin (3. adım) ve ajan
hemen buna yanıt verir. Bunu 10 dakikadan uzun sürebilecek yanıtlar için kullanın.
Çağrı bekletilmez: isteminiz, bu sırada yapay zeka ajanının ne yapacağını
söylemelidir; örneğin karşı tarafa eşlik etmek veya onu geri aramayı teklif etmek.

Her durumda, ajanın isteminde aracı ne zaman kullanacağını ve beklerken karşı
tarafa ne söyleyeceğini belirtin:

```text
When you need Matthew's decision, use ask_owner with a short question.
Tell the person you're checking with Matthew and it may take a minute.
If there's no answer, offer to take a message or have Matthew call back.
```

## Planlama için sınırlar

- Uç noktanız, aracın `timeout` süresi içinde ve en fazla **180 saniye** içinde yanıt vermelidir. Bekletme modundaki bir araç, bekleyen sonuçla aramayı en fazla **600 saniye** bekletebilir.
- Bir araç beklerken ajan karşı taraftaki kişiye yanıt vermez. Bekletme modunda müzik duyarlar; aksi takdirde kısa sesli güncellemeler duyarlar.
- Fısıltı en fazla **1000 karakter** olabilir.
- `telephony.turn` teslimi en az bir kez yapılır ve sırasız olabilir.

## Güvenlik kontrol listesi

- API anahtarını sunucunuzda tutun.
- Webhook'larda ve araç isteklerinde ThunderPhone imzalarını, Slack isteklerinde ise Slack imzalama gizli anahtarını doğrulayın. İki ThunderPhone imzası farklı gizli anahtarlar kullanır: webhook teslimleri webhook uç noktasının kendi gizli anahtarını, araç istekleri ise kuruluşunuzun [`GET /v1/webhook`](/api-reference/organizations#legacy-single-url-webhook) içindeki webhook gizli anahtarını kullanır.
- Aramaları kimlerin başlatabileceğine karar verin: arama başlatmadan önce Slack kullanıcı kimliğini kontrol edin.
- Giden aramalar diğer tüm aramalarla aynı kurallara tabidir. Bkz. [Giden arama yasaları](/tr/guides/outbound-calling-laws).

## Bir kodlama ajanıyla oluşturun

Kodlama ajanınızı [dokümanlar MCP sunucusuna](/tr/guides/docs-mcp) ve bu sayfaya yönlendirin; ardından "bu kılavuzu izleyen ThunderPhone ajanım için bir Slack botu" isteyin. ThunderPhone uygulamasındaki yapay zeka ajanı Zeus, ajanın tarafını (webhook uç noktası, araç ve istem satırları) ayarlayabilir ve sohbette bot için başlangıç kodu yazabilir.
