> ## Documentation Index
> Fetch the complete documentation index at: https://knowledge.flowella.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Customer.io'dan WhatsApp şablonları ve Flow'lar gönderin

> Flowella API ile Customer.io kampanyalarından onaylı WhatsApp şablonları ve Flow'lar gönderin, isteğe bağlı olarak gelen mesajları Customer.io'ya aktarın.

Flowella, Customer.io'nun webhook eylemleri ve Flowella REST API'si aracılığıyla Customer.io'ya bağlanır. Bir Customer.io kampanyası, o adıma ulaşan her kişiye WhatsApp Flow düğmeli şablonlar da dahil olmak üzere onaylı bir WhatsApp şablonu göndermek için Flowella'yı çağırır. WhatsApp yanıtlarını Customer.io'da da görmek istiyorsanız Flowella, gelen her mesajı sizin yönettiğiniz, webhook ile tetiklenen bir Customer.io otomasyonuna gönderebilir.

> [!NOTE]
>
> Customer.io'da yüklenecek bir uygulama yoktur. Her iki yönü de standart Customer.io eylemleriyle kurarsınız, böylece hangi isteklerin çalışacağına ve hangi özniteliklerin değişeceğine tam olarak siz karar verirsiniz.

## Entegrasyon nasıl çalışır

| Yön | Ne çalışır | Neyi değiştirir |
| - | - | - |
| Customer.io'dan Flowella'ya | Kampanyanızdaki bir **Send and receive data** (webhook) eylemi, kampanyadaki kişi için `POST /v1/templates/send` çağrısı yapar. | Flowella bir WhatsApp şablon mesajını kuyruğa alır. Customer.io'ya hiçbir şey yazılmaz. |
| Flowella'dan Customer.io'ya (isteğe bağlı) | Bir Flowella giden webhook'u, `message.received` olaylarını Customer.io'daki webhook ile tetiklenen bir otomasyona gönderir. | Yalnızca kendi **Create or Update Person** eyleminizde eşlediğiniz kişi öznitelikleri. |

Flowella, Customer.io API'sini hiçbir zaman çağırmaz. İsteğe bağlı gelen yönde Flowella olayları yalnızca verdiğiniz webhook URL'sine gönderir ve bunlarla ne yapılacağına otomasyonunuz karar verir.

```mermaid theme={null}
flowchart LR
    A["Customer.io: kişi webhook eylemine ulaşır"] --> B["Flowella: POST /v1/templates/send"]
    B --> C["Meta: WhatsApp mesajı teslim edildi"]
    C --> D["Kişi WhatsApp'ta yanıt verir"]
    D --> E["Flowella: message.received webhook'u"]
    E --> F["Customer.io: webhook ile tetiklenen otomasyon"]
    F --> G["Customer.io: Create or Update Person"]
```

## Başlamadan önce

* Bağlı bir WhatsApp numarasına sahip bir Flowella kuruluşu. Bkz. [Kurulum sırası](https://knowledge.flowella.io/tr/whatsapp/accounts/setup-sequence.md).
* Flowella'da onaylı bir WhatsApp şablonu. Bkz. [Şablonlar](https://knowledge.flowella.io/tr/app/templates.md).
* API anahtarı ve gelen senkronizasyon için webhook oluşturmak üzere Flowella'da **Owner** veya **Admin** rolü. Bkz. [Ekip ve roller](https://knowledge.flowella.io/tr/settings/team.md).
* Webhook eylemli kampanya veya otomasyon oluşturabileceğiniz bir Customer.io çalışma alanı.
* Her kişinin WhatsApp numarasının Customer.io profilinde `+447700900123` gibi uluslararası biçimde kayıtlı olması. Bkz. [Telefon numarası biçimi](https://knowledge.flowella.io/tr/hubspot/phone-number-format.md).
* Her kişinin sizden WhatsApp mesajı almayı kabul etmiş olması. Meta, herhangi birine mesaj göndermeden önce izin alınmasını zorunlu tutar. Bkz. Meta'nın [izin alma kılavuzu](https://developers.facebook.com/documentation/business-messaging/whatsapp/getting-opt-in).

## Customer.io'dan WhatsApp şablonu gönderme

**1. Bir Flowella API anahtarı oluşturun**

Flowella'da **Settings** ve ardından **API keys** bölümüne gidin ve `Customer.io production` gibi bir adla canlı bir anahtar oluşturun. Anahtarı hemen kopyalayın: Flowella onu yalnızca bir kez gösterir. Bkz. [API anahtarları](https://knowledge.flowella.io/tr/settings/api-keys.md).

**2. Şablon ve kanal kimliklerini bulun**

Anahtarınızla `GET /v1/templates?status=APPROVED` çağrısı yapın. Şablonun `id` ve `wabaId` değerlerini ve göndermek istediğiniz numaranın `whatsappChannelId` değerini not edin. Birden fazla numaranız varsa bkz. [Çoklu kanal](https://knowledge.flowella.io/tr/essentials/multi-channel.md).

```bash theme={null}
curl "https://api.flowella.io/v1/templates?status=APPROVED" \
  -H "Authorization: Bearer $FLOWELLA_API_KEY"
```

**3. Kampanyanıza bir webhook eylemi ekleyin**

Customer.io kampanya iş akışınızda, WhatsApp mesajının gönderilmesi gereken noktaya bir **Send and receive data** eylemi ekleyin. Bkz. Customer.io'nun [webhook eylemleri](https://docs.customer.io/webhooks-action) kılavuzu.

**4. İsteği ayarlayın**

Yöntemi `POST`, URL'yi `https://api.flowella.io/v1/templates/send` olarak ayarlayın. Şu başlıkları ekleyin:

| Başlık | Değer |
| - | - |
| `Authorization` | `Bearer ` ve ardından Flowella API anahtarınız |
| `Content-Type` | `application/json` |

**5. İstek gövdesini yazın**

Bu gövdeyi yapıştırın ve kimlikleri kendi kimliklerinizle değiştirin. `customer.phone` değerini, kişinin WhatsApp numarasını tutan öznitelikle değiştirin.

```json theme={null}
{
  "templateId": "1234567890123456",
  "templateWabaId": "102290129340398",
  "whatsappChannelId": "clxxxxxxxxxxxxxxxxxxxxxxxx",
  "recipients": [
    {
      "phone": "{{customer.phone}}",
      "bodyParameters": ["{{customer.first_name}}"]
    }
  ]
}
```

`bodyParameters`, şablonun gövde değişkenlerini sırayla doldurur: ilk değer `{{1}}` içine, ikincisi `{{2}}` içine gider ve böyle devam eder. Şablonda gövde değişkeni yoksa boş liste, `[]`, olarak bırakın.

**6. Eylemi test edin**

Kendi WhatsApp numaranızın olduğu bir test kişisi seçin ve Customer.io'da **Test response** seçeneğini seçin. Daha önce kullanmadığınız bir değerle, örneğin `test-2026-11-11-01`, bir `Idempotency-Key` başlığı ekleyin ve her testte değiştirin. Bkz. [Tekrarlanan gönderimler ve eşgüçlülük](#repeat-sends-and-idempotency).

`"status": "accepted"` içeren bir `202` yanıtı, Flowella'nın gönderimi kuyruğa aldığı anlamına gelir. Teslimatı doğrulamaz: sonuç için Flowella'da şablonun **Statistics** sekmesini kontrol edin.

**7. Test başlığını kaldırın ve kampanyayı başlatın**

Test için kullandığınız `Idempotency-Key` başlığını silin veya her kişi için farklı olan bir değerle değiştirin. Ardından kampanyayı başlatın.

### Kişi başına ayarlayabileceğiniz şablon seçenekleri

İstek gövdesi her alıcı için şu alanları kabul eder. [API'ye giriş](https://knowledge.flowella.io/tr/api-reference/introduction.md) ve [OpenAPI belgesi](https://api.flowella.io/v1/openapi.json) isteğin tamamını açıklar.

| Alan | Kullanım amacı |
| - | - |
| `phone` | Kişinin WhatsApp numarası. Zorunludur. |
| `bodyParameters` | Gövde değişkenlerinin değerleri, sırayla. En fazla 20. |
| `buttonParameters` | URL düğmesi değişkenleri (`subType` `url`), Flow düğmeleri (`subType` `flow`) veya kod kopyalama düğmeleri (`subType` `copy_code`) için değerler. |

Görsel, video veya belge başlığı olan bir şablon için gövdenin en üst düzeyindeki `headerMedia.url` alanına herkese açık bir dosya bağlantısı ayarlayabilirsiniz.

### Tekrarlanan gönderimler ve eşgüçlülük

`POST /v1/templates/send` aynı mesajı iki kez göndermenizi önler. Bu önemlidir, çünkü Customer.io bir webhook eylemini `2xx` yanıtı almadığında yeniden dener:

* `Idempotency-Key` başlığı olmadan Flowella, anahtar olarak istek gövdesinin bir karmasını kullanır. 7 gün içinde bayt bayt aynı olan bir gövde özgün `id` değerini döndürür ve hiçbir şey göndermez. Her kişinin gövdesi kendi numarasını içerdiğinden normal bir kampanya herkese bir kez gönderir.
* `Idempotency-Key` başlığıyla, 7 gün içinde aynı anahtara sahip her istek, gövde değişmiş olsa bile özgün `id` değerini döndürür ve hiçbir şey göndermez.
* Ayrıca Flowella, aynı şablonun aynı numaraya 15 saniye içinde ikinci kez gönderilmesini atlar.

> [!WARNING]
>
> Canlı bir kampanya eyleminde asla sabit bir `Idempotency-Key` değeri bırakmayın. Mesajı yalnızca ilk kişi alır: sonraki her istek anahtarı yeniden kullanır, bu nedenle Flowella ilk `id` değerini döndürür ve hiçbir şey göndermez. Kampanyayı başlatmadan önce başlığı kaldırın veya her kişi için farklı olan bir değer oluşturun, örneğin kampanya adının ardından `{{customer.id}}`.

Başarısız testlerin çoğunu da aynı kurallar açıklar. Aynı şablonu aynı test kişisine yeniden göndermek aynı gövdeyi üretir, bu nedenle `Idempotency-Key` değerini her seferinde değiştirmezseniz Flowella hiçbir şey göndermez.

### Büyük bir segmente gönderme

Customer.io'dan gelen her istek bir gönderimi kuyruğa alır ve Flowella bunu arka planda teslim eder, geçici WhatsApp hatalarını yeniden dener. Büyük kampanyalar için iki sınır geçerlidir:

* **Meta'nın mesajlaşma sınırı.** Meta, kayan 24 saatlik dönemde 24 saatlik pencere dışında kaç kişiye mesaj gönderebileceğinizi sınırlar. Bkz. [Mesajlaşma sınırları](https://knowledge.flowella.io/tr/whatsapp/limits/messaging-limits.md).
* **API anahtarınızın hız sınırı.** Sınırı aşan istekler, `Retry-After` başlığıyla `429` döndürür. Bkz. [Hız sınırları](https://knowledge.flowella.io/tr/api-reference/introduction.md#rate-limits).

Büyük gönderimleri Customer.io'nun kendi gönderim denetimleriyle zamana yayın ve ilerlemeyi şablonun **Statistics** sekmesinden izleyin. Flowella, gönderdiğiniz numarada abonelikten çıkmış herkesi atlar. Bkz. [Abonelikten çıkmalar](https://knowledge.flowella.io/tr/app/opt-outs.md).

## Gelen WhatsApp mesajlarını Customer.io'ya senkronize etme (isteğe bağlı)

Bu bölüm, bir kişinin size gönderdiği her WhatsApp mesajını Customer.io'ya gönderir. Böylece kişiyi güncelleyebilir veya mesajdan başka kampanyalar başlatabilirsiniz.

**1. Customer.io'da webhook ile tetiklenen bir otomasyon oluşturun**

Webhook ile tetiklenen bir kampanya veya otomasyon oluşturun ve Customer.io'nun oluşturduğu webhook URL'sini kopyalayın. Bkz. Customer.io'nun [webhook kampanyaları](https://docs.customer.io/journeys/webhook-triggered-campaigns/) kılavuzu.

**2. Flowella'da giden bir webhook ekleyin**

Flowella'da **Settings** ve ardından **Webhooks** bölümüne gidin ve **Add webhook** seçeneğini seçin. Customer.io URL'sini **Endpoint URL** alanına yapıştırın, bir imzalama sırrı girin ve **Events** altında yalnızca `message.received` seçeneğini işaretleyin. Bkz. [Webhook'lar](https://knowledge.flowella.io/tr/settings/webhooks.md).

**3. Örnek veri gönderin**

Flowella'dan kendinize bir WhatsApp şablonu gönderin ve yanıtlayın. Böylece Customer.io, iş akışını oluşturmak için gerçek bir `message.received` olayı alır. Her olay şöyle görünür:

```json theme={null}
{
  "id": "evt_3f2b8c1d9a7e4f60b5c2d8e1a4f7b9c3",
  "type": "message.received",
  "created_at": "2026-10-21T09:30:00.000Z",
  "payload_version": "1",
  "data": {
    "messageId": "clxxxxxxxxxxxxxxxxxxxxxxxx",
    "conversationId": "clxxxxxxxxxxxxxxxxxxxxxxxx",
    "contactId": "clxxxxxxxxxxxxxxxxxxxxxxxx",
    "direction": "INBOUND",
    "type": "TEXT",
    "metaMessageId": "wamid.HBgLMTU1NTEyMzQ1NjcVAgASGBQzQUY"
  }
}
```

Flowella'daki **Send test event**, kişi içermeyen bir `webhook.test` olayı gönderir, bu nedenle bir sonraki adımda bunu filtreleyin.

**4. Yalnızca gerçek gelen mesajları tutun**

Yalnızca tetikleyicinin `type` değeri `message.received` olduğunda devam eden bir **True/False Branch** ekleyin.

**5. Kişiyi Flowella'da arayın**

Olay telefon numarasını değil, kimlikleri taşır. `GET` yöntemi, `https://api.flowella.io/v1/contacts/{{trigger.data.contactId}}` URL'si ve öncekiyle aynı `Authorization` başlığıyla bir **Send and receive data** eylemi ekleyin. Yanıt, kişinin `id`, `phone`, `waId`, `name`, `email`, `externalId`, `isOptedOut`, `createdAt` ve `updatedAt` değerlerini içerir.

Mesajın kendisini saklamak için `GET /v1/messages/{{trigger.data.messageId}}` adresine başka bir istek ekleyin. `body` alanı mesaj metnini tutar ve boş olabilir.

**6. Kişiyi güncelleyin**

Bir **Create or Update Person** eylemi ekleyin. Çalışma alanınızın kişiler için kullandığı tanımlayıcıyı seçin ve yalnızca ihtiyacınız olan öznitelikleri ayarlayın, örneğin son WhatsApp yanıtının zamanı. Bkz. Customer.io'nun [Create or update person](https://docs.customer.io/journeys/create-update-person/) kılavuzu.

> [!WARNING]
>
> Webhook ile tetiklenen bir otomasyonda **Create or Update Person**, tanımlayıcıyla eşleşen kimse yoksa yeni bir kişi oluşturur. İstemediğiniz kişileri oluşturmamak için adımın yalnızca tanımlayıcı değeri mevcut olduğunda çalışmasını sağlayan bir eylem koşulu ekleyin ve çalışma alanınızda olmayan bir numarayla test edin.

### Gelen webhook'un güvenliği

Flowella her isteği `X-Flowella-Signature` başlığıyla imzalar. Webhook ile tetiklenen bir Customer.io otomasyonu bu imzayı kontrol edemez, bu nedenle Customer.io webhook URL'sine sahip herkes ona veri gönderebilir. URL'yi gizli tutun ve gelen senkronizasyonu izin veya faturalandırma özniteliklerini değiştirmek için kullanmayın. Olayları önce kendi uç noktanız üzerinden yönlendiriyorsanız bkz. [İmzaları doğrulama](https://knowledge.flowella.io/tr/api-reference/webhooks.md#verify-signatures).

### Abonelikten çıkmalar

Bir kişi `STOP` veya başka bir abonelikten çıkma anahtar kelimesi gönderdiğinde Flowella, abonelikten çıkmayı o WhatsApp numarasına kaydeder ve Customer.io'dan gelenler dahil o numaradan kişiye yapılacak sonraki tüm gönderimleri engeller. Bkz. [Abonelikten çıkmalar](https://knowledge.flowella.io/tr/app/opt-outs.md).

Abonelikten çıkmaları Customer.io'ya kopyalamak için `optout.created` olayına güvenmeyin: şu anda bir kişinin bir numaradaki ilk abonelikten çıkması için tetiklenmez. Bunun yerine `createdAfter` ve `phone` filtrelerini kabul eden `GET /v1/opt-outs` ile abonelikten çıkmaları listeleyin.

## Sorun giderme

| Belirti | Neden | Çözüm |
| - | - | - |
| `Invalid or expired API key` ile `401` | Anahtar iptal edildi, değiştirildi veya yanlış yapıştırıldı. | Yeni bir anahtar oluşturun ve `Authorization` başlığını güncelleyin. Bkz. [API anahtarları](https://knowledge.flowella.io/tr/settings/api-keys.md). |
| Flowella'da **Could not load API keys** | API anahtarlarını yalnızca Owner ve Admin kullanıcıları yönetebilir. | Anahtarı oluşturması için bir Owner veya Admin'den yardım isteyin. |
| `Missing bearer token` ile `401` | İstek, yönlendirme yapan `https://app.flowella.io/api/v1` adresine gitti ve başlık düştü. | `https://api.flowella.io/v1` adresini kullanın. |
| Test `202` döndürüyor ancak hiçbir şey gelmiyor | Gövde veya `Idempotency-Key`, 7 gün içindeki önceki bir gönderimle eşleşti ya da aynı şablon aynı numaraya 15 saniye içinde gitti. | Her test için yeni bir `Idempotency-Key` değeri kullanın. |
| Kampanyada mesajı yalnızca ilk kişi aldı | Eylemde sabit bir `Idempotency-Key` değeri kaldı. | Başlığı kaldırın veya değerini her kişi için benzersiz yapın. |
| **Statistics** sekmesinde gönderim başarısız görünüyor | Meta mesajı teslim edemedi, örneğin numara WhatsApp'ta olmadığı için. | Nedeni **Details** sütununda okuyun. Bkz. [Meta hata kodları](https://knowledge.flowella.io/tr/whatsapp/errors/error-codes.md). |
| **Statistics** sekmesinde **Invalid phone number.** | Telefon özniteliği boş veya uluslararası biçimde değil. | Numaraları `+447700900123` gibi ülke koduyla saklayın. |
| Customer.io hiçbir gelen olay almıyor | Flowella webhook'u etkin değil veya `message.received` işaretli değil. | Flowella'da webhook'un **Delivery log** kaydını kontrol edin. Bkz. [Webhook'lar](https://knowledge.flowella.io/tr/settings/webhooks.md#delivery-log). |

## İlgili

> [card] [API'ye giriş](https://knowledge.flowella.io/tr/api-reference/introduction.md)
>
> Kimlik doğrulama, eşgüçlülük, hız sınırları ve hatalar.

> [card] [Webhook referansı](https://knowledge.flowella.io/tr/api-reference/webhooks.md)
>
> Olay türleri, istek gövdeleri ve imzalar.

> [card] [Şablon değişkenleri](https://knowledge.flowella.io/tr/app/template-variables.md)
>
> Değişkenler, örnekler ve yedek değerler.

> [card] [Toplu gönderim](https://knowledge.flowella.io/tr/app/bulk-send.md)
>
> Bunun yerine Flowella uygulamasından bir listeye şablon gönderin.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.