UPPU API belgesi

UPPU API'sine başlangıç

UPPU API v1 ile kendi sistemleriniz WhatsApp, Messenger, Instagram, Telegram ve web sohbeti mesajlarını UPPU üzerinden gönderir ve alır. Kodunuz yalnızca UPPU ile konuşur: mesajlaşma ağlarıyla UPPU konuşur, yanıt penceresini ve izin kurallarını UPPU uygular, her olayı size imzalı bir webhook olarak gönderir.

Bu rehber ilk anahtardan canlıya geçişe kadar yol gösterir. API başvurusu her ucu ve alanı, webhook sayfası her olayı listeler; kod örnekleri sık yapılan işleri PHP, Node.js, Python ve C# ile gösterir.

Ortamlar

Canlı Sahne
Taban adres https://messaging.uppu.net/v1 https://messaging-staging.uppu.net/v1
Anahtar öneki uppu_live_ uppu_test_
Simüle WhatsApp kanalı yok var

Başlamadan önce

  1. Firmanızın paketinde API vardır. Paketi UPPU belirler. Paketinde API olmayan firmada her istek 403 api_disabled alır, details.reason not_in_plan olur; olay da gönderilmez. UPPU'daki muhatabınıza yazın.
  2. Bir kanal bağlıdır (WhatsApp, Messenger, Instagram, Telegram ya da web sohbeti). Kendi sisteminizin yanıtladığı kanalda firma sahibi kanallar sayfasında kanalın Yönetim ayarını Harici sistem (API) yapar: ekibin gelen kutusu bu kanalın konuşmalarını kendiliğinden atamaz, temsilciler yine okuyup yanıt verebilir.
  3. Firma sahibi bir anahtar oluşturur: UPPU panelinde firmanın ayarları, ardından Geliştiriciler. Anahtarları ve webhook'ları yalnızca firma sahibi, parolasını onaylayarak yönetir.

API anahtarları

Kapsamlar

Anahtar kapsamlar taşır (panelde "Yetkiler"). Panel üç hazır seçim sunar; "özel" kapsamları tek tek seçtirir. Eksik kapsam 403 insufficient_scope alır, details.required gereken kapsamı söyler.

Kapsamİzin verdiğiUç noktalarBotBildirim göndericiSalt okuma
Her anahtarAnahtarın kanallarını okurGET /v1/channels
GET /v1/channels/{id}		evetevetevet
messages:sendMesaj, okundu bildirimi ve yazıyor göstergesi göndermePOST /v1/conversations/{id}/typing
POST /v1/messages
POST /v1/messages/{id}/read		evetevet—
messages:readMesajları ve konuşmaları okumaGET /v1/conversations
GET /v1/conversations/{id}
GET /v1/messages
GET /v1/messages/{id}		evetevetevet
conversations:writeKonuşmaları çözme ve devretmePOST /v1/conversations/{id}/handover
POST /v1/conversations/{id}/release
POST /v1/conversations/{id}/resolve		evet——
media:writeMedya yüklemePOST /v1/mediaevetevet—
media:readMedya indirmeGET /v1/media/{id}
GET /v1/media/{id}/content
POST /v1/media/{id}/link		evet—evet
templates:readŞablonları okumaGET /v1/templates
GET /v1/templates/{id}		evetevetevet
contacts:readKişileri arama ve okumaGET /v1/contacts/{id}
GET /v1/contacts/{id}/consents
POST /v1/contacts/lookup		evetevetevet
consents:writeİzin kaydetmePOST /v1/consents—evet—
events:readOlayları okumaGET /v1/events—evetevet
webhooks:manageWebhook uç noktalarını yönetDELETE /v1/webhook-endpoints/{id}
GET /v1/webhook-endpoints
GET /v1/webhook-endpoints/{id}
PATCH /v1/webhook-endpoints/{id}
POST /v1/webhook-endpoints
POST /v1/webhook-endpoints/{id}/activate
POST /v1/webhook-endpoints/{id}/disable
POST /v1/webhook-endpoints/{id}/probe
POST /v1/webhook-endpoints/{id}/secret
POST /v1/webhook-endpoints/{id}/test		———
reports:readRaporları okumaGET /v1/reports/daily
GET /v1/reports/summary		———
templates:writeWhatsApp şablonlarını oluşturma ve silmeDELETE /v1/templates/{id}
POST /v1/templates		———

Simülatörün uçları (/v1/sandbox/...) yalnızca sahnede vardır ve messages:send ister; /v1/sandbox/action-target ise anahtar istemez (aşağıda, sahne simülatörü).

Sahne simülatörü

Sahnede firma sahibi Geliştiriciler sayfasından en çok üç simüle WhatsApp kanalı ekleyebilir. Simüle kanal API'de ve webhook'larda gerçek bir WhatsApp kanalı gibi davranır (yanıt penceresi, izin kuralları, tekrar anahtarı, durumlar, medya, olaylar), ama Meta'ya hiçbir şey gitmez: durumlar birkaç saniye arayla message.status olayı olarak gelir. Simüle kanala bağlı, Bot hazır seçimli bir test anahtarı oluşturun.

Sihirli alıcılar. Kişinin telefon numarasının son iki hanesi, gönderdiğiniz mesajın sonucunu seçer:

Son iki hane Sonuç
diğerleri accepted, sent, delivered, read
01 accepted, sent, delivered (okunmaz)
02 accepted, sent (teslim bildirimi gelmez)
03 accepted, sonra failed, recipient_unreachable
04 accepted, sonra failed, window_closed
05 accepted, sonra failed, marketing_opt_out (UPPU geri çekmeyi kaydeder)
06 accepted, sonra failed, payment_required
07 hemen reddedilir: failed, invalid_parameter
08 hız sınırı: UPPU 10, 60 ve 300 saniye sonra yeniden dener, sonra failed, provider_rate_limited
09 yanıt yok: unknown, sonra delivered

Denemelerde kurgu için ayrılmış numaralar kullanın, örneğin +447700900100. ttl açıldıktan sonra 08'e kısa bir ttl ile (örneğin 30 saniye) gönderilen mesaj daha erken biter: ttl dolunca UPPU yeniden denemeyi bırakır ve mesaj expired değil, provider_rate_limited ile failed olur, çünkü ağ hatayla yanıt vermiştir.

Şablon seti (hepsi tr dilinde): uppu_sim_order_update (UTILITY, iki sıralı gövde parametresi), uppu_sim_appointment (UTILITY, adlı customer_name ve appointment_time, iki hızlı yanıt düğmesi), uppu_sim_payment (UTILITY, değişkenli metin başlık), uppu_sim_campaign (MARKETING: kayıtlı izin ister), uppu_sim_login_code (AUTHENTICATION: her zaman reddedilir) ve uppu_sim_pending (onaylanmamış).

Simülatörün uçları (test anahtarı, messages:send):

Simüle trafik firmanın kullanımında sayılmaz. UPPU simüle kanalların verisini istek üzerine siler; gerçek kanallara hiç dokunulmaz.

/v1/sandbox/action-target sizin çağırdığınız API'nin parçası değildir: sahnede UPPU Bot'un eylemleri firmanın kendi API'si yerine onu çağırır. Anahtar istemez, istemci adresi başına sınırlıdır; başvuru onu anlatır.

Canlıda /v1/sandbox yolları yoktur.

İlk mesajınız

Adımlar sahnede ve curl ile. Önce anahtarı ortama koyun:

export UPPU_API_BASE=https://messaging-staging.uppu.net/v1
export UPPU_API_KEY=uppu_test_...

1. Kanalınızı bulun. Simüle kanalın id'sini not edin.

curl -s "$UPPU_API_BASE/channels" -H "Authorization: Bearer $UPPU_API_KEY"

2. Bir kişi size yazsın. WhatsApp serbest mesaja yalnızca kişinin son mesajından sonraki 24 saat içinde izin verir; bu yüzden bir mesaj simüle edin. Yanıt bir sandbox_event'tir; contact_id o kişidir.

curl -s -X POST "$UPPU_API_BASE/sandbox/inbound" \
  -H "Authorization: Bearer $UPPU_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"channel_id": "<kanal kimliği>", "from": {"phone": "+447700900100", "name": "Deniz"}, "content": {"type": "text", "text": {"body": "Merhaba"}}}'

3. Yanıt verin. Her gönderim bir Idempotency-Key taşır: bu gönderimin her yeniden denemesinde aynı anahtar kullanılır, böylece yeniden deneme hiçbir zaman ikinci mesaj göndermez.

curl -s -X POST "$UPPU_API_BASE/messages" \
  -H "Authorization: Bearer $UPPU_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: ticket-42-reply-1" \
  -d '{"channel_id": "<kanal kimliği>", "to": {"contact_id": "<kişi kimliği>"}, "content": {"type": "text", "text": {"body": "Teşekkürler, ilgileniyoruz."}}, "client_reference": "ticket-42"}'

Yanıt 202 ve mesajdır, status queued.

4. Durumu izleyin. GET /v1/messages/{id} mesajın accepted, sent, delivered ve read olarak ilerlediğini gösterir; webhook uç noktanız varsa aynı adımlar message.status olayı olarak gelir.

curl -s "$UPPU_API_BASE/messages/<mesaj kimliği>" -H "Authorization: Bearer $UPPU_API_KEY"

5. Şablon gönderin. Onaylı şablon 24 saatlik pencerenin dışında da gider:

{
  "channel_id": "<kanal kimliği>",
  "to": {"contact_id": "<kişi kimliği>"},
  "content": {
    "type": "template",
    "template": {"name": "uppu_sim_order_update", "language": "tr", "body": {"parameters": ["Deniz", "A-1001"]}}
  },
  "client_reference": "order-A-1001"
}

Mesaj gönderme

POST /v1/messages her türden mesajı gönderir; bir kanalın neyi kabul ettiğini GET /v1/channels söyler (capabilities.content_types, capabilities.limits).

Yanıt penceresi ve şablonlar

Tekrar anahtarı

Hız sınırları

SınırDeğer
Anahtar başına, bütün uçlarherhangi bir saniyede 100 istek ve dakikada 3.000
Anahtar başına, gönderim ve okundu bildirimi (POST /v1/messages, POST /v1/messages/{id}/read)saniyede 20 istek
Anahtar başına, dosya yükleme (POST /v1/media)saniyede 2 istek ve günde 1 GB
Anahtar başına, dosya indirme (GET /v1/media/{id}/content)saniyede 10 istek ve saatte 2 GB
Anahtar başına, kaçırılan olaylar (GET /v1/events)saniyede 2 istek
Yazıyor göstergesi (POST /v1/conversations/{id}/typing)anahtar başına saniyede 20 istek ve konuşma başına 3 saniyede bir
Firma başına, webhook uç noktasının test olayı ve yanlış imzalı denemesi (POST /v1/webhook-endpoints/{id}/test ve /probe)dakikada 10 istek, aynı anda bir
İmzalı medya bağlantıları (POST /v1/media/{id}/link)Bağlantı 300 saniye ve 30 istek boyunca çalışır; her indirme onu veren anahtarın saatlik medya baytından düşer
Anahtar başına, raporlar (GET /v1/reports/summary ve /daily)saniyede 2 istek
Firma başına, şablon oluşturma ve silme (POST /v1/templates, DELETE /v1/templates/{id})dakikada 10 istek, aynı anda bir; Meta bir WhatsApp hesabına saatte 100 yeni şablon izin verir
Bir ağdan gelen geçersiz anahtarlardakikada 30; sonra her istek 10 dakika boyunca 429 alır
Kanal başına bekleyen gönderimler10.000 bekleyen gönderimden itibaren ya da en eskisi 15 dakika beklemişse yeni gönderim 429 channel_backlog alır

Hatalar

Her hatanın zarfı aynıdır:

{
  "error": {
    "type": "policy",
    "code": "window_closed",
    "status": 422,
    "retryable": false,
    "message": "Kişi son 24 saatte yazmadı; yalnızca onaylı bir şablon gönderilebilir.",
    "request_id": "01jace0e1v2m4n6p8q0r2s4t6a",
    "doc_url": "https://messaging.uppu.net/docs/errors#window_closed",
    "details": {"window_closed_at": "2026-10-19T08:58:00.000Z", "hint": "send_template"},
    "provider_error": null
  }
}

Webhook'lar

UPPU her olayı (gelen mesaj, durum, değişen kimlik) HTTPS uç noktanıza imzalı bir POST olarak gönderir. İmzayı ham gövde üzerinden doğrulayın, 10 saniye içinde 2xx dönün, tekrarları webhook-id ile ayıklayın ve olayı sonra işleyin. Kaçırdığınız olaylar 7 gün boyunca GET /v1/events'te durur. Webhook sayfası kurulumu (panelde ya da API'den), imzayı, yeniden denemeleri ve her olayı örneğiyle anlatır. Bir dosyayı anahtarınız olmadan vermek için POST /v1/media/{id}/link birkaç dakika çalışan imzalı bir indirme bağlantısı döner; indirmeleri anahtarınızın saatlik medya baytından düşer.

Ekibinize devir

Kendi sisteminizin (yönetim kipi api) ya da UPPU Bot'un (bot) yanıtladığı kanalda her konuşmayı otomasyon tutar (held_by api ya da bot), ta ki ekibinize devredilene kadar (held_by team). İki çağrı da conversations:write ister («Bot» hazır seçiminde var).

API'den şablonlar

Hiçbir hazır seçimde olmayan templates:write kapsamıyla («Özel» seçimle verilir) sisteminiz bir kanalın WhatsApp Business hesabının WhatsApp şablonlarını panelin şablon sayfasının kurallarıyla oluşturur ve siler.

{
  "channel_id": "01j9z0ch5k2m4n6p8q0r2s4t6v",
  "name": "order_update",
  "language": "tr",
  "category": "UTILITY",
  "header": {"type": "text", "text": "Sipariş {{1}}", "example": "A-1001"},
  "body": {"text": "Merhaba {{1}}, siparişiniz yola çıktı.", "examples": ["Ayşe"]},
  "footer": {"text": "Bilgilendirme"},
  "buttons": [{"type": "quick_reply", "text": "Teşekkürler"}]
}

Raporlar

Yine hiçbir hazır seçimde olmayan reports:read kapsamıyla GET /v1/reports/summary panelin «Raporlar» sayfasının sayılarını, GET /v1/reports/daily aynı sayıları gün gün verir. Sayılar her gece toplanır: yalnızca sayılar; kişi, konuşma ya da mesaj yok.

Uyumluluk

v1 içinde UPPU yalnızca ekler; hiçbir şeyi kaldırmaz ya da yeniden adlandırmaz:

Kişisel veri

Canlıya geçiş