Open in
Jalankan panggilan dari Slack atau aplikasi chat
Bangun bot Slack, Teams, atau web-chat Anda sendiri yang memulai panggilan, mengikutinya secara langsung, mengarahkan agen, dan menjawab pertanyaannya, menggunakan API publik.
Anda dapat mengendalikan agen dari aplikasi chat yang sudah digunakan tim Anda. Sebuah pesan memulai panggilan. Panggilan berlangsung secara langsung dalam utas. Balasan di utas mengarahkan agen. Saat agen memerlukan keputusan, agen akan menanyakannya kepada Anda di sana dan menunggu jawaban Anda.
ThunderPhone tidak menghosting bot ini untuk Anda. Anda (atau agen pemrograman Anda) membangun server kecil yang menghubungkan aplikasi chat Anda ke API publik. Halaman ini menunjukkan komponennya. Komponen tersebut sama untuk Slack, Microsoft Teams, Discord, atau halaman chat web pribadi; contohnya menggunakan Slack.
Cara kerjanya
| Yang Anda lakukan di chat | Yang dipanggil bot Anda | Yang terjadi |
|---|---|---|
| Kirim "Hubungi Comcast dan dapatkan perkiraan waktu pemulihan gangguan" | POST /v1/call dengan pesan sebagai context | Agen melakukan panggilan. Bot Anda membuka utas untuk panggilan |
| Pantau utas | Menerima webhook telephony.turn | Setiap baris yang diucapkan agen atau orang lain muncul di utas |
| Balas di utas saat panggilan berlangsung | POST /v1/calls/{call_id}/whisper | Agen menerima catatan Anda secara pribadi dan menindaklanjutinya. Orang lain tidak pernah mendengarnya |
| Jawab pertanyaan agen | Endpoint tool Anda mengembalikan jawaban Anda, atau mengirimkannya nanti dengan POST /v1/calls/{call_id}/tool-results | Agen melanjutkan panggilan dengan jawaban tersebut; dalam mode tunggu, orang lain mendengar musik tunggu sementara itu |
| Baca hasilnya | Menerima telephony.complete | Bot Anda memposting ringkasan dan hasilnya |
Bot Anda menyimpan satu pemetaan: utas chat mana yang terkait dengan call_id mana.
Sebelum memulai
- Kunci API, disimpan di server Anda dan tidak pernah di browser atau chat. Buat satu di Integrations → API keys (lihat Buat kunci API server).
- Nomor yang diaktifkan untuk panggilan keluar dan agen untuk panggilan. Pesan
menjadi
contextper panggilan, sehingga satu agen umum menangani setiap tugas. - Server yang dapat menerima webhook, seperti Railway, Fly.io, Render, atau host Anda sendiri.
- Endpoint webhook yang mengarah ke server tersebut dan berlangganan
telephony.turnsertatelephony.complete. Peristiwa giliran hanya dikirim ke endpoint yang mencantumkannya. Lihat Webhook. Peristiwa giliran memerlukan perekaman panggilan agen diaktifkan, dansummaryakhir panggilan memerlukan pengaturan agen Buat ringkasan panggilan; tanpa keduanya, kolom tersebut tetap kosong. - Aplikasi chat Anda sendiri. Untuk Slack, buat aplikasi di workspace Anda di api.slack.com/apps.
1. Mulai panggilan dari pesan
Saat bot Anda menerima pesan (pesan langsung atau @mention),
segera konfirmasikan permintaan Slack (Slack mencoba ulang apa pun yang tidak
dikonfirmasi dalam 3 detik) dan lakukan sisanya di latar belakang. Periksa
bahwa pengirim diizinkan untuk melakukan panggilan, lalu mulai panggilan dengan
pesan tersebut sebagai context:
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"
}'Simpan call_id yang dikembalikan pada thread Slack (channel ditambah
ts pesan) dan balas di thread tersebut ("Memanggil…"). Buat
idempotency_key dari channel dan ts pesan (sebuah ts hanya unik
dalam channel-nya), agar event Slack yang dicoba ulang tidak melakukan
panggilan kedua. Jika permintaan menyebutkan seseorang, bukan nomor, bot Anda
mencari nomornya terlebih dahulu. ThunderPhone hanya menghubungi to_number
yang Anda kirim.
2. Ikuti panggilan di thread
Setiap webhook telephony.turn membawa call_id, pembicara (role:
assistant untuk agen, user untuk orang lain), text, dan
position giliran. Cari thread berdasarkan call_id dan
posting barisnya.
- Verifikasi setiap webhook sebelum menindaklanjutinya. Lihat Verifikasi tanda tangan webhook.
- Hilangkan duplikasi berdasarkan
event_idenvelope dan urutkan berdasarkanposition. Pengiriman terjadi setidaknya satu kali, dan giliran dapat tiba tidak berurutan. - Kelompokkan baris jika panggilan yang sibuk akan membanjiri thread; posting setiap beberapa detik lebih mudah dibaca daripada satu pesan per baris.
Saat telephony.complete tiba, posting bagaimana panggilan berakhir (status
dan end_reason), summary, serta data yang diekstrak, lalu tutup
thread. Lihat Panggilan selesai untuk kolomnya.
3. Arahkan panggilan dari thread
Saat seseorang membalas di thread panggilan langsung, kirim balasan tersebut sebagai bisikan, kecuali agen sedang menunggu jawaban atas pertanyaan (langkah 4), dalam hal itu balasan tersebut adalah jawabannya:
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."}'Agen mendengarnya secara pribadi dan memasukkannya ke giliran berikutnya; orang lain
tidak pernah mendengar bisikan itu sendiri. Bisikan terdiri dari 1 hingga 1000 karakter. Kode
409 berarti panggilan tidak lagi berlangsung: beri tahu thread bahwa panggilan telah berakhir.
4. Biarkan agen bertanya kepada Anda
Berikan agen sebuah tool, misalnya ask_owner dengan satu parameter
question, yang memanggil server Anda. Buat sebagai
koneksi API dan tautkan ke agen.
Setiap permintaan tool membawa panggilan dalam header X-ThunderPhone-Call-ID.
Ada tiga cara untuk mendapatkan jawabannya kembali.
Tahan panggilan (hingga 10 menit). Atur alat ke mode tahan: spec.wait_mode
"hold" dan spec.timeout hingga 600 detik (tanpa batas waktu, penahanan
berlangsung selama 20 detik), melalui
API, atau minta Zeus untuk
mengaturnya (editor aplikasi belum memiliki kedua kolom tersebut). Endpoint Anda memposting pertanyaan ke thread panggilan dan langsung merespons dengan hasil tertunda:
{"status": "pending", "request_id": "q-C012AB3CD-1731000042.000300"}Lawan bicara mendengar satu kalimat dari agen, lalu musik tunggu. Pada
menu telepon atau pesan suara, agen menggunakan pembaruan lisan sebagai gantinya, dan
agen full-duplex tidak menahan panggilan: agen menerima balasan tertunda sebagai hasil. Saat
balasan tiba di thread, kirimkan dengan
POST /v1/calls/{call_id}/tool-results:
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."}}'Musik perlahan berhenti dan agen melanjutkan dengan jawaban Anda. Jika tidak ada yang
menjawab sebelum timeout, agen diberi tahu bahwa tidak ada jawaban dan menawarkan
langkah selanjutnya kepada lawan bicara. Selama pertanyaan tertunda untuk suatu panggilan,
balasan berikutnya di thread-nya menjawab pertanyaan tersebut: kirimkan sebagai hasil tool dan
jangan juga mengirimkannya sebagai bisikan (bisikan hanya mencapai agen setelah
tool selesai). Lihat
Menunggu lama.
Tunggu dalam permintaan (hingga 3 menit). Endpoint Anda memposting pertanyaan,
menunggu balasan, lalu mengembalikannya, seperti {"answer": "Yes, book Tuesday at 10."}.
Atur spec.timeout tool melalui API, hingga 180 detik (default-nya
20). Berikan endpoint Anda tenggatnya sendiri beberapa detik lebih singkat
(misalnya 170 detik), sehingga saat tidak ada yang menjawab, endpoint tetap mengembalikan
sesuatu yang dapat ditindaklanjuti agen, seperti
{"answer": null, "note": "No reply yet. Offer to take a message."}. Tool
yang mencapai timeout akan sampai ke agen sebagai error, dan host Anda harus
tetap membuka permintaan selama itu. Selama menunggu, agen memberi tahu lawan bicara
bahwa agen sedang memeriksa, mengatakan bahwa agen masih bekerja setelah sekitar 12 detik, lalu
memberikan pembaruan singkat sekitar setiap 15 detik. Mode tahan juga berfungsi
di sini: atur spec.wait_mode ke "hold" dan lawan bicara mendengar musik
alih-alih pembaruan.
Jawab dengan bisikan. Endpoint Anda memposting pertanyaan dan segera mengembalikan,
misalnya {"status": "asked", "note": "Matthew has been asked; his answer will come as guidance."}.
Saat balasan tiba, kirimkan sebagai bisikan (langkah 3), dan agen
segera meresponsnya. Gunakan ini untuk jawaban yang mungkin memerlukan waktu lebih dari
10 menit. Panggilan tidak ditahan: Prompt Anda harus memberi tahu
agen apa yang harus dilakukan sementara itu, misalnya menemani lawan bicara atau menawarkan
untuk menelepon kembali.
Dalam setiap kasus, jelaskan dalam Prompt agen kapan harus menggunakan tool dan apa yang harus dikatakan kepada lawan bicara selama menunggu:
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.Batas yang perlu direncanakan
- Titik akhir Anda harus merespons dalam
timeoutalat, maksimal 180 detik. Alat dalam mode tahan dapat menahan panggilan hingga 600 detik dengan hasil yang tertunda. - Saat alat menunggu, agen tidak menjawab lawan bicara. Dalam mode tahan, mereka mendengar musik; jika tidak, pembaruan lisan singkat.
- Bisikan maksimal 1000 karakter.
- Pengiriman
telephony.turnsetidaknya sekali dan mungkin tidak berurutan.
Daftar periksa keamanan
- Simpan kunci API di server Anda.
- Verifikasi tanda tangan ThunderPhone pada webhook dan permintaan alat, serta
rahasia penandatanganan Slack pada permintaan Slack. Kedua tanda tangan
ThunderPhone menggunakan rahasia yang berbeda: pengiriman webhook menggunakan rahasia
milik titik akhir webhook itu sendiri, dan permintaan alat menggunakan rahasia webhook
organisasi Anda dari
GET /v1/webhook. - Tentukan siapa yang dapat memulai panggilan: periksa ID pengguna Slack sebelum melakukan panggilan.
- Panggilan keluar mengikuti aturan yang sama seperti panggilan lainnya. Lihat Hukum panggilan keluar.
Bangun dengan agen pemrograman
Arahkan agen pemrograman Anda ke server MCP dokumentasi dan ke halaman ini, lalu minta "bot Slack untuk agen ThunderPhone saya yang mengikuti panduan ini". Zeus, asisten di aplikasi ThunderPhone, dapat menyiapkan sisi agen (titik akhir webhook, alat, dan baris Prompt) serta menulis kode awal untuk bot di chat.