# Kanal Bağlantısı API'si
Bu kılavuz, API kullanarak mesajlaşma kanallarının bir hesaba nasıl bağlanacağını gösterir. Bir entegrasyon veya sarmalayıcı (wrapper) oluşturan geliştiriciler için yazılmıştır; bu nedenle tam isteklere, bunların yapılma sırasına ve aldığınız yanıtlara odaklanır.
Buradaki hemen hemen her kanal için geçerli olduğundan, en başta anlamanız gereken bir model vardır.
## Bağlan ve sorgula (connect-then-poll) modeli
Çoğu kanal tek bir API çağrısıyla bağlanamaz. WhatsApp, Instagram veya Messenger'ı bağlamak, hesap sahibinin kendi sağlayıcı hesabına giriş yapmasını ve erişimi onaylamasını gerektirir. Bu onay için **başsız (tamamen otomatik) bir yol yoktur** - gerçek bir kişinin bir tarayıcıda URL açması veya telefonuyla bir QR kodu taraması gerekir.
Bu nedenle akış her zaman şöyledir:
1. `POST` ile **bağlantıyı başlatın**. Yanıt size ya açılacak bir URL ya da görüntülenecek bir QR kodu verir.
2. **Bunu son kullanıcıya iletin** - URL'yi tarayıcılarında açın veya taramaları için QR kodunu ekranda oluşturun.
3. Durum bağlı bir duruma ulaşana kadar kısa aralıklarla (birkaç saniyede bir) `GET` ile **durum uç noktasını sorgulayın**.
Entegrasyonunuzun görevi bu döngüyü yönetmektir: URL'yi veya QR'ı gösterin, ardından tamamlanana kadar sorgulayın. Kullanıcı arayüzünüzü sorgulama etrafında planlayın; "tarayıcınızda işlemin bitmesi bekleniyor" mesajı içeren bir yükleme simgesi iyi çalışır.
::: note
**Not:** Başlamadan önce, planınızda API erişiminin etkinleştirildiğinden ve bir API anahtarınız olduğundan emin olun. Nasıl oluşturacağınızı öğrenmek için [API Erişimi](../integrations/api-access.md) bölümüne bakın. Aşağıdaki tüm istekler `https://api.youraiconnector.com/v1` temel URL'sini kullanır ve her isteğin kimliğini doğrulamanız gerekir. Kabul edilen dört yöntem için [Kimlik Doğrulama](authentication.md) bölümüne bakın; buradaki örnekler `X-API-Key` başlığını kullanır ve her sayfada daha basit olan `?apiKey=` sorgu biçimini gösteren bir cURL örneği bulunur.
:::
---
## Instagram + Messenger (Meta)
Instagram ve Messenger, her ikisi de bir Facebook Sayfası üzerinde çalıştığı için tek bir akışta birlikte bağlanır. Hesap sahibi Facebook aracılığıyla yetkilendirme yapar, siz yönettikleri Sayfaların listesini getirirsiniz ve hangi Sayfanın bağlanacağını seçersiniz.
### 1. Adım - Instagram + Messenger bağlantısını başlatın
```
POST /channels/meta/connect
```
Bu, bir onay URL'si döndürür. Bu istekte hiçbir kimlik bilgisi gönderilmez; bağlantı tamamen tarayıcıda yetkilendirilir.
**cURL**
```bash
curl -X POST "https://api.youraiconnector.com/v1/channels/meta/connect?apiKey=YOUR_API_KEY"
```
**JavaScript**
```javascript
const res = await fetch("https://api.youraiconnector.com/v1/channels/meta/connect", {
method: "POST",
headers: { "X-API-Key": "YOUR_API_KEY" },
});
const data = await res.json();
// Open data.oauth_url in the end user's browser.
```
**Python**
```python
import requests
res = requests.post(
"https://api.youraiconnector.com/v1/channels/meta/connect",
headers={"X-API-Key": "YOUR_API_KEY"},
)
data = res.json()
# Open data["oauth_url"] in the end user's browser.
```
**Yanıt**
```json
{
"success": true,
"oauth_url": "https://www.facebook.com/v21.0/dialog/oauth?client_id=...&state=...",
"state_token": "opaque-one-time-token",
"connect_url": "https://api.youraiconnector.com/v1/channels/meta/connect/page?token=eyJhbGciOi...",
"connect_url_expires_at": 1717000000000,
"expires_at": "2026-06-10T12:30:00.000Z"
}
```
Son kullanıcının Facebook'a giriş yapıp erişimi onaylayabilmesi için `oauth_url` adresini tarayıcılarında açın. Bağlantı girişimi `expires_at` (yaklaşık 30 dakika) süresinde sona erer; süre dolarsa baştan başlayın. `state_token` değerini kısa ömürlü bir gizli bilgi olarak kabul edin ve günlüğe kaydetmeyin.
### Instagram + Messenger için en kolay seçenek: `connect_url` teslim edin
Yanıt ayrıca hazır bir `connect_url` içerir: hesap sahibi için tüm akışı çalıştıran barındırılan bir sayfa. Sayfayı açıp Facebook'a giriş yaparlar ve birden fazla Sayfaları varsa, liste gösterilir ve hangisini bağlayacaklarını seçmelerine olanak tanınır - ardından kendi kendine başarı raporu verir. `oauth_url`'i kendiniz açmak, bir Sayfa seçici oluşturmak ve yoklama yapmak yerine bu bağlantıyı hesap sahibine verin. Bağlantı yaklaşık 30 dakika çalışır (`connect_url_expires_at`); süresi dolarsa yeni bir bağlantı başlatın. Aşağıdaki manuel adımlar, akışı yönetmek ve Sayfa seçiciyi kendileri oluşturmak isteyen entegrasyonlar içindir.
### Adım 2 - Sayfalar yüklenene kadar durumu sorgulayın
```
GET /channels/meta/status
```
Kullanıcı Facebook girişini tamamladıktan sonra, bu uç noktayı her birkaç saniyede bir sorgulayın. `status` alanı şu adımlardan geçer:
| `status` | Anlamı |
|---|---|
| `pending` | Onay henüz tamamlanmadı. Beklemeye devam edin. |
| `token_received` | Yetkilendirildi, ancak Sayfa listesi hala yükleniyor. |
| `pages_loaded` | Sayfalar mevcut - 3. adıma geçin. |
| `connected` | Bir Sayfa seçildi ve kanal yayında. |
**cURL**
```bash
curl "https://api.youraiconnector.com/v1/channels/meta/status" \
-H "X-API-Key: YOUR_API_KEY"
```
**JavaScript**
```javascript
const res = await fetch("https://api.youraiconnector.com/v1/channels/meta/status", {
headers: { "X-API-Key": "YOUR_API_KEY" },
});
const data = await res.json();
// Poll until data.status === "pages_loaded".
```
**Python**
```python
res = requests.get(
"https://api.youraiconnector.com/v1/channels/meta/status",
headers={"X-API-Key": "YOUR_API_KEY"},
)
data = res.json()
# Poll until data["status"] == "pages_loaded".
```
**Yanıt (sayfalar yüklendiğinde)**
```json
{
"success": true,
"status": "pages_loaded",
"pages": [
{
"id": "1234567890",
"name": "My Business Page",
"category": "Local business",
"instagram_business_account": {
"id": "17890000000000000",
"username": "mybusiness"
}
}
],
"selected_page": null
}
```
### Adım 3 - Sayfaları listeleyin (isteğe bağlı)
Sayfa listesini kendi başına getirmeyi tercih ederseniz (örneğin, bir seçici oluşturmak için), şunu kullanın:
```
GET /channels/meta/pages
```
```bash
curl "https://api.youraiconnector.com/v1/channels/meta/pages" \
-H "X-API-Key: YOUR_API_KEY"
```
Bu, durum uç noktasıyla aynı `pages` dizisini döndürür. (`status` uç noktası zaten sayfaları içerir, bu nedenle bu çağrı sadece kolaylık sağlamak içindir.)
### Adım 4 - Bağlanacak sayfayı seçin
```
POST /channels/meta/select-page
```
Kullanıcının seçtiği Sayfanın `page_id` değerini gönderin. O Sayfaya bağlı Instagram hesabı otomatik olarak bağlanır; yalnızca hangi Instagram hesabının kullanılacağını geçersiz kılmak istiyorsanız `instagram` nesnesine ihtiyacınız vardır.
**cURL**
```bash
curl -X POST "https://api.youraiconnector.com/v1/channels/meta/select-page" \
-H "X-API-Key: YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{ "page_id": "1234567890" }'
```
**JavaScript**
```javascript
const res = await fetch("https://api.youraiconnector.com/v1/channels/meta/select-page", {
method: "POST",
headers: {
"X-API-Key": "YOUR_API_KEY",
"Content-Type": "application/json",
},
body: JSON.stringify({ page_id: "1234567890" }),
});
const data = await res.json();
```
**Python**
```python
res = requests.post(
"https://api.youraiconnector.com/v1/channels/meta/select-page",
headers={"X-API-Key": "YOUR_API_KEY"},
json={"page_id": "1234567890"},
)
data = res.json()
```
**Yanıt**
```json
{
"success": true,
"page_id": "1234567890",
"instagram_business_account_id": "17890000000000000"
}
```
Kanal artık bağlı. Takip eden bir `GET /channels/meta/status`, `status: "connected"` değerini bildirecektir.
### Bağlı sayfanın gönderilerini listele
```
GET /channels/meta/posts?platform=instagram
```
Bağladığınız sayfanın son gönderilerini (Instagram medyası veya Facebook gönderileri) döndürür. Belirli bir gönderiye yapılan yorumlara tepki veren bir Giriş Noktası (Entry Point) ayarladığınızda, seçiciyi (picker) bunun üzerinden oluşturursunuz.
| Sorgu parametresi | Gerekli | Açıklama |
|---|---|---|
| `platform` | Evet | `instagram` veya `facebook`. Başka herhangi bir değer `400` döndürür. |
| `limit` | Hayır | Kaç tane gönderi döndürüleceği, `1`-`50` arası. Varsayılan değer `25`. |
| `after` | Hayır | Bir sonraki sayfa için imleç - önceki yanıttan `nextCursor` değerini iletin. |
**cURL**
```bash
curl "https://api.youraiconnector.com/v1/channels/meta/posts?platform=instagram&limit=25" \
-H "X-API-Key: YOUR_API_KEY"
```
**Yanıt**
```json
{
"success": true,
"connected": true,
"platform": "instagram",
"posts": [
{
"id": "17900000000000000",
"caption": "New spring menu is live",
"thumbnailUrl": "https://scontent.cdninstagram.com/...",
"permalink": "https://www.instagram.com/p/Cxxxxxxxxxx/",
"createdAt": "2026-05-02T09:12:00.000Z",
"mediaType": "REELS"
}
],
"nextCursor": "QVFIUkxxxxxxxx"
}
```
`mediaType`, Instagram'ın kendi etiketidir (`REELS`, `FEED`, `STORY` veya format - `IMAGE`, `VIDEO`, `CAROUSEL_ALBUM`); Facebook için bu her zaman `POST` değerindedir. `nextCursor`, son sayfada `null` değerini alır.
Eğer listelenecek bir şey yoksa, çağrı yine de `connected: false` ve boş bir `posts` dizisi içeren `200` değerini ve nedenini belirten bir `reason` döndürür:
| `reason` | Ne yapmalı |
|---|---|
| _(yok)_ | Henüz hiçbir sayfa bağlı değil - önce bağlantı akışını çalıştırın. |
| `no_instagram_account` | Bir Facebook Sayfası bağlı ancak ona bağlı bir Instagram işletme hesabı yok. Facebook gönderileri yine de düzgün bir şekilde listelenir. |
| `token_expired` | Kayıtlı sayfa kimlik bilgisi artık çalışmıyor - kanalı yeniden bağlayın. |
### Instagram + Messenger bağlantısını kesin
```
DELETE /channels/meta
```
```bash
curl -X DELETE "https://api.youraiconnector.com/v1/channels/meta" \
-H "X-API-Key: YOUR_API_KEY"
```
**Yanıt**
```json
{ "success": true, "disconnected": true }
```
Bu, hem Instagram hem de Messenger için gelen yönlendirmeyi durdurur. İşlem eş değerlidir (idempotent) - hiçbir şey bağlı değilken çağrıldığında bile başarılı olur.
---
## WhatsApp Business
Bu, resmi bir WhatsApp Business numarasını bağlar. Bağlantıyı çağırmadan önce numaranın hesapta zaten mevcut olması gerekir. Meta'da olduğu gibi, hesap sahibi tarayıcısında yetkilendirme yapar, ardından numara `ONLINE` bildirene kadar sorgulama yaparsınız.
### 1. Adım - WhatsApp Business bağlantısını başlatın
```
POST /channels/whatsapp/connect
```
**cURL**
```bash
curl -X POST "https://api.youraiconnector.com/v1/channels/whatsapp/connect?apiKey=YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{ "phone_number": "+14155551234" }'
```
**JavaScript**
```javascript
const res = await fetch("https://api.youraiconnector.com/v1/channels/whatsapp/connect", {
method: "POST",
headers: {
"X-API-Key": "YOUR_API_KEY",
"Content-Type": "application/json",
},
body: JSON.stringify({ phone_number: "+14155551234" }),
});
const data = await res.json();
// Open data.oauth_url in the account holder's browser.
```
**Python**
```python
res = requests.post(
"https://api.youraiconnector.com/v1/channels/whatsapp/connect",
headers={"X-API-Key": "YOUR_API_KEY"},
json={"phone_number": "+14155551234"},
)
data = res.json()
# Open data["oauth_url"] in the account holder's browser.
```
| Alan | Gerekli | Açıklama |
|---|---|---|
| `phone_number` | Evet | E.164 formatında bağlanacak numara (örneğin `+14155551234`). |
| `only_waba_sharing` | Hayır | Yetkilendirmeyi mevcut bir WhatsApp Business Hesabı paylaşımıyla sınırlandırır, yeni gönderici kurulumunu atlar. Varsayılan değer `false`. |
| `retry` | Hayır | Önceki girişimi tamamlanmamış bir numara için yetkilendirmeyi yeniden çalıştırır. Varsayılan değer `false`. |
| `business_name` | Hayır | Yalnızca onay ekranında gösterilen işletme adı için kozmetik geçersiz kılma (maks. 256 karakter). Saklanmaz. |
| `description` | Hayır | Yalnızca onay ekranında gösterilen işletme açıklaması için kozmetik geçersiz kılma (maks. 256 karakter). Saklanmaz. |
**Yanıt**
```json
{
"success": true,
"status": "pending",
"oauth_url": "https://www.facebook.com/v21.0/dialog/oauth?client_id=...&state=...",
"state_token": "opaque-one-time-token",
"expires_at": "2026-06-10T12:30:00.000Z"
}
```
Yetkilendirmek için hesap sahibinin tarayıcısında `oauth_url` adresini açın. Onayladıklarında, kayıt arka planda tamamlanır.
### Adım 2 - ONLINE olana kadar durumu sorgulayın
```
GET /channels/whatsapp/connect/{phoneNumber}/status
```
`status` değeri `ONLINE` olana kadar bunu sorgulayın.
**cURL**
```bash
curl "https://api.youraiconnector.com/v1/channels/whatsapp/connect/+14155551234/status" \
-H "X-API-Key: YOUR_API_KEY"
```
**JavaScript**
```javascript
const phone = encodeURIComponent("+14155551234");
const res = await fetch(
`https://api.youraiconnector.com/v1/channels/whatsapp/connect/${phone}/status`,
{ headers: { "X-API-Key": "YOUR_API_KEY" } }
);
const data = await res.json();
// Poll until data.status === "ONLINE".
```
**Python**
```python
import urllib.parse
phone = urllib.parse.quote("+14155551234")
res = requests.get(
f"https://api.youraiconnector.com/v1/channels/whatsapp/connect/{phone}/status",
headers={"X-API-Key": "YOUR_API_KEY"},
)
data = res.json()
# Poll until data["status"] == "ONLINE".
```
**Yanıt**
```json
{
"success": true,
"phone_number": "+14155551234",
"channel": "whatsapp",
"status": "ONLINE",
"status_reason": null,
"live": true
}
```
`status` alanı şunlar olabilir:
| `status` | Anlamı |
|---|---|
| `PENDING` | Yetkilendirildi, onay süreci devam ediyor. Sorgulamaya devam edin. |
| `ONLINE` | Bağlandı ve gönderime hazır. |
| `RATE_LIMITED` | Çok fazla deneme - tekrar denemeden önce bekleyin. |
| `REGISTRATION_FAILED` | Kurulum tamamlanamadı. |
| `DELETED` | Kayıt artık mevcut değil. |
`live: true`, durumun sağlayıcıya karşı gerçek zamanlı olarak kontrol edildiği anlamına gelir; `false` ise son önbelleğe alınmış durumdan geldiği anlamına gelir.
### Bir WhatsApp Business numarasının bağlantısını kesin
```
DELETE /channels/whatsapp/{phoneNumber}
```
```bash
curl -X DELETE "https://api.youraiconnector.com/v1/channels/whatsapp/+14155551234" \
-H "X-API-Key: YOUR_API_KEY"
```
**Yanıt**
```json
{ "success": true, "phone_number": "+14155551234", "disconnected": true }
```
Numaranın kendisi hesapta kalır, böylece daha sonra tekrar bağlayabilirsiniz.
---
## WhatsApp Web
WhatsApp Web, tıpkı WhatsApp uygulamasında bir cihazı bağlamak gibi, bir QR kodunu tarayarak normal bir WhatsApp numarasını bağlar. İş akışı şöyledir: oturumu başlatın, QR kodunu getirin ve gösterin, ardından durum `connected` olana kadar sorgulama yapın.
### 1. Adım - Bir WhatsApp Web eşleştirme oturumu başlatın
```
POST /channels/whatsapp-web/connections
```
**cURL**
```bash
curl -X POST "https://api.youraiconnector.com/v1/channels/whatsapp-web/connections?apiKey=YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{ "phone_number": "+15551230000" }'
```
**JavaScript**
```javascript
const res = await fetch("https://api.youraiconnector.com/v1/channels/whatsapp-web/connections", {
method: "POST",
headers: {
"X-API-Key": "YOUR_API_KEY",
"Content-Type": "application/json",
},
body: JSON.stringify({ phone_number: "+15551230000" }),
});
const data = await res.json();
```
**Python**
```python
res = requests.post(
"https://api.youraiconnector.com/v1/channels/whatsapp-web/connections",
headers={"X-API-Key": "YOUR_API_KEY"},
json={"phone_number": "+15551230000"},
)
data = res.json()
```
| Alan | Gerekli | Açıklama |
|---|---|---|
| `phone_number` | Evet | Bağlanacak WhatsApp numarası, E.164 formatında. |
| `proxy_country` | Hayır | Yönlendirme bölgesi için ISO 3166-1 alpha-2 ülke kodu. Belirtilmediğinde numaradan otomatik olarak algılanır. |
| `force_new` | Hayır | Mevcut oturumu atın ve yeni bir eşleştirme başlatın. Varsayılan değer `false`. |
| `import_contacts` | Hayır | İlk bağlantıda cihazın mevcut kişilerini içe aktarın. Varsayılan değer `false`. |
| `pause_ai_for_imported_contacts` | Hayır | Kişileri içe aktarırken, onlar için otomatik yanıtları duraklatın. Varsayılan değer `true`. |
| `import_existing_chats` | Hayır | Mevcut sohbet geçmişini içe aktarın (`import_contacts: true` gerektirir). Varsayılan değer `false`. |
**Yanıt**
```json
{
"success": true,
"phone_number": "+15551230000",
"session_id": "session-id",
"status": "qr_pending",
"connect_url": "https://api.youraiconnector.com/v1/channels/whatsapp-web/connect?token=eyJhbGciOi...",
"connect_url_expires_at": 1717000000000,
"poll_qr_path": "/v1/channels/whatsapp-web/connections/%2B15551230000/qr",
"poll_status_path": "/v1/channels/whatsapp-web/connections/%2B15551230000/status"
}
```
### WhatsApp Web için en kolay seçenek: `connect_url` teslim edin
Yanıt, kullanıma hazır bir `connect_url` içerir: QR kodunu gösteren, döndükçe otomatik olarak yenileyen ve numara bağlandığı anda başarı mesajına geçen barındırılan bir sayfa. Bu bağlantıyı hesap sahibine vermeniz (tarayıcıda açın, onlara gönderin veya bir QR/buton olarak gösterin) ve WhatsApp ile taratmalarını sağlamanız yeterlidir; QR'ı kendiniz getirmenize veya herhangi bir şeyi sorgulamanıza gerek yoktur. Bağlantı yaklaşık 30 dakika boyunca çalışır (`connect_url_expires_at`); bu süre dolmadan işlemi tamamlayamazlarsa, yeni bir tane almak için yeni bir bağlantı başlatın.
Bir kişinin bağlantı açabildiği durumlarda önerilen yol budur. Aşağıdaki manuel adımlar (QR'ı kendiniz getirme, durumu sorgulama), QR'ı kendi arayüzlerinde oluşturmak isteyen entegrasyonlar içindir.
Yanıt ayrıca kullanmanız için tam `poll_qr_path` ve `poll_status_path` değerlerini de verir, böylece bunları kendiniz oluşturmak zorunda kalmazsınız.
### Adım 2 - QR kodunu getirme ve gösterme
```
GET /channels/whatsapp-web/connections/{phoneNumber}/qr
```
**cURL**
```bash
curl "https://api.youraiconnector.com/v1/channels/whatsapp-web/connections/+15551230000/qr" \
-H "X-API-Key: YOUR_API_KEY"
```
**JavaScript**
```javascript
const phone = encodeURIComponent("+15551230000");
const res = await fetch(
`https://api.youraiconnector.com/v1/channels/whatsapp-web/connections/${phone}/qr`,
{ headers: { "X-API-Key": "YOUR_API_KEY" } }
);
const data = await res.json();
// Render data.qr_data_url as an ![]()
for the user to scan.
```
**Python**
```python
import urllib.parse
phone = urllib.parse.quote("+15551230000")
res = requests.get(
f"https://api.youraiconnector.com/v1/channels/whatsapp-web/connections/{phone}/qr",
headers={"X-API-Key": "YOUR_API_KEY"},
)
data = res.json()
# Render data["qr_data_url"] for the user to scan.
```
**Yanıt**
```json
{
"success": true,
"phone_number": "+15551230000",
"status": "qr_pending",
"qr_code": "2@raw-qr-payload-string...",
"qr_data_url": "data:image/png;base64,iVBORw0KGgo...",
"expires_at": "2026-06-10T12:05:00.000Z"
}
```
Kullanıcının telefonuyla taraması için QR kodunu oluşturun (WhatsApp > Bağlı Cihazlar > Cihaz Bağla):
- `qr_data_url` kullanıma hazır bir görseldir - doğrudan bir `![]()
` içine yerleştirin.
- `qr_code`, görseli kendiniz oluşturmayı tercih ederseniz kullanabileceğiniz ham veridir.
QR kodunun ömrü kısadır. Oturumu başlattıktan hemen sonra bu çağrıyı yaparsanız "QR code not available yet" (QR kodu henüz hazır değil) hatası içeren bir `404` alabilirsiniz; sadece bir an bekleyin ve tekrar deneyin. Eğer `410` ("QR code expired" - QR kodu süresi doldu) alırsanız, yeni bir kod almak için bağlantıyı baştan başlatın.
### Adım 3 - Bağlanana kadar durumu sorgulama
```
GET /channels/whatsapp-web/connections/{phoneNumber}/status
```
**cURL**
```bash
curl "https://api.youraiconnector.com/v1/channels/whatsapp-web/connections/+15551230000/status" \
-H "X-API-Key: YOUR_API_KEY"
```
**JavaScript**
```javascript
const phone = encodeURIComponent("+15551230000");
const res = await fetch(
`https://api.youraiconnector.com/v1/channels/whatsapp-web/connections/${phone}/status`,
{ headers: { "X-API-Key": "YOUR_API_KEY" } }
);
const data = await res.json();
// Poll until data.status === "connected" (or "open").
```
**Python**
```python
import urllib.parse
phone = urllib.parse.quote("+15551230000")
res = requests.get(
f"https://api.youraiconnector.com/v1/channels/whatsapp-web/connections/{phone}/status",
headers={"X-API-Key": "YOUR_API_KEY"},
)
data = res.json()
# Poll until data["status"] == "connected" (or "open").
```
**Yanıt**
```json
{
"success": true,
"phone_number": "+15551230000",
"status": "connected",
"has_qr": false,
"qr_expires_at": null,
"last_activity": null,
"message_count": null,
"proxy": null,
"live": true
}
```
| `status` | Anlamı |
|---|---|
| `not_initialized` | Henüz oturum yok (son hata). |
| `qr_pending` | QR kodunun taranması bekleniyor. |
| `connecting` | Tarandı, kurulum tamamlanıyor. |
| `connected` / `open` | Bağlandı ve aktif - bu başarıdır. |
| `disconnected` | Oturum sonlandırıldı (son hata). |
### Bir WhatsApp Web oturumunun bağlantısını kesin
```
DELETE /channels/whatsapp-web/connections/{phoneNumber}
```
```bash
curl -X DELETE "https://api.youraiconnector.com/v1/channels/whatsapp-web/connections/+15551230000" \
-H "X-API-Key: YOUR_API_KEY"
```
**Yanıt**
```json
{ "success": true, "phone_number": "+15551230000", "status": "removed" }
```
Bu, cihazın bağlantısını keser ve bağlantıyı kaldırır. Yerel durumu her zaman temizler, bu nedenle altta yatan oturum zaten gitmiş olsa bile işlemsel olarak eş değerdir (idempotent).
---
## Telegram
> **Kullanılabilirlik:** Telegram diğer tüm kanallar gibi bağlanır ve her hesaba açıktır; sizin için açılmasına gerek yoktur. Telegram hesabın planına dahil değilse, aşağıdaki Telegram uç noktaları yine de `403` döndürebilir; bu durumda hata `"This channel is not included in your current plan. Upgrade to unlock it."` şeklinde görünür.
Telegram, kişisel bir hesabı telefon numarası ve tek kullanımlık giriş kodu (ve hesapta ayarlıysa iki faktörlü parola) ile bağlar. Akış şöyledir: oturumu başlatın, kodu gönderin, isteğe bağlı olarak parolayı gönderin ve ardından durum aracılığıyla onaylayın.
### 1. Adım - Bir Telegram bağlantı oturumu başlatın
```
POST /channels/telegram/connect
```
**cURL**
```bash
curl -X POST "https://api.youraiconnector.com/v1/channels/telegram/connect?apiKey=YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{ "phone_number": "+14155550100" }'
```
**JavaScript**
```javascript
const res = await fetch("https://api.youraiconnector.com/v1/channels/telegram/connect", {
method: "POST",
headers: {
"X-API-Key": "YOUR_API_KEY",
"Content-Type": "application/json",
},
body: JSON.stringify({ phone_number: "+14155550100" }),
});
const data = await res.json();
```
**Python**
```python
res = requests.post(
"https://api.youraiconnector.com/v1/channels/telegram/connect",
headers={"X-API-Key": "YOUR_API_KEY"},
json={"phone_number": "+14155550100"},
)
data = res.json()
```
| Alan | Gerekli | Açıklama |
|---|---|---|
| `phone_number` | Evet | E.164 formatında bağlanacak hesap telefon numarası. |
| `mode` | Hayır | `code` (varsayılan) hesaba tek kullanımlık bir giriş kodu gönderir; `qr` bir giriş belirteci ve görüntülenecek QR URL'si döndürür. |
| `proxy_country` | Hayır | Giden ağ rotası için ISO 3166-1 alpha-2 ülke kodu. |
| `force_new` | Hayır | `true` olduğunda, mevcut tüm oturumları atar ve yeni bir başlangıç yapar. |
**Yanıt**
```json
{
"success": true,
"phone_number": "+14155550100",
"status": "code_required",
"session_id": "session-id",
"connect_url": "https://api.youraiconnector.com/v1/channels/telegram/connect/page?token=eyJhbGciOi...",
"connect_url_expires_at": 1717000000000
}
```
`code` modunda hesap Telegram'da bir giriş kodu alır ve `status`, `code_required` olur. (`qr` modunda yanıt ayrıca `login_token` ve tarama için `qr_url` içerir, ayrıca `status`, `qr_required` olur.)
### Telegram için en kolay seçenek: `connect_url` teslim edin
Yanıt, bağlantıyı kendi başına tamamlayan barındırılan bir sayfa olan hazır bir `connect_url` içerir. `code` modunda hesap sahibi giriş kodunu ve varsa iki adımlı doğrulama şifresini girer. `qr` modunda sayfa, Telegram uygulamasından taramaları için kendisini yenileyen bir QR kodu gösterir. Her iki durumda da başarıyı kendi kendine bildirir, bu nedenle kendi kullanıcı arayüzünüzü oluşturup sorgulama yapmak yerine bu bağlantıyı doğrudan hesap sahibine verebilirsiniz. Bağlantı yaklaşık 30 dakika (`connect_url_expires_at`) boyunca çalışır; süresi dolarsa, yeni bir tane almak için bağlantıyı yeniden başlatın.
Aşağıdaki manuel adımlar (kodu kendiniz toplayın, gönderin ve durumu sorgulayın; veya `qr_url` oluşturup sorgulayın), kullanıcı arayüzünü kendisi oluşturmak isteyen entegrasyonlar içindir.
### Adım 2 - Giriş kodunu gönderin
```
POST /channels/telegram/connect/{phoneNumber}/verify-code
```
**cURL**
```bash
curl -X POST "https://api.youraiconnector.com/v1/channels/telegram/connect/+14155550100/verify-code" \
-H "X-API-Key: YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{ "code": "12345" }'
```
**JavaScript**
```javascript
const phone = encodeURIComponent("+14155550100");
const res = await fetch(
`https://api.youraiconnector.com/v1/channels/telegram/connect/${phone}/verify-code`,
{
method: "POST",
headers: {
"X-API-Key": "YOUR_API_KEY",
"Content-Type": "application/json",
},
body: JSON.stringify({ code: "12345" }),
}
);
const data = await res.json();
```
**Python**
```python
import urllib.parse
phone = urllib.parse.quote("+14155550100")
res = requests.post(
f"https://api.youraiconnector.com/v1/channels/telegram/connect/{phone}/verify-code",
headers={"X-API-Key": "YOUR_API_KEY"},
json={"code": "12345"},
)
data = res.json()
```
**Yanıt**
```json
{
"success": true,
"phone_number": "+14155550100",
"status": "connected",
"telegram_user_id": "100000001",
"username": "myhandle"
}
```
Eğer `status`, `connected` ise işleminiz tamamlanmıştır. Eğer hesapta iki faktörlü doğrulama etkinse, `status` bunun yerine `password_required` olacaktır - 3. adıma geçin.
### Adım 3 - İki faktörlü doğrulama şifresini gönderin (yalnızca gerekliyse)
```
POST /channels/telegram/connect/{phoneNumber}/verify-password
```
Bunu yalnızca 2. adım `password_required` döndürdüğünde çağırın.
**cURL**
```bash
curl -X POST "https://api.youraiconnector.com/v1/channels/telegram/connect/+14155550100/verify-password" \
-H "X-API-Key: YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{ "password": "the-2fa-password" }'
```
**JavaScript**
```javascript
const phone = encodeURIComponent("+14155550100");
const res = await fetch(
`https://api.youraiconnector.com/v1/channels/telegram/connect/${phone}/verify-password`,
{
method: "POST",
headers: {
"X-API-Key": "YOUR_API_KEY",
"Content-Type": "application/json",
},
body: JSON.stringify({ password: "the-2fa-password" }),
}
);
const data = await res.json();
```
**Python**
```python
import urllib.parse
phone = urllib.parse.quote("+14155550100")
res = requests.post(
f"https://api.youraiconnector.com/v1/channels/telegram/connect/{phone}/verify-password",
headers={"X-API-Key": "YOUR_API_KEY"},
json={"password": "the-2fa-password"},
)
data = res.json()
```
**Yanıt**
```json
{
"success": true,
"phone_number": "+14155550100",
"status": "connected",
"telegram_user_id": "100000001",
"username": "myhandle"
}
```
### Telegram durumunu kontrol edin
```
GET /channels/telegram/connect/{phoneNumber}/status
```
```bash
curl "https://api.youraiconnector.com/v1/channels/telegram/connect/+14155550100/status" \
-H "X-API-Key: YOUR_API_KEY"
```
**Yanıt**
```json
{
"success": true,
"phone_number": "+14155550100",
"status": "connected",
"telegram_user_id": "100000001",
"live": true
}
```
`status`; `connected`, `code_required`, `password_required`, `initializing`, `disconnected`, `not_initialized` veya `error` olabilir.
### Telegram bağlantısını kesin
```
DELETE /channels/telegram/{phoneNumber}
```
```bash
curl -X DELETE "https://api.youraiconnector.com/v1/channels/telegram/+14155550100" \
-H "X-API-Key: YOUR_API_KEY"
```
**Yanıt**
```json
{ "success": true, "phone_number": "+14155550100", "status": "removed" }
```
İdempotent - tekrarlanan çağrılar başarılı olur.
---
## Instagram (kişisel hesap)
> Sınırlı erişimli beta, hesap bazında etkinleştirilir. Bu, kişisel bir Instagram hesabını kullanıcı adı ve şifresiyle (resmi İşletme API'si değil) giriş yaparak bağlar. Hesap beta için etkinleştirilmemişse, bağlantı çağrısı bir izin hatası döndürür.
Bu işlem hesap sahibinin kendi Instagram giriş bilgilerini gerektirdiğinden, en basit yol onlara barındırılan `connect_url`'ı vermek ve kimlik bilgilerini orada girmelerine izin vermektir - entegrasyonunuz şifreyi asla işlemez.
### 1. Adım - Bir Instagram (kişisel) bağlantısı başlatın
```
POST /channels/instagram-private/connect
```
Instagram `username` ve `password` gönderin.
**Yanıt**
```json
{
"success": true,
"status": "connected",
"connect_url": "https://api.youraiconnector.com/v1/channels/instagram-private/connect/page?token=eyJhbGciOi...",
"connect_url_expires_at": 1717000000000
}
```
Hesapta iki faktörlü kimlik doğrulama varsa veya Instagram bir kontrol noktası (checkpoint) sunarsa, `status` değeri `two_factor_required` veya `challenge_required` olarak döner - kodu aşağıdaki `/connect/{id}/verify-2fa` veya `/connect/{id}/verify-challenge` adresine gönderin, ardından `connected` olana kadar `/connect/{id}/status`'i sorgulayın. `{id}`, yukarıdaki yanıtta `account_id`/`username` olarak döndürülen normalleştirilmiş Instagram kullanıcı adıdır - aşağıdaki her adımda bunu kullanın.
### Adım 2 - İki faktörlü kodu gönderin (istenirse)
```
POST /channels/instagram-private/connect/{id}/verify-2fa
```
Bunu yalnızca 1. adım (veya 3. adım) `two_factor_required` döndürdüğünde çağırın.
```bash
curl -X POST "https://api.youraiconnector.com/v1/channels/instagram-private/connect/yourbrand/verify-2fa" \
-H "X-API-Key: YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{ "code": "123456" }'
```
**Yanıt**
```json
{
"success": true,
"account_id": "yourbrand",
"status": "connected",
"ig_user_id": "17890000000000000",
"username": "yourbrand"
}
```
`status` değeri `connected` (tamamlandı), `two_factor_required` (yanlış kod, tekrar deneyin) veya `challenge_required` (Instagram ayrıca bir kontrol noktası kodu istiyor - 3. adıma gidin) olarak dönebilir.
### Adım 3 - Kontrol noktası onay kodunu gönderin (istenirse)
```
POST /channels/instagram-private/connect/{id}/verify-challenge
```
Bunu yalnızca önceki bir adım `challenge_required` döndürdüğünde çağırın. Yukarıdaki 2. adımla aynı istek ve yanıt yapısına sahiptir.
```bash
curl -X POST "https://api.youraiconnector.com/v1/channels/instagram-private/connect/yourbrand/verify-challenge" \
-H "X-API-Key: YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{ "code": "123456" }'
```
### Instagram (kişisel) durumunu kontrol et
```
GET /channels/instagram-private/connect/{id}/status
```
`status` değeri `connected` olana veya nihai bir hata bildirene kadar bunu sorgulayın.
```bash
curl "https://api.youraiconnector.com/v1/channels/instagram-private/connect/yourbrand/status" \
-H "X-API-Key: YOUR_API_KEY"
```
**Yanıt**
```json
{
"success": true,
"account_id": "yourbrand",
"status": "connected",
"ig_user_id": "17890000000000000",
"username": "yourbrand",
"live": true
}
```
`status` değeri `connected`, `two_factor_required`, `challenge_required`, `initializing`, `disconnected`, `not_initialized` veya `error` olabilir. `live: true`, bunun önbelleğe alınmış bir değer yerine doğrudan bağlantı çalışanından canlı olarak okunduğu anlamına gelir.
### Instagram (kişisel) için en kolay seçenek: `connect_url` teslim edin
Yanıt bir `connect_url` içerir: hesap sahibinin Instagram kullanıcı adını ve şifresini (ve Instagram isterse bir 2FA veya kontrol noktası kodunu) girdiği ve kendi kendine başarı raporu veren barındırılan bir sayfa. Kimlik bilgileri doğrudan Instagram'a gider ve saklanmaz. Şifrelerini kendi kullanıcı arayüzünüzde toplamak yerine bu bağlantıyı hesap sahibine verin. Bağlantı yaklaşık 30 dakika çalışır (`connect_url_expires_at`).
### Instagram'ın bağlantısını kes (kişisel)
```
DELETE /channels/instagram-private/{id}
```
İdempotent - tekrarlanan çağrılar başarılı olur.
### Takipçileri eşitle
```
POST /channels/instagram-private/{id}/sync-followers
```
Bağlı bir hesap için manuel olarak bir takipçi eşitlemesi tetikler - arka planda otomatik olarak çalışan işin aynısıdır, burada isteğe bağlı bir "Takipçileri yenile" eylemi olarak sunulmuştur. Hesabın mevcut takipçi listesini getirir, yeni kişileri kaydeder ve (Canlı bir kampanyada takipçi erişimi açık olduğunda) yeni takipçilere günlük sınıra kadar bir açılış DM'si gönderir.
```bash
curl -X POST "https://api.youraiconnector.com/v1/channels/instagram-private/yourbrand/sync-followers" \
-H "X-API-Key: YOUR_API_KEY"
```
**Yanıt**
```json
{
"success": true,
"accountId": "yourbrand",
"totalFollowers": 1204,
"newFollowers": 6,
"dmsSent": 6,
"isBaselineSeed": false
}
```
> Bu beş alan, bu sayfada `snake_case` yerine `camelCase` dönen tek yerdir - bu bir yazım hatası değil, bu uç noktanın mevcut çalışma şeklidir. `isBaselineSeed: true`, bunun bağlantı kurulduktan sonraki ilk eşitleme olduğu anlamına gelir; bu sadece başlangıç takipçi listesini kaydeder ve asla erişim DM'leri göndermez (bu nedenle o çalıştırmada `dmsSent` her zaman `0` olur).
Bir hesap için yapılan ilk çağrı biraz zaman alabilir (tüm takipçi listesini taradığı için); sonraki çağrılar daha hızlıdır çünkü sadece yeni takipçiler arasındaki fark alınır. `404`, hesabın bağlı olmadığı anlamına gelir; `412`, bağlantının henüz başlatılmasının tamamlanmadığı anlamına gelir - bekleyin ve tekrar deneyin.
---
## LINE
LINE, tarayıcı yönlendirmesi veya yoklama (polling) gerektirmediği için bağlanması en kolay kanaldır. Müşteri, LINE Developers konsolunda bir Messaging API kanalı oluşturur, iki değeri kopyalar ve siz bunları tek bir çağrıda gönderirsiniz. Ardından, konsola yapıştırmaları için onlara bir webhook URL'si verirsiniz.
### 1. Adım - Kanal kimlik bilgileriyle bağlanma
```
POST /channels/line
```
**cURL**
```bash
curl -X POST "https://api.youraiconnector.com/v1/channels/line?apiKey=YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"channel_access_token": "LONG_LIVED_CHANNEL_ACCESS_TOKEN",
"channel_secret": "CHANNEL_SECRET"
}'
```
**JavaScript**
```javascript
const res = await fetch("https://api.youraiconnector.com/v1/channels/line", {
method: "POST",
headers: {
"X-API-Key": "YOUR_API_KEY",
"Content-Type": "application/json",
},
body: JSON.stringify({
channel_access_token: "LONG_LIVED_CHANNEL_ACCESS_TOKEN",
channel_secret: "CHANNEL_SECRET",
}),
});
const data = await res.json();
```
**Python**
```python
res = requests.post(
"https://api.youraiconnector.com/v1/channels/line",
headers={"X-API-Key": "YOUR_API_KEY"},
json={
"channel_access_token": "LONG_LIVED_CHANNEL_ACCESS_TOKEN",
"channel_secret": "CHANNEL_SECRET",
},
)
data = res.json()
```
| Alan | Gerekli | Açıklama |
|---|---|---|
| `channel_access_token` | Evet | Resmi Hesabın uzun ömürlü Messaging API kanal erişim belirteci. Mesaj gönderip almak için kullanılır. |
| `channel_secret` | Evet | Gelen etkinlik imzalarını doğrulamak için kullanılan Messaging API kanal gizli anahtarı. |
| `channel_id` | Hayır | Sayısal kanal kimliği. Yalnızca bilgilendirme amaçlıdır. |
**Yanıt**
```json
{
"success": true,
"status": "connected",
"bot_user_id": "Uxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
"basic_id": "@mybusiness",
"display_name": "My Business",
"picture_url": "https://...",
"chat_mode": "bot",
"chat_mode_ok": true,
"webhook_url": "https://api.youraiconnector.com/line/webhook/..."
}
```
Bir sonraki adımda yapacaklarınız için iki alan önemlidir:
- **`webhook_url`** - müşteri bunu LINE Developers konsolundaki LINE kanalının **Webhook URL** alanına yapıştırmalıdır (ve "Use webhook" seçeneğini etkinleştirmelidir). Bunu yapana kadar hiçbir gelen mesaj ulaşmaz. Bunu onlara belirgin bir şekilde gösterin.
- **`chat_mode_ok`** - `false` olduğunda, Resmi Hesap "sohbet" modundadır ve LINE Resmi Hesap Yöneticisi'nde "bot" moduna geçirilene kadar mesaj alıp gönderemez. Katılım sürecinizi bu bayrağa göre düzenleyin ve müşteriye modu değiştirmesini söyleyin.
> `channel_access_token` ve `channel_secret` hiçbir uç nokta tarafından döndürülmez. Onlara tekrar ihtiyacınız olursa kendi tarafınızda saklayın; aksi takdirde LINE konsolundan tekrar yapıştırın.
Burada döndürülen `bot_user_id`, aşağıdaki durum, doğrulama ve bağlantı kesme çağrılarında kullandığınız bağlantı tanımlayıcısıdır.
### 2. Adım - Webhook kurulumundan sonra yeniden doğrulama
```
POST /channels/line/{botUserId}/verify-webhook
```
Müşteri webhook URL'sini yapılandırmayı bitirip bot moduna geçtikten sonra, depolanan belirteci yeniden doğrulamak ve önbelleğe alınmış sohbet modunu yenilemek için bunu çağırın.
```bash
curl -X POST "https://api.youraiconnector.com/v1/channels/line/Uxxxxxxxx.../verify-webhook" \
-H "X-API-Key: YOUR_API_KEY"
```
**Yanıt**
```json
{
"success": true,
"token_valid": true,
"chat_mode": "bot",
"chat_mode_ok": true,
"webhook_url": "https://api.youraiconnector.com/line/webhook/..."
}
```
`token_valid` değeri `false` ise, depolanan erişim belirteci artık kimlik doğrulaması yapmıyordur; müşterinin bunu konsolda yeniden oluşturmasını sağlayın ve yeni belirteçle `POST /channels/line` öğesini tekrar çağırın.
### LINE durumunu kontrol et
```
GET /channels/line/{botUserId}/status
```
```bash
curl "https://api.youraiconnector.com/v1/channels/line/Uxxxxxxxx.../status" \
-H "X-API-Key: YOUR_API_KEY"
```
**Yanıt**
```json
{
"success": true,
"bot_user_id": "Uxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
"channel": "line",
"status": "connected",
"basic_id": "@mybusiness",
"display_name": "My Business",
"picture_url": "https://...",
"chat_mode": "bot",
"is_active": true,
"live": false
}
```
LINE'ın canlı bir durum akışı yoktur, bu nedenle `live` burada her zaman `false` değerindedir; değerler bağlantı (veya son doğrulama) anında yakalanan durumu yansıtır.
### LINE bağlantısını kes
```
DELETE /channels/line/{botUserId}
```
```bash
curl -X DELETE "https://api.youraiconnector.com/v1/channels/line/Uxxxxxxxx..." \
-H "X-API-Key: YOUR_API_KEY"
```
**Yanıt**
```json
{ "success": true, "status": "removed", "bot_user_id": "Uxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" }
```
---
## Viber
Viber, LINE ile aynı şekilde bağlanır - botun kimlik doğrulama belirtecini (auth token) Viber Yönetici Panelinden tek bir çağrıda yapıştırırsınız - bilinmesi gereken bir farkla: bağlanmak aynı zamanda webhook'umuzu o anda botunuza KAYDEDER, bu nedenle sonrasında ayrı bir konsol adımı yoktur. Bu aynı zamanda, sadece belirtecin kendisi yanlışsa değil, girişimiz Viber'in senkron webhook kontrolüne yanıt veremezse de bir bağlantı girişiminin başarısız olabileceği anlamına gelir.
### Adım 1 - Botun kimlik doğrulama belirteci ile bağlanın
```
POST /channels/viber
```
| Alan | Gerekli | Açıklama |
|---|---|---|
| `auth_token` | Evet | Viber Yönetici Panelinden (Bot Ayarlarım) alınan botun kimlik doğrulama belirteci. |
```bash
curl -X POST "https://api.youraiconnector.com/v1/channels/viber?apiKey=YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{ "auth_token": "444d5555e6666f7777a8888b9999c000" }'
```
**Yanıt**
```json
{
"success": true,
"status": "connected",
"bot_id": "botIdFromViber",
"bot_name": "My Business Bot",
"bot_avatar": "https://...",
"bot_uri": "mybusinessbot",
"subscribers_count": 0,
"webhook_url": "https://api.youraiconnector.com/v1/incoming-viber-message/...",
"event_types": ["delivered", "seen", "failed", "subscribed", "unsubscribed", "conversation_started"]
}
```
Kimlik doğrulama belirteci hiçbir uç nokta tarafından geri yansıtılmaz - tekrar yapıştırmanız gerekirse kendi tarafınızda saklayın. `bot_id`, aşağıdaki durum, doğrulama ve bağlantı kesme çağrıları tarafından kullanılan bağlantı tanımlayıcısıdır.
### Viber durumunu kontrol et
```
GET /channels/viber/{botId}/status
```
Depolanan bağlantı durumunu bildirir. Botu Viber'e karşı yeniden kontrol etmek ve önbelleğe alınmış webhook kaydını yenilemek için `?live=true` ekleyin - sessiz bir botun gerçekten bozuk olduğunu varsaymadan önce kullanışlıdır.
```bash
curl "https://api.youraiconnector.com/v1/channels/viber/botIdFromViber/status?live=true" \
-H "X-API-Key: YOUR_API_KEY"
```
**Yanıt**
```json
{
"success": true,
"bot_id": "botIdFromViber",
"channel": "viber",
"status": "connected",
"bot_name": "My Business Bot",
"bot_avatar": "https://...",
"bot_uri": "mybusinessbot",
"webhook_url": "https://api.youraiconnector.com/v1/incoming-viber-message/...",
"registered_webhook": "https://api.youraiconnector.com/v1/incoming-viber-message/...",
"webhook_ok": true,
"subscribers_count": 128,
"is_active": true,
"live": true
}
```
`webhook_ok: false`, botun webhook'unun artık bizi işaret etmediği anlamına gelir - gelen mesajlar ulaşılamaz durumdadır. Bu genellikle başka bir aracın aynı botu daha sonra bağladığı anlamına gelir (Viber'in webhook kaydı son yazılanı kabul eder). Bunu aşağıdaki yeniden doğrulama çağrısı ile düzeltin, müşteriden belirtecini tekrar yapıştırmasını istemenize gerek yoktur. `live`, yanıt taze bir Viber kontrolü yerine son önbelleğe alınmış durum olduğunda `false` olur.
### Webhook'u yeniden kaydet
```
POST /channels/viber/{botId}/verify-webhook
```
`webhook_ok: false` için onarım eylemi - halihazırda saklanan kimlik doğrulama belirtecini kullanarak bot üzerindeki webhook'umuzu yeniden kaydeder.
```bash
curl -X POST "https://api.youraiconnector.com/v1/channels/viber/botIdFromViber/verify-webhook" \
-H "X-API-Key: YOUR_API_KEY"
```
**Yanıt**
```json
{ "success": true, "token_valid": true, "webhook_ok": true, "webhook_url": "https://api.youraiconnector.com/v1/incoming-viber-message/...", "event_types": ["delivered", "seen", "failed", "subscribed", "unsubscribed", "conversation_started"] }
```
`token_valid: false`, saklanan belirtecin artık çalışmadığı anlamına gelir - `POST /channels/viber` ve yeni bir belirteç ile yeniden bağlanın.
### Viber bağlantısını kes
```
DELETE /channels/viber/{botId}
```
Web kancamızı Viber tarafında kayıttan düşürür (en iyi çaba ile) ve bağlantıyı kaldırır.
```bash
curl -X DELETE "https://api.youraiconnector.com/v1/channels/viber/botIdFromViber" \
-H "X-API-Key: YOUR_API_KEY"
```
**Yanıt**
```json
{ "success": true, "status": "removed", "bot_id": "botIdFromViber", "webhook_removed": true }
```
---
## TikTok
> **Kullanılabilirlik:** Sınırlı kullanılabilirlik betası, hesap bazında etkinleştirilir. TikTok'u bağlamak, hesap bunun için etkinleştirilene kadar bir izin hatası döndürür.
TikTok İş Mesajlaşması, Meta gibi tam bir OAuth kanalıdır ancak yoklama tarafında daha basittir: Karşı tarafta oluşturulacak özel bir durum yoklama adımı yoktur, çünkü TikTok geri yönlendirme yapıp bağlantı yazıldığında bağlı hesap kendiliğinden görünür. Aşağıdaki durum uç noktası, bağlantı sırasında döngüye sokmanız gereken bir şey olarak değil, talep üzerine durumu doğrulamak (destek araçları, sağlık kontrolleri) için mevcuttur.
### Adım 1 - TikTok bağlantısını başlat
```
POST /channels/tiktok/connect
```
Kimlik bilgisi gerektirmez - hesap sahibi yetkilendirmeyi tamamen kendi tarayıcısında yapar.
```bash
curl -X POST "https://api.youraiconnector.com/v1/channels/tiktok/connect?apiKey=YOUR_API_KEY"
```
**Yanıt**
```json
{
"success": true,
"status": "pending_authorization",
"oauth_url": "https://www.tiktok.com/v2/auth/authorize?client_key=...&state=...",
"state_token": "opaque-one-time-token",
"expires_at": "2026-06-10T12:30:00.000Z"
}
```
Hesap sahibinin TikTok'a giriş yapıp erişimi onaylayabilmesi için `oauth_url` adresini tarayıcısında açın. Durum `expires_at` (yaklaşık 30 dakika) içinde sona erer - eğer süre aşılırsa baştan başlayın. TikTok için `connect_url` barındırılan sayfa kısayolu yoktur; `oauth_url` adresini kendiniz açmanız tek yoldur.
### TikTok durumunu kontrol et
```
GET /channels/tiktok/{openId}/status
```
`openId`, OAuth geri araması çalıştırıldıktan sonra bilinen TikTok İş Hesabının open_id'sidir.
```bash
curl "https://api.youraiconnector.com/v1/channels/tiktok/openIdFromTikTok/status" \
-H "X-API-Key: YOUR_API_KEY"
```
**Yanıt**
```json
{
"success": true,
"open_id": "openIdFromTikTok",
"channel": "tiktok",
"status": "connected",
"business_id": "openIdFromTikTok",
"username": "mybusiness",
"display_name": "My Business",
"avatar_url": "https://...",
"status_reason": null,
"is_active": true,
"live": false
}
```
TikTok'un ucuz bir canlı sağlık kontrolü yoktur, bu nedenle `live` burada her zaman `false` değerindedir - alanlar bağlantının (veya son belirteç yenilemesinin) yazdıklarını yansıtır. `status_reason` ayarlı `status: "reauth_required"`, hesabın tekrar bağlantı sürecinden geçmesi gerektiği anlamına gelir; TikTok belirteçleri yıllık rotasyonla otomatik olarak yenilenir ve bu rotasyon başarısız olursa görünen durum budur.
### TikTok bağlantısını kes
```
DELETE /channels/tiktok/{openId}
```
```bash
curl -X DELETE "https://api.youraiconnector.com/v1/channels/tiktok/openIdFromTikTok" \
-H "X-API-Key: YOUR_API_KEY"
```
**Yanıt**
```json
{ "success": true, "status": "removed", "open_id": "openIdFromTikTok" }
```
---
## GoHighLevel
GoHighLevel (GHL) bir mesajlaşma kanalı değil, bir CRM entegrasyonudur - onu bağlamak plandaki bir kanal yuvasını tüketmez, çünkü yeni bir kanal eklemek yerine hesabın mevcut kanallarını kullanır. Ayrıca bu sayfadaki **aynı anda birden fazla bağlantıyı** tutabilen tek entegrasyondur: müşterinin uygulamayı yüklediği her GHL alt hesabı ("konum") kendi girişine sahip olur.
### Adım 1 - GHL bağlantısını başlat
```
POST /channels/ghl/connect
```
| Alan | Gerekli | Açıklama |
|---|---|---|
| `brand` | Hayır | Hangi GHL pazar yeri listelemesi üzerinden yetkilendirme yapılacağı. Varsayılan olarak standart listelemeyi kullanır - yalnızca dağıtımınızda birden fazla pazar yeri uygulaması yapılandırılmışsa geçerlidir. |
```bash
curl -X POST "https://api.youraiconnector.com/v1/channels/ghl/connect?apiKey=YOUR_API_KEY"
```
**Yanıt**
```json
{
"success": true,
"status": "pending_authorization",
"oauth_url": "https://marketplace.gohighlevel.com/oauth/chooselocation?client_id=...&state=...",
"state_token": "opaque-one-time-token",
"brand": "dmchamp",
"expires_at": "2026-06-10T12:30:00.000Z"
}
```
Hesap sahibinin bir GHL konumu seçip erişimi onaylayabilmesi için `oauth_url` öğesini tarayıcısında açın. Durum (state) `expires_at` tarihinde (yaklaşık 30 dakika sonra) sona erer.
### GHL bağlantılarını listele
```
GET /channels/ghl/status
```
Diğer kanallardan farklı olarak bu, tek bir bağlantının durumu değildir; hesabın bağladığı her konumu listeler.
```bash
curl "https://api.youraiconnector.com/v1/channels/ghl/status" \
-H "X-API-Key: YOUR_API_KEY"
```
**Yanıt**
```json
{
"success": true,
"connections": [
{
"location_id": "abc123location",
"company_id": "xyz789company",
"brand": "dmchamp",
"status": "connected",
"status_reason": null,
"scopes": ["conversations.readonly", "conversations.write", "conversations/message.write"],
"connected_at": "2026-06-01T10:00:00.000Z",
"conversation_provider_id": "provider-id-in-ghl",
"trigger_subscriptions": [
{ "id": "sub_1", "key": "InboundMessage", "workflow_id": "wf_123" }
]
}
]
}
```
### Bir GHL konumunun bağlantısını kes
```
DELETE /channels/ghl/{locationId}
```
Buradaki bağlantıyı siler, bu da o konum için tüm eşitlemeleri ve tetikleyicileri durdurur. Bu işlem, uygulamayı GHL tarafında kaldırmaz; müşteri bunu da isterse GHL pazar yeri yüklemelerinden kendisi kaldırmalıdır.
```bash
curl -X DELETE "https://api.youraiconnector.com/v1/channels/ghl/abc123location" \
-H "X-API-Key: YOUR_API_KEY"
```
**Yanıt**
```json
{ "success": true, "status": "disconnected", "location_id": "abc123location" }
```
---
## Telefon numaraları (satın alma ve bırakma)
Mevcut bir numarayı bağlamak yerine, doğrudan WhatsApp uyumlu yeni bir numara satın alabilirsiniz. Kullanılabilir numaraları arayın, bir tane satın alın ve ardından sağlama işlemi tamamlanana kadar sorgulayın.
::: note
**Not:** Buradan satın alınan numaralar WhatsApp uyumludur. WhatsApp gönderici kaydı satın alma işleminden sonra arka planda çalışır, bu nedenle gönderim yapmadan önce durumun `ONLINE` değerine ulaşmasını beklemeniz gerekir. Krediler satın alma sırasında düşülür ve numarayı bıraktığınızda **iade edilmez**.
:::
### Adım 1 - Kullanılabilir numaraları ara
```
GET /phone-numbers/available?country_code=ISO2
```
**cURL**
```bash
curl "https://api.youraiconnector.com/v1/phone-numbers/available?country_code=US&apiKey=YOUR_API_KEY"
```
**JavaScript**
```javascript
const res = await fetch(
"https://api.youraiconnector.com/v1/phone-numbers/available?country_code=US",
{ headers: { "X-API-Key": "YOUR_API_KEY" } }
);
const data = await res.json();
```
**Python**
```python
res = requests.get(
"https://api.youraiconnector.com/v1/phone-numbers/available",
params={"country_code": "US"},
headers={"X-API-Key": "YOUR_API_KEY"},
)
data = res.json()
```
| Sorgu parametresi | Gerekli | Açıklama |
|---|---|---|
| `country_code` | Evet | İçinde arama yapılacak ISO 3166-1 alpha-2 ülke kodu (örneğin `US`, `GB`, `NL`). |
| `type` | Hayır | Tercih edilen numara sınıfı, `local` veya `mobile`. Her iki sınıf da döndürülebilir. |
**Yanıt**
```json
{
"success": true,
"phone_numbers": [
{
"phone_number": "+14155551234",
"purchase_credits": 50,
"monthly_credits": 50,
"cost_usd": 1.15
}
]
}
```
Her sonuç tek seferlik `purchase_credits` ve yinelenen `monthly_credits` değerini gösterir. Platform tarafından sağlanan bir numara ayda en az 50 krediye mal olur ve taşıyıcının kendi aylık fiyatına göre artar; satın alma sırasında ve her yenilemede ücretlendirilir. Aramanın döndürdüğü `purchase_credits` / `monthly_credits` değerini alıntılayın; asla kendiniz bir fiyat türetmeyin. Yeni bir hesapta yapılan ilk arama bazı temel kaynakları hazırlar, bu nedenle sonraki aramalardan biraz daha yavaş olabilir.
### Adım 2 - Bir numara satın alın
```
POST /phone-numbers
```
Arama sonuçlarından bir `phone_number` kullanın.
**cURL**
```bash
curl -X POST "https://api.youraiconnector.com/v1/phone-numbers" \
-H "X-API-Key: YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"phone_number": "+14155551234",
"country_code": "US",
"display_name": "Support line"
}'
```
**JavaScript**
```javascript
const res = await fetch("https://api.youraiconnector.com/v1/phone-numbers", {
method: "POST",
headers: {
"X-API-Key": "YOUR_API_KEY",
"Content-Type": "application/json",
},
body: JSON.stringify({
phone_number: "+14155551234",
country_code: "US",
display_name: "Support line",
}),
});
const data = await res.json();
```
**Python**
```python
res = requests.post(
"https://api.youraiconnector.com/v1/phone-numbers",
headers={"X-API-Key": "YOUR_API_KEY"},
json={
"phone_number": "+14155551234",
"country_code": "US",
"display_name": "Support line",
},
)
data = res.json()
```
| Alan | Zorunlu | Açıklama |
|---|---|---|
| `phone_number` | Evet | Kullanılabilir numaralar aramasından dönen, E.164 formatındaki bir numara. |
| `country_code` | Evet | ISO 3166-1 alpha-2 ülke kodu (örneğin `US`). |
| `display_name` | Hayır | Kolay hatırlanabilir bir etiket. Varsayılan olarak telefon numarasıdır. |
| `category` | Hayır | İsteğe bağlı kategori etiketi. |
**Yanıt**
```json
{
"success": true,
"phone_number": "+14155551234",
"channel": "whatsapp",
"whatsapp_status": "PURCHASED",
"outgoing_status": "PURCHASED",
"status": "PURCHASED",
"purchase_credits": 50,
"monthly_credits": 50
}
```
Numara `PURCHASED` durumunda başlar. WhatsApp kaydı daha sonra arka planda devam eder: `PURCHASED` -> `PENDING` -> `ONLINE`.
> Satın alma işlemi, bir iş adresi eksik olduğu veya başka bir gerekli ayrıntı ayarlanmadığı için başarısız olursa, açıklayıcı bir `error` içeren bir `400` alırsınız. Eksik ayrıntıyı ayarlayın ve tekrar deneyin.
### Adım 3 - ONLINE durumuna gelene kadar sorgulayın
```
GET /phone-numbers/{phoneNumber}/status
```
Bu, paylaşılan telefon numarası durum uç noktasıdır; satın alınan WhatsApp numaralarının yanı sıra diğer bağlı numaralarınız için de çalışır.
**cURL**
```bash
curl "https://api.youraiconnector.com/v1/phone-numbers/+14155551234/status" \
-H "X-API-Key: YOUR_API_KEY"
```
**JavaScript**
```javascript
const phone = encodeURIComponent("+14155551234");
const res = await fetch(
`https://api.youraiconnector.com/v1/phone-numbers/${phone}/status`,
{ headers: { "X-API-Key": "YOUR_API_KEY" } }
);
const data = await res.json();
// Poll until data.status === "ONLINE".
```
**Python**
```python
import urllib.parse
phone = urllib.parse.quote("+14155551234")
res = requests.get(
f"https://api.youraiconnector.com/v1/phone-numbers/{phone}/status",
headers={"X-API-Key": "YOUR_API_KEY"},
)
data = res.json()
# Poll until data["status"] == "ONLINE".
```
**Yanıt**
```json
{
"success": true,
"phone_number": "+14155551234",
"channel": "whatsapp",
"status": "ONLINE",
"status_reason": null,
"live": true
}
```
### Adım 4 - Bir numarayı serbest bırakın
```
DELETE /phone-numbers/{phoneNumber}
```
```bash
curl -X DELETE "https://api.youraiconnector.com/v1/phone-numbers/+14155551234" \
-H "X-API-Key: YOUR_API_KEY"
```
**Yanıt**
```json
{ "success": true, "phone_number": "+14155551234", "released": true }
```
Bunun ne yaptığı, numaranın kime ait olduğuna bağlıdır.
**Platform üzerinden kiralanan** bir numara için bu gerçek bir serbest bırakmadır: WhatsApp göndericisi kaydı silinir, numara operatöre iade edilir ve hesaptan kaldırılır; numaranın kimse tarafından yeniden satın alınamayacağı 7 günlük bir bekleme süresi uygulanır ve hiçbir kredi iadesi yapılmaz.
**Hesabın kendisine ait** (kendi Twilio hesabı, kendi Meta uygulaması veya WhatsApp İşletme Hesabı ya da bir Android SMS ağ geçidi) bir numara için, aynı çağrı onu yalnızca hesaptan kaldırır. Yukarı akış sağlayıcısında hiçbir şey serbest bırakılmaz ve herhangi bir soğuma süresi yazılmaz, bu nedenle numara hemen yeniden bağlanabilir. Varsa, WhatsApp gönderen kaydı korunabilir veya korunmayabilir: sökme işlemi, hesabın platform tarafından yönetilen Twilio kimlik bilgilerini kullanarak göndereni silmeye çalışır. Yönetilen kurulumdaki bir hesapta bu kimlik bilgileri geçerlidir ve gönderen silinir, bu nedenle yeniden bağlanmak, onu tekrar kaydettirmek anlamına gelir. Kendi Twilio'suna geçmiş bir hesapta ise silme işlemi kimlik doğrulaması yapamaz ve gönderen o hesapta kayıtlı kalır; bu durumda yeniden bağlanmak, mevcut göndereni tekrar eklemekten ibarettir.
### Hâlihazırda sahip olduğunuz bir numarayı ekleyin (BYO)
```
POST /phone-numbers/byo
```
Yukarıdaki arama ve satın alma akışını tamamen atlar. Bunu, hesap sahibi platform üzerinden numara kiralamak yerine kendi numarasını (kendi Twilio'su, kendi Meta WhatsApp İşletme Hesabı veya bir Android SMS ağ geçidi) getirdiğinde kullanın. Bu işlem yalnızca numarayı kaydeder; herhangi bir kredi ücreti alınmaz ve burada sağlayıcı ile hiçbir şey tedarik edilmez. Numara, hesap sahibi üzerinde bir Gönderici kaydetmek için WhatsApp OAuth işlemini tamamlayana kadar (kontrol panelindeki "Kendi numaranı getir" düğmesinin başlattığı akışın aynısı) etkin kalmaz.
| Alan | Gerekli | Açıklama |
|---|---|---|
| `phone_number` | Evet | E.164 formatında eklenecek numara (örneğin `+14155551234`). |
| `country_code` | Evet | ISO 3166-1 alpha-2 ülke kodu (örneğin `US`). |
| `display_name` | Hayır | Kolay bir etiket. Varsayılan olarak telefon numarasıdır. |
| `category` | Hayır | İsteğe bağlı kategori etiketi. |
```bash
curl -X POST "https://api.youraiconnector.com/v1/phone-numbers/byo?apiKey=YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"phone_number": "+14155551234",
"country_code": "US",
"display_name": "Support line"
}'
```
**Yanıt** (`201 Created`):
```json
{
"success": true,
"phone_number": "+14155551234",
"channel": "whatsapp",
"type": "BYO",
"whatsapp_status": "ADDED",
"outgoing_status": "ADDED",
"is_active": false
}
```
Gerçek bir E.164 numarası olmayan (veya gerçek müşterilere asla mesaj gönderemeyen Meta'nın WhatsApp test numarasına benzeyen) bir `phone_number`, `400` döndürür. Hesapta zaten var olan bir numarayı eklemek - Meksika'nın `+52` ve `+521` biçimleri gibi biraz farklı yazılmış olsa bile - yinelenen bir satır oluşturmak yerine `409` döndürür.
### Bir numarayı birincil olarak ayarla
```
POST /phone-numbers/{phoneNumber}/set-primary
```
Bir numarayı `is_active: true`, hesaptaki diğer tüm numaraları ise `is_active: false` durumuna atomik olarak getirir; hesap hiçbir zaman istek sırasında iki aktif numarayla veya hiç numarasız kalmaz. `is_active`, genel güncelleme uç noktası üzerinden kasıtlı olarak ayarlanamaz; bu özel çağrı, hangi numaranın birincil olacağını değiştirmenin tek yoludur.
```bash
curl -X POST "https://api.youraiconnector.com/v1/phone-numbers/+14155551234/set-primary" \
-H "X-API-Key: YOUR_API_KEY"
```
**Yanıt**
```json
{
"success": true,
"phone_number": {
"id": "+14155551234",
"phone_number": "+14155551234",
"display_name": "Support line",
"channel": "whatsapp",
"is_active": true,
"whatsapp_status": "ONLINE"
}
}
```
Buradaki `phone_number`, yalnızca dize değil, tam numara nesnesidir (`GET /phone-numbers` öğesinin döndürdüğü şeklin aynısı). Hesapta olmayan bir `phoneNumber`, `404` döndürür.
### Bir numaranın kaydını sil (serbest bırakmadan)
```
DELETE /phone-numbers/{phoneNumber}/record
```
Bu hesaptaki numara kaydının basit bir şekilde silinmesidir; sağlayıcı tarafında bir serbest bırakma veya kayıttan silme işlemi yapılmaz ve yukarıdaki serbest bırakma adımındaki gibi 7 günlük bir bekleme süresi uygulanmaz. Bunu, yönetilen serbest bırakma akışına girmeden BYO, WhatsApp Web, Telegram veya LINE kayıtlarını ya da eski bir girişi temizlemek için kullanın. Bir serbest bırakma işleminin aksine, hesapta olmayan bir numarayı silmek sessiz bir başarı değil, bir `404` döndürür.
```bash
curl -X DELETE "https://api.youraiconnector.com/v1/phone-numbers/+14155551234/record" \
-H "X-API-Key: YOUR_API_KEY"
```
**Yanıt**
```json
{ "success": true, "phone_number": "+14155551234", "deleted": true }
```
---
## Bir kanalı kampanyaya yönlendirme
Bir kanal bağlamak mesajları hesaba **alır**. Mesajları **hangi Yapay Zeka Temsilcisinin yanıtlayacağına** karar vermez.
Yönlendirme, kampanyalar tarafından değil, bir Yapay Zeka Temsilcisi üzerindeki **Giriş Noktaları** tarafından yönetilir. Her kanalın, o kanaldaki yeni ve bilinmeyen kişileri yanıtlayacak Temsilciyi belirten bir kanal varsayılan Giriş Noktası vardır:
| Ne yapmak istiyorsunuz | Çağrı |
|---|---|
| Bir kanalı, onu yanıtlaması gereken Temsilciye yönlendirin | `{ "channel": "instagram", "agent_id": "AGENT_ID" }` gövdeli `PUT /entry-points/channel-defaults` |
| Giriş Noktaları kademesinin hesap için canlı olup olmadığını kontrol edin | Giriş Noktaları o hesabın yönlendirmesine karar verdiğinde `{ "success": true, "cutover_enabled": true }` döndüren `GET /entry-points/routing-status` |
| Bir kanalı yanıtlayan Temsilci olmadan bırakın | `DELETE /entry-points/channel-defaults?channel=instagram` |
Bir kanalın bir Giriş Noktası (Entry Point) olana kadar, daha önce hiç konuşmadığınız birinden gelen ilk mesaj yine de saklanır, ancak hiçbir şey bunu almaz ve hiçbir asistan yanıt vermez. Bu, çoğu entegrasyonun gözden kaçırdığı adımdır: Instagram'ı bağlamak ve bir Temsilci oluşturmak tek başına yeterli değildir; ayrıca kanalı Temsilciye yönlendirmeniz gerekir. WhatsApp numarası başına bir Temsilci, anahtar kelime ve yorum kuralları dahil olmak üzere çağrıların tam seti [Giriş Noktaları API](entry-points.md) içindedir.
`POST /channels/campaign` hala aşağıda belgelenen eski kanal bazlı kampanya yönlendirme haritasını yazar, ancak bu haritaya artık hiçbir hesapta gelen yönlendirme için başvurulmaz; yalnızca geri alma için tutulur. Bunun üzerine inşa etmeyin.
### Bir veya daha fazla kanalı yönlendir (eski kampanya yönlendirme haritası)
`POST /channels/campaign`
**İstek alanları**
| Alan | Gerekli | Açıklama |
|---|---|---|
| `campaign_id` | Evet | Bu kanallardaki yeni kişileri yanıtlaması gereken kampanya. Hesaba ait olmalıdır. |
| `channels` | Evet | Yönlendirilecek kanallardan oluşan boş olmayan bir dizi. İzin verilenler: `whatsapp`, `whatsapp_web`, `telegram`, `instagram`, `messenger`, `chat_widget`, `custom_channel`, `sms`, `email`. |
Yönlendirme yuvası ve kampanyanın `enabled_channels` listesi tek bir atomik işlemde birlikte güncellenir, böylece asla birbirinden kopmazlar. Farklı bir kampanyaya zaten yönlendirilmiş bir kanal, basitçe buna yeniden yönlendirilir.
**cURL**
```bash
curl -X POST "https://api.youraiconnector.com/v1/channels/campaign?apiKey=YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"campaign_id": "NBCXrhqGPSFsd6MV7pRo",
"channels": ["instagram", "messenger"]
}'
```
**JavaScript**
```javascript
const res = await fetch("https://api.youraiconnector.com/v1/channels/campaign", {
method: "POST",
headers: {
"X-API-Key": "YOUR_API_KEY",
"Content-Type": "application/json",
},
body: JSON.stringify({
campaign_id: "NBCXrhqGPSFsd6MV7pRo",
channels: ["instagram", "messenger"],
}),
});
const data = await res.json();
```
**Python**
```python
import requests
res = requests.post(
"https://api.youraiconnector.com/v1/channels/campaign",
headers={"X-API-Key": "YOUR_API_KEY"},
json={
"campaign_id": "NBCXrhqGPSFsd6MV7pRo",
"channels": ["instagram", "messenger"],
},
)
data = res.json()
```
**Yanıt**
```json
{
"success": true,
"campaign_id": "NBCXrhqGPSFsd6MV7pRo",
"channels": ["instagram", "messenger"]
}
```
### Yönlendirmenin gerçekten tetiklenmesi için neyin doğru olması gerekir
Hala eski kampanya yönlendirme haritasını okuyan bir hesapta, yönlendirme bir API çağrısı olarak başarılı olur ancak kampanyadaki üç şey gerçek bir gelen mesajın yanıtlanıp yanıtlanmayacağına karar verir. Yönlendirilen bir kanal sessiz kaldığında üçünü de kontrol edin.
| Gereksinim | Aksi takdirde ne olur |
|---|---|
| `type`, `Incoming from Unknown Contacts` veya `Combined` değerindedir | İstek `400` ile reddedilir. Giden ve Anahtar Kelime kampanyaları bir yönlendirme yuvası tutamaz. |
| `status`, `Live` değerindedir | Yönlendirme saklanır ancak hiçbir şeyi almaz. Bir `Draft` kampanyası, "Yönlendirdim ve hiçbir şey olmuyor" sorununun en yaygın nedenidir. |
| `ai_mode`, `true` değerindedir | Kişi oluşturulur ve mesaj saklanır, ancak asistan asla yanıt vermez. |
Anahtar kelime eşleştirme artık Giriş Noktalarında yer alıyor — yanıtlaması gereken Yapay Zeka Temsilcisi üzerinde `keyword` türünde bir Giriş Noktası oluşturun.
### Kanal başına bir kampanya
Her kanal tam olarak bir eski yönlendirme yuvasına sahiptir. Aynı kanala ikinci bir kampanya yönlendirmek, yuvayı sessizce yeniden işaretler ve `200` döndürür — çakışma hatası yoktur. Önceki kampanya zaten sahip olduğu kişileri işlemeye devam eder; sadece yenilerini almayı durdurur.
### Bir kanalın yönlendirmesini temizle
`DELETE /channels/campaign/{channel}`
Tek bir kanalın yönlendirmesini, o an hangi kampanyaya işaret ettiğine bakılmaksızın kaldırır ve kanalı o kampanyanın `enabled_channels` öğesinden çıkarır. Kanal üzerindeki yeni bilinmeyen kişiler artık hiçbir kampanya tarafından alınmaz. Kampanyada halihazırda bulunan kişiler ise daha önceki gibi devam eder.
```bash
curl -X DELETE "https://api.youraiconnector.com/v1/channels/campaign/instagram?apiKey=YOUR_API_KEY"
```
**Yanıt**
```json
{
"success": true,
"channel": "instagram",
"cleared": true,
"campaign_id": "NBCXrhqGPSFsd6MV7pRo"
}
```
İşlem eşdeğerdir (idempotent): daha önce hiç yönlendirilmemiş bir kanalın temizlenmesi de `200`, `cleared: false` ve `campaign_id: null` ile birlikte döner. Bu uç nokta, planda **gelen kampanyalar** özelliğinin etkin olmasını gerektirir; aksi takdirde `403` alırsınız.
---
## Kendi Meta uygulamanızı kullanın (Instagram + Messenger)
Varsayılan olarak Instagram + Messenger bağlantısı platformun Meta uygulaması üzerinden çalışır, bu nedenle hesap sahibi Facebook onay ekranında bu uygulamanın adını görür. Onay ekranında **sizin** markanızın görünmesini isterseniz, kendi Meta uygulamanızı kaydedebilir ve tüm akışı bu uygulama üzerinden yönlendirebilirsiniz. Yapılandırıldıktan sonra bu, hesabınız için geçerli olur; yukarıdaki bağlantı çağrılarında markalama dışında hiçbir şey değişmez.
> **Bu yalnızca Instagram + Messenger için geçerlidir.** WhatsApp, WhatsApp Web, Telegram ve LINE bağlantıları özel bir Meta uygulamasından etkilenmez.
### Uygulamanızın öncelikle nelere ihtiyacı var
Bu kısım zaman alan ve tamamen Meta tarafında gerçekleşen bölümdür:
1. **Bir uygulama:** İşletme türünde, Messenger ve Instagram ürünleri eklenmiş.
2. **Gelişmiş Erişim** (Meta Uygulama İncelemesi aracılığıyla): `pages_show_list`, `pages_messaging`, `pages_manage_metadata`, `pages_read_engagement`, `instagram_basic`, `instagram_manage_messages` için. Gelişmiş Erişim olmadan, yalnızca uygulamanızda bir role sahip kişiler bağlantıyı tamamlayabilir; müşterilerinizin bağlantıları başarısız olur. Uygulama İncelemesi genellikle birkaç hafta sürer ve İşletme Doğrulaması gerektirir.
3. **İşletme için Facebook Girişi yapılandırması:** Uygulamanızın içinde oluşturulmuş ve aynı izinleri veren. Sayısal yapılandırma kimliği uygulama bazlıdır, bu nedenle kendinizinkini oluşturmalısınız.
Uygulamanızda gerekli izinlerden herhangi biri eksikse, bağlantı sırasında neyin eksik olduğunu belirten net bir hata ile ( `/status` anketinde `byo_app_missing_permissions` olarak görünür) bağlantı başarısız olur; çalışıyor gibi görünüp ilk mesajda hata vermesinden daha iyidir.
### Adım 1 - Uygulamanızı kaydedin
`PUT /account-config/meta-app`
| Alan | Gerekli | Açıklama |
|---|---|---|
| `app_id` | Evet | Meta Uygulama Kimliğiniz (Ayarlar → Temel). |
| `app_secret` | Evet | Meta Uygulama Gizli Anahtarınız. Saklanmadan önce Meta nezdinde doğrulanır, ardından şifrelenir. Hiçbir uç nokta tarafından geri döndürülmez. |
| `config_id` | Evet | Uygulamanızdaki İşletme için Facebook Girişi yapılandırmasının sayısal kimliği. |
Facebook Giriş akışı için üçü de gereklidir. Aşağıda açıklanan yalnızca Instagram Giriş token-push yolunu çalıştırıyorsanız, bunları tamamen dışarıda bırakabilirsiniz.
```bash
curl -X PUT "https://api.youraiconnector.com/v1/account-config/meta-app?apiKey=YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"app_id": "1234567890123456",
"app_secret": "your-app-secret",
"config_id": "9876543210987654"
}'
```
**Yanıt**
```json
{
"success": true,
"app_id": "1234567890123456",
"config_id": "9876543210987654",
"verify_token": "1f4c…a9",
"webhook_urls": {
"instagram": "https://api.youraiconnector.com/v1/incoming-instagram-message/byo/YOUR_ACCOUNT_ID",
"messenger": "https://api.youraiconnector.com/v1/incoming-messenger-message/byo/YOUR_ACCOUNT_ID"
}
}
```
### Adım 2 - Uygulamanızı bizimle konuşacak şekilde yapılandırın
Meta uygulamanızın kontrol panelinde:
1. **Web kancaları (Webhooks)** - hem Instagram hem de Messenger ürünleri için Geri Arama URL'sini (Callback URL) yanıttaki eşleşen `webhook_urls` değeriyle, Doğrulama belirtecini (Verify token) ise `verify_token` ile ayarlayın. `messages`, `messaging_postbacks` ve `comments` alanlarına abone olun.
2. **Geçerli OAuth Yönlendirme URI'leri** - onay akışının geri dönebilmesi için `https://api.youraiconnector.com/v1/auth-meta-callback-handler` ekleyin.
`GET /account-config/meta-app` her zaman aynı kurulum materyalini döndürür; `DELETE /account-config/meta-app` uygulamayı kaldırır (gelecekteki bağlantılar platform uygulamasına geri döner; ayrıca uygulamanızdaki web kancası aboneliğini de kaldırın).
### 3. Adım - Her zamanki gibi bağlanın
Başka hiçbir şey değişmez. `POST /channels/meta/connect` (ve barındırılan `connect_url` sayfası) hesabınız için otomatik olarak uygulamanızı kullanır; yanıtın `uses_byo_meta_app: true` kısmı, onay ekranının hangi uygulamayı göstereceğini doğrular. Mesaj gönderme, sayfa seçimi ve bağlantı kesme işlemleri aynı şekilde çalışır.
## Kendi Instagram Giriş uygulamanızı getirin (token gönderimi)
Yukarıdaki bölüm, hesabın bir Facebook Sayfası aracılığıyla bağlandığı Facebook Girişi akışını kapsamaktadır. Meta ayrıca **Instagram Girişi ile Instagram API** (Instagram için İşletme Girişi) seçeneğini de sunar: hesap sahibi doğrudan Instagram üzerinde kimlik doğrulaması yapar, herhangi bir Facebook hesabı veya Sayfası gerekmez.
Platformunuz halihazırda bu ürüne sahip kendi Meta uygulamasını çalıştırıyorsa, bizim tarafımızda herhangi bir OAuth akışına ihtiyacınız yoktur. Müşterileriniz **sizin** uygulamanızı yetkilendirir ve siz de hesap başına tamamlanmış kimlik bilgilerini bize gönderirsiniz:
1. Instagram uygulamanızın kimlik bilgilerini bir kez kaydedersiniz (böylece webhook'larınızı doğrulayabiliriz).
2. Hesap başına, Instagram profesyonel hesap kimliğini + uygulamanızın elde ettiği uzun ömürlü Instagram kullanıcı token'ını gönderirsiniz.
3. Uygulamanızın Instagram mesajlaşma webhook'unu bize yönlendirirsiniz. Hiç göndermediğiniz hesaplara ait etkinlikler onaylanır ancak göz ardı edilir.
4. Token yaşam döngüsü size aittir: token'ları kendi sisteminizde yenileyin ve her yenilenen token'ı aynı çağrıyla bize gönderin. Gönderilen bir token'ı asla biz yenilemeyiz.
### Uygulamanızın öncelikle nelere ihtiyacı var
- Meta uygulamanıza eklenmiş **Instagram** ürünü ("Instagram girişi ile API kurulumu"). Bu ürünün, Facebook Uygulama Kimliği/Gizli Anahtarı'ndan ayrı, **kendi Uygulama Kimliği ve Uygulama Gizli Anahtarı çifti** vardır; bunları ürünün kurulum panelinde bulabilirsiniz.
- `instagram_business_basic` ve `instagram_business_manage_messages` için **Gelişmiş Erişim** (Meta Uygulama İncelemesi aracılığıyla) (yorum otomasyonları kullanıyorsanız `instagram_business_manage_comments` ekleyin). Bu olmadan, yalnızca uygulamanızda rolü olan kişiler uygulamayı yetkilendirebilir.
### Adım 1 - Instagram uygulama kimlik bilgilerinizi kaydedin
Yukarıdakiyle aynı uç nokta — Instagram çiftini `PUT /account-config/meta-app` adresine gönderin. Facebook alanları bu yol için gerekli değildir: Yalnızca Instagram Girişi çalıştırıyorsanız çifti tek başına, her ikisini de çalıştırıyorsanız Facebook alanlarıyla birlikte gönderin. Bir kaydetme işlemi her zaman tüm ayarı tanımlar, bu nedenle hangi seti dışarıda bırakırsanız o kaldırılır.
| Alan | Zorunlu | Açıklama |
|---|---|---|
| `instagram_app_id` | Birlikte | Instagram ürününün kendi sayısal Uygulama Kimliği (Facebook Uygulama Kimliği değil). |
| `instagram_app_secret` | Birlikte | Instagram ürününün kendi Uygulama Gizli Anahtarı. Dinlenme halindeyken şifrelenir, asla geri döndürülmez. |
```bash
curl -X PUT "https://api.youraiconnector.com/v1/account-config/meta-app?apiKey=YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"instagram_app_id": "1122334455667788",
"instagram_app_secret": "your-instagram-app-secret"
}'
```
**Yanıt** — Instagram Giriş webhook URL'sini taşır (`instagram` ve `messenger` URL'leri yalnızca Facebook alanları da saklandığında görünür):
```json
{
"success": true,
"instagram_app_id": "1122334455667788",
"verify_token": "1f4c…a9",
"webhook_urls": {
"instagram_login": "https://api.youraiconnector.com/v1/incoming-instagram-login-message/byo/YOUR_ACCOUNT_ID"
}
}
```
Uygulamanızın Instagram ürününe ait **Webhooks** panelinde, Geri Arama URL'sini (Callback URL) `webhook_urls.instagram_login`, Doğrulama token'ını (Verify token) `verify_token` olarak ayarlayın ve `messages` ile `comments` alanlarına abone olun.
### Adım 2 - Hesap başına bir token gönderin
`PUT /channels/instagram-login/token`
Diğer tüm rotalar gibi `sub_account_id` ile çalışır, bu nedenle bir ajans anahtarı tüm filosunu sağlayabilir.
| Alan | Zorunlu | Açıklama |
|---|---|---|
| `ig_user_id` | Evet | **Instagram profesyonel hesap kimliği** — `GET https://graph.instagram.com/v21.0/me?fields=user_id,username` içindeki `user_id` alanı. Bu, Instagram webhook'larının `entry.id` olarak taşıdığı kimlikle aynıdır. ⚠️ Bu, `/me` içindeki `id` alanı **değildir** — o alan uygulama kapsamlıdır ve her Meta uygulamasına göre değişir. Uygulama kapsamlı kimliği göndermek, hatayı belirten bir `400` döndürür. |
| `access_token` | Evet | Uygulamanızın o hesap için elde ettiği uzun ömürlü Instagram kullanıcı token'ı. Saklanmadan önce Instagram'a karşı canlı olarak doğrulanır: token çalışmalı ve `ig_user_id`'e ait olmalıdır. |
| `expires_at` | Hayır | Token'ın ISO-8601 formatında son kullanma tarihi. Alternatif olarak `expires_in` (saniye) gönderin. Varsayılan olarak 60 gündür. |
| `username` | Hayır | Hesabın @kullanıcıadı; bunu zaten Instagram'dan okuyoruz. |
```bash
curl -X PUT "https://api.youraiconnector.com/v1/channels/instagram-login/token?apiKey=YOUR_AGENCY_KEY&sub_account_id=CLIENT_ID" \
-H "Content-Type: application/json" \
-d '{
"ig_user_id": "17841400000000000",
"access_token": "IGAAR…",
"expires_at": "2026-11-01T00:00:00Z"
}'
```
**Yanıt**
```json
{
"success": true,
"ig_user_id": "17841400000000000",
"username": "acme.studio",
"expires_at": "2026-11-01T00:00:00.000Z",
"webhook_url": "https://api.youraiconnector.com/v1/incoming-instagram-login-message/byo/YOUR_ACCOUNT_ID"
}
```
Gönderim işleminin bir parçası olarak, uygulamanızı o hesabın webhook'larına abone yaparız (`subscribed_apps`, gönderilen token ile), böylece mesajlar sizin tarafınızdan ekstra bir çağrıya gerek kalmadan akmaya başlar.
**Yenileme** - yenilenen belirteci aynı `ig_user_id` ile aynı uç noktaya gönderin; depolanan belirteci ve son kullanma tarihini yerinde günceller.
**Çakışmalar** - bir Instagram hesabı asla iki bağlantıda aynı anda aktif olamaz. Hesap başka bir yerde veya bu hesapta Facebook Sayfası akışı üzerinden zaten bağlıysa, gönderim işlemi önce hangi bağlantının kesilmesi gerektiğini belirten bir `409` döndürür. Facebook akışı bağlantısı asla otomatik olarak değiştirilmez, çünkü Messenger'a da hizmet veriyor olabilir.
### Adım 3 - Bir istemci ayrıldığında bağlantıyı kesin
`DELETE /channels/instagram-login/token` (aynı kimlik doğrulama ve `sub_account_id`) web kancalarının aboneliğini en iyi çabayla iptal eder ve depolanan kimlik bilgisini kaldırır. Belirteç zaten geçersiz olsa bile her zaman başarılı olur — ve kimlik bilgisi kaldırıldığında, o hesabın web kancası olayları yoksayılır.
---
## Güvenilir bir sarmalayıcı (wrapper) oluşturmak için ipuçları
- **Nazikçe yoklayın.** Birkaç saniyede bir yeterlidir. Terminal durumuna (`connected` / `ONLINE` veya bir hata durumu) ulaştığınızda durun ve döngüye makul bir genel zaman aşımı koyun (tarayıcı/QR adımlarının süresi dolar, her `expires_at`'ye bakın).
- **Yoldaki telefon numaralarını URL ile kodlayın.** Baştaki `+`, `%2B` olarak gönderilmelidir. Uç noktalar çıplak rakamları da kurtarır, ancak kodlama güvenli varsayılandır.
- **Asla geri sır beklemeyin.** Erişim belirteçleri, kanal sırları ve sayfa belirteçleri kabul edilir veya saklanır ancak hiçbir yanıtta geri döndürülmez.
- **Kimlik doğrulama kapısını yönetin.** Bir `403`, API erişiminin planda olmadığı veya bağladığınız kanalın hesabın planına dahil olmadığı anlamına gelir. Bkz. [API Erişimi](../integrations/api-access.md).
- **Hız sınırına dikkat edin.** Kimliği doğrulanmış istekler dakikada 300 ile sınırlandırılmıştır; bir `429`, geri çekilip tekrar denemeniz gerektiği anlamına gelir. Bkz. [Kimlik Doğrulama](authentication.md).
## Sonraki adımlar
- [Kimlik Doğrulama](authentication.md) - kabul edilen dört kimlik doğrulama biçimi ve hata formatı.
- [API Erişimi](../integrations/api-access.md) - API anahtarınızı oluşturma ve yönetme.