ThunderPhone v3 kini tersedia.Gunakan langsung secara mandiri, mulai 2¢/menit.Baca pengumumannya

Developer cookbook

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 chatYang dipanggil bot AndaYang terjadi
Kirim "Hubungi Comcast dan dapatkan perkiraan waktu pemulihan gangguan"POST /v1/call dengan pesan sebagai contextAgen melakukan panggilan. Bot Anda membuka utas untuk panggilan
Pantau utasMenerima webhook telephony.turnSetiap baris yang diucapkan agen atau orang lain muncul di utas
Balas di utas saat panggilan berlangsungPOST /v1/calls/{call_id}/whisperAgen menerima catatan Anda secara pribadi dan menindaklanjutinya. Orang lain tidak pernah mendengarnya
Jawab pertanyaan agenEndpoint tool Anda mengembalikan jawaban Anda, atau mengirimkannya nanti dengan POST /v1/calls/{call_id}/tool-resultsAgen melanjutkan panggilan dengan jawaban tersebut; dalam mode tunggu, orang lain mendengar musik tunggu sementara itu
Baca hasilnyaMenerima telephony.completeBot 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 context per 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.turn serta telephony.complete. Peristiwa giliran hanya dikirim ke endpoint yang mencantumkannya. Lihat Webhook. Peristiwa giliran memerlukan perekaman panggilan agen diaktifkan, dan summary akhir 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_id envelope dan urutkan berdasarkan position. 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 timeout alat, 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.turn setidaknya 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.