API tanıtımı

Flowella REST API, programlı olarak WhatsApp mesajları göndermenizi, kişileri ve devre dışı bırakmaları yönetmenizi, şablonları listelemenizi ve toplu olarak göndermenizi ve analizleri çekmenizi sağlar. Bu sayfa, bir uç noktayı çağırmadan önce bilmeniz gereken her şeyi kapsar. Tam uç nokta referansı API referansı kenar çubuğunda bulunur (OpenAPI spec’dan otomatik olarak oluşturulur).

Temel URL

https://api.flowella.io/v1

Tüm v1 uç noktaları bu kanonik tabanın altında yer alır — örneğin https://api.flowella.io/v1/messages.

API daha önce uygulama ana bilgisayarında https://app.flowella.io/api/v1/... adresinde bulunuyordu. Bu eski yola yapılan istekler, yöntem ve gövdeyi koruyarak https://api.flowella.io/v1/... adresine kalıcı olarak (308) yönlendirilir — böylece mevcut entegrasyonlar çalışmaya devam eder. Ek sıçramayı atlamak için fırsat bulduğunuzda taban URL’nizi güncelleyin.

Kimlik Doğrulama

Her istek, Authorization başlığında bir API anahtarına ihtiyaç duyar:

Authorization: Bearer flo_xxxxxxxxxxxxxxxxxxxxxxxx

Anahtarlar kuruluş kapsamlıdır - tek bir Flowella kuruluşu üzerinde hareket ederler ve bu kuruluştaki bir Yöneticinin izinlerini devralırlar.

Anahtarlara parola gibi davranın. Onları asla kaynak kontrolüne işlemeyin, asla sohbete veya paylaşılan belgelere yapıştırmayın ve takım arkadaşları kuruluştan ayrıldığında onları döndürün. Döndürme adımları için Ayarlar → API anahtarları bölümüne bakın.

Anahtar oluşturma

API anahtarlarını yönetmek için Owner veya Admin rolüne ihtiyacınız vardır.

Flowella uygulamasında Ayarlar → API anahtarları bölümüne gidin.
Anahtar oluştur** seçeneğine tıklayın ve ona akılda kalıcı bir isim verin.
Anahtarı bir kez kopyalayın - yalnızca oluşturma sırasında gösterilir.

Anahtarlara parola gibi davranın: asla kaynak kontrolüne işlemeyin, asla sohbete yapıştırmayın ve ekip arkadaşları kuruluştan ayrıldığında anahtarları rotasyona tabi tutun.

Bir anahtarın doğrulanması

Bir anahtarın geçerli olduğunu doğrulamak için ping uç noktasına basın:

curl https://api.flowella.io/v1/ping \
  -H "Authorization: Bearer flo_xxxxxxxxxxxxxxxxxxxxxxxx"

await fetch("https://api.flowella.io/v1/ping", {
  headers: { Authorization: `Bearer ${process.env.FLOWELLA_API_KEY}` },
});

import os, requests

requests.get(
    "https://api.flowella.io/v1/ping",
    headers={"Authorization": f"Bearer {os.environ['FLOWELLA_API_KEY']}"},
)

200 OK ile { "ok": true, "organizationId": "…" } kimliğinizin doğrulandığı anlamına gelir.

Hatalar

Tüm hatalar tutarlı bir zarf içinde geri gelir:

{
  "error": {
    "code": "UNAUTHORIZED",
    "message": "Invalid API key"
  }
}

HTTP durumu	Ne zaman göreceksiniz
`400`	Doğrulama başarısız oldu, hatalı biçimlendirilmiş gövde veya yukarı akış Meta reddi
`401`	Eksik veya geçersiz API anahtarı
`402`	Ödeme gerekli - aboneliğiniz eylemi kapsamıyor
`403`	Yasak - örneğin, devre dışı bırakılmış bir kişiye gönderiliyor veya Meta bağlı değil
`404`	İstenen kanal veya kaynak mevcut değil
`429`	Hız sınırlı - yavaşla

error.code alanı sabittir ve programlı olarak açılması güvenlidir. error.message insan tarafından okunabilir ve değişebilir.

Oran sınırları

API anahtarları kuruluş başına oranla sınırlıdır. Sınırı aşarsanız RATE_LIMITED kodlu bir 429 ve Too many requests mesajı alırsınız. Mevcut olduğunda, Retry-After yanıt başlığı kaç saniye beklemeniz gerektiğini söyler. Geri çekilin ve üstel gecikmeyle yeniden deneyin. Büyük toplu gönderimler yapıyorsanız, throttlePerHour parametresiyle birlikte POST /v1/templates/send seçeneğini tercih edin - Flowella sunucu tarafında gaz kelebeği uygular, böylece istekleri kendiniz hızlandırmanız gerekmez.

Idempotency anahtarları

Toplu şablon gönderimleri eşzamansızdır. POST /v1/templates/send isteği doğrular, kalıcı olarak kuyruğa alır ve hemen 202 Accepted döndürür:

{
  "id": "v1ts-0123456789abcdef",
  "status": "accepted"
}

Flowella toplu gönderimi arka planda teslim eder ve geçici WhatsApp hatalarını otomatik olarak yeniden dener. Alıcılar tek tek işlenir, bu nedenle geçersiz bir numara toplu gönderimin geri kalanını engellemez. Teslimat ilerlemesini uygulamada şablonun İstatistikler sekmesinden takip edin. Teslimat yanıttan sonra gerçekleştiği için, yeniden denemelerin güvenli olması gerekir. Her toplu gönderimi benzersiz şekilde tanımlayan bir Idempotency-Key başlığı (en fazla 200 karakter) iletin:

curl -X POST "https://api.flowella.io/v1/templates/send" \
  -H "Authorization: Bearer flo_xxxxxxxxxxxxxxxxxxxxxxxx" \
  -H "Idempotency-Key: campaign-2026-08-31-launch" \
  -H "Content-Type: application/json" \
  -d '{
    "templateId": "clxxxxxxxxxxxxxxxxxxxxxxxx",
    "whatsappChannelId": "clxxxxxxxxxxxxxxxxxxxxxxxx",
    "recipients": [{ "phone": "+15551234567" }]
  }'

Aynı anahtarın yedi gün içinde tekrarlanması, yeni bir gönderim oluşturmak yerine orijinal işin id değerini döndürür. Bir zaman aşımı veya ağ hatasından sonra kimseye iki kez mesaj göndermeden isteği güvenle yeniden deneyebilirsiniz. Başlığı atlarsanız, Flowella istek gövdesinden bir anahtar türetir. Bu nedenle kısa aralıklarla iki kez gönderilen özdeş bir toplu gönderim çift gönderilmez. Açık bir anahtar yine de daha güvenlidir, çünkü gövdedeki herhangi bir değişiklik (alıcıların yeniden sıralanması bile) yeni bir türetilmiş anahtar üretir.

Sayfalandırma

Liste uç noktaları (/conversations, /contacts, /templates) imleç sayfalama kullanır:

limit (1-100, varsayılan 25) ve isteğe bağlı bir cursor iletin.
Yanıt, items ve daha fazla sonuç olduğunda bir nextCursor içerir.
Bir sonraki sayfayı almak için nextCursor’yi cursor parametresi olarak geri iletin.
nextCursor kayıp olduğunda, sonuna ulaştınız demektir.

curl "https://api.flowella.io/v1/conversations?limit=50" \
  -H "Authorization: Bearer flo_xxxxxxxxxxxxxxxxxxxxxxxx"

Tarih ve saat

Tüm zaman damgaları UTC’de ISO 8601 dizeleridir (örneğin 2025-01-15T14:30:00.000Z). API’nin tarihleri kabul ettiği durumlarda, hem yalnızca tarih (2025-01-15) hem de tam ISO 8601 sunucu tarafında zorlanır.

Telefon numaraları

Telefon numaralarını mümkünse E.164 biçiminde (+15551234567) iletin. Flowella yaygın varyasyonları sunucu tarafında normalleştirecektir, ancak E.164 en güvenlisidir.

Kanallar

Birçok uç nokta bir whatsappChannelId kabul eder. Kuruluşunuzun tek bir kanalı varsa ve siz bunu atlarsanız, Flowella varsayılan kanalınızı kullanır. Birden fazla kanalınız varsa, yanlış göndericiden göndermekten kaçınmak için kimliği açıkça iletin. Tam URL modeli ve kanal değiştirme için, Çoklu kanal bölümüne bakın.

OpenAPI spec

Makine tarafından okunabilir spesifikasyon şu adreste bulunmaktadır:

/api-reference/openapi.json

Postman, Insomnia veya tercih ettiğiniz kod oluşturucuya bırakın.

Bir entegrasyon mu oluşturuyorsunuz? Durum için yoklama yapmak yerine olaylara tepki vermek için bu sayfayı Webhooks ile eşleştirin.

Başlarken

Değişiklik günlüğü

Temel bilgiler

Uygulamayı kullanma

Ayarlar

Meta ve WhatsApp kurulumu

HubSpot entegrasyonu

Flow'lar ve kampanyalar

Hesap ve oturum açma

Güvenlik ve gizlilik

API referansı

Sorun giderme

Temel URL

Kimlik Doğrulama

Anahtar oluşturma

Bir anahtarın doğrulanması

Hatalar

Oran sınırları

Idempotency anahtarları

Sayfalandırma

Tarih ve saat

Telefon numaraları

Kanallar

OpenAPI spec

​Temel URL

​Kimlik Doğrulama

​Anahtar oluşturma

​Bir anahtarın doğrulanması

​Hatalar

​Oran sınırları

​Idempotency anahtarları

​Sayfalandırma

​Tarih ve saat

​Telefon numaraları

​Kanallar

​OpenAPI spec

Temel URL

Kimlik Doğrulama

Anahtar oluşturma

Bir anahtarın doğrulanması

Hatalar

Oran sınırları

Idempotency anahtarları

Sayfalandırma

Tarih ve saat

Telefon numaraları

Kanallar

OpenAPI spec