Webhook ile SMS ve Sesli Arama Kodlarını Alın: API Rehberi

Webhook, numaranıza gelen her SMS'i ve aramayı geldikçe sunucunuza gönderir. Kasım 2026'dan beri kısa bir arama, metni ve içinde okunan kodla birlikte gelir.

Webhook, numaranıza gelen her SMS'i ve aramayı geldikçe sunucunuza gönderir. Kasım 2026'dan beri kısa bir arama, metni ve içinde okunan kodla birlikte gelir. Böylece sesli kod da kodunuza metin olarak ulaşır.

Bu rehber alıcıyı kurar, her isteğin gerçekten bizden geldiğini doğrular ve iki kod türünü de işler. Rehber, bir API anahtarınız ve bir numaranız olduğunu varsayar. Yoksa önce API ile SMS doğrulamasını otomatikleştirme rehberine bakın.

Bazı kodlar neden arama olarak gelir

Birçok servis, SMS ulaşmadığında “beni arayın” seçeneği sunar. Bazıları yalnızca sesli kod gönderir. Bir robot rakamları sesli okur. SMS Activate App'ten aldığınız özel bir numarada bu arama, tıpkı bir SMS gibi numaranıza ulaşır.

Bir dakikaya kadar süren her kayıtlı arama, geldiğinde metne çevrilir. Şunları alırsınız:

  • transcript: aramada söylenenler veya null.
  • code: aramada okunan doğrulama kodu (4 ila 8 haneli) veya null.
  • transcriptStatus: done, empty (konuşma yok), failed, toolong (bir dakikadan uzun), overbudget veya off.

Kayıt bağlantısı 24 saat çalışır. Metin saklanır.

Adım 1: Numarayı sunucunuza yönlendirin

Tek bir numara için webhook'u ayarlayın:

Adres HTTPS olmalı ve kaydedilmeden önce kontrolümüze 2xx durum koduyla yanıt vermelidir. Tüm numaralarınızın olaylarını tek seferde almak istiyorsanız bunun yerine hesapta PATCH /v1/me ile webhookUrl ayarlayın.

Adım 2: İmza anahtarını alın

Yanıt {"secret": "whsec_..."} biçimindedir ve yalnızca bir kez gösterilir. Bu anahtarı API anahtarınızla birlikte saklayın. Her çağrı yeni bir anahtar üretir ve eskisi bir sonraki teslimatta geçersiz olur. Bu yüzden anahtarı yalnızca sunucunuzu aynı anda güncelleyebildiğinizde yenileyin.

Adım 3: Her isteği doğrulayın

Her istek üç başlık taşır:

  • x-vpn-event: sms.received, call.received, recording.ready ve diğerleri.
  • x-vpn-timestamp: isteğin imzalandığı zaman, Unix saniyesi cinsinden.
  • x-vpn-signature: v1= ve onaltılık (hex) biçimde bir HMAC-SHA256.

İmza, gizli anahtarınızla v1.<timestamp>.<raw body> üzerinden hesaplanan HMAC-SHA256'dır. Bunu herhangi bir JSON ayrıştırmasından önce ham baytlar üzerinden hesaplayın ve sunucu saatinizden beş dakikadan fazla sapan bir zaman damgasını reddedin.

Node.js ve Express ile:

2xx ile kısa sürede yanıt verin, uzun süren işleri sonraya bırakın.

Adım 4: Kodu her iki olay türünden alın

Bir SMS (sms.received):

Bir aramanın kaydı (recording.ready, arama bittikten birkaç saniye sonra):

Tek bir işleyici ikisini de karşılar:

Transkripti kendiniz ayrıştırmak yerine code alanını tercih edin: robot rakamları çoğu zaman tekrar eder veya tek tek okur, code ise bunları zaten tek bir dize olarak içerir.

Adım 5: Gerçek trafikten önce test edin

  • POST /v1/me/webhook-test, alıcınıza bir webhook.test olayı gönderir.
  • GET /v1/me/webhook-deliveries, son teslimatları listeler: olay, teslim edilip edilmediği, sunucunuzun döndürdüğü durum kodu ve deneme sayısı.

Bir teslimat başarısız olursa önce buraya bakın. En sık nedenler yanlış gizli anahtar, doğrulamadan önce ayrıştırılan gövde ve geç gelen yanıttır.

Webhook yok mu? Aramaları API ile okuyun

Sunucunuz yoksa bir numaranın aramalarını ihtiyaç duyduğunuzda okuyun:

Her arama aynı transcript, code ve transcriptStatus alanlarını taşır. Web sitesindeki hesabınızda kod, aramanın altında görünür ve tek dokunuşla kopyalanır.

Aramaların ve SMS'lerin maliyeti

Bir numaraya gelen aramalar (dakika başına) ve SMS'ler, ülkeye göre belirlenen bir fiyattan bakiyenizden düşülür. Bu fiyat ülkelerde, arama sonuçlarında ve numaralarınızda usagePricing (callCents, smsCents, advanceUsd) olarak döner. Bakiyeniz sıfır olduğunda numara küçük bir avans tutarına kadar çalışmaya devam eder. Bu tutar aşılınca bakiye yükleyene kadar gelen aramalar reddedilir, SMS'ler ise gelmeye devam eder. Ayrıntılar için fiyatlandırma sayfasına bakın.

Sonraki adımlar