Kampanyalar API’si #

Bir kampanya, yapay zeka botunun kişilerinizle konuşması için ihtiyaç duyduğu her şeyi bir araya getirir: talimatları, üzerinde çalıştığı kanallar, aktif saatleri ve takip davranışı. Kampanyalar API’si, kontrol paneli yerine kendi kodunuzdan kampanyaları listelemenize, oluşturmanıza, güncellemenize, çoğaltmanıza, etkinleştirmenize, arşivlemenize ve ince ayar yapmanıza olanak tanır.

Aşağıdaki tüm uç noktalar https://api.youraiconnector.com/v1 temel URL’sine göredir. Her isteğin kimliği doğrulanmalıdır; API anahtarınızı nasıl alacağınız ve ileteceğiniz hakkında bilgi için API Erişimi ve Kimlik Doğrulama bölümlerine bakın. API erişimi ücretli bir özelliktir; bu özellik olmadan istekler 403 ile reddedilir.

Dikkat: Bazı örnekler basit ?apiKey=YOUR_API_KEY sorgu biçimini, diğerleri ise X-API-Key başlığını kullanır. Her ikisi de her yerde çalışır; kurulumunuza hangisi uyuyorsa onu kullanın.

Kampanya türleri #

Bir kampanya oluşturduğunuzda şu türlerden birini seçmelisiniz:

Büyük/küçük harf duyarlılığı yoktur. type, status, booking_provider, first_response_mode, bot.anthropic_model ve bot.ai_speed her türlü büyük/küçük harf kullanımını kabul eder — "live", "Live" ve "LIVE" aynı şeydir — ve değer, kampanyayı okuduğunuzda geri dönen kanonik biçiminde saklanır. Tek istisna duraklatma çiftidir: "Paused" ve "paused" gerçekten farklı iki durumdur, bu nedenle "PAUSED" gibi belirsiz bir yazım, birini seçmenizi söyleyen bir 400 ile reddedilir.

İki duraklatma durumu #

Her ikisi de kampanyayı durdurur: gelen yönlendirme yalnızca durum tam olarak Live olduğunda çalışır. API’den duraklatmak için Paused, devam ettirmek için Live kullanın — küçük harfli çift, pano düğmesi için mevcuttur ve onun için çalışır durumda tutulur.

Bunların hiçbiri, yapay zeka bir konuşma içinde yanıt vermeyi bıraktığında olan şey değildir. Bu, kişi bazlı bir anahtardır, kişi üzerinde is_bot_active — bir insan devraldığında, kişi vazgeçtiğinde veya yapay zeka sohbeti sonlandırdığında ayarlanır. Kampanyanın kendi durumu etkilenmez ve içindeki diğer tüm konuşmalar çalışmaya devam eder. Bkz. bir kişi için yapay zekayı duraklatma veya devam ettirme.

Kampanya oluşturmak, bir kanalı kimin 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, yeni ve bilinmeyen kişileri yanıtlayan Temsilciyi adlandıran bir kanal varsayılan Giriş Noktası vardır: bunu PUT /entry-points/channel-defaults ile ayarlayın, hesap için kademenin canlı olup olmadığını GET /entry-points/routing-status ile kontrol edin, DELETE /entry-points/channel-defaults ile temizleyin. POST /channels/campaign hala 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şlemleri için tutulur. Buna göre geliştirme yapmayın. Her iki yüzeyin yan yana görünümü için Bir kanalı kampanyaya yönlendirme bölümüne bakın.

Kampanyaları listele #

GET /campaigns

Kampanyalarınızı en yeniden başlayarak döndürür. archived=true değerini iletmediğiniz sürece arşivlenmiş kampanyalar hariç tutulur.

Sorgu parametreleri

cURL

curl "https://api.youraiconnector.com/v1/campaigns?limit=20&apiKey=YOUR_API_KEY"

JavaScript

const res = await fetch("https://api.youraiconnector.com/v1/campaigns?limit=20", {
  headers: { "X-API-Key": "YOUR_API_KEY" },
});
const data = await res.json();
console.log(data.campaigns, data.next_cursor);

Python

import requests

res = requests.get(
    "https://api.youraiconnector.com/v1/campaigns",
    params={"limit": 20},
    headers={"X-API-Key": "YOUR_API_KEY"},
)
data = res.json()
print(data["campaigns"], data["next_cursor"])

Yanıt

{
  "success": true,
  "campaigns": [
    {
      "id": "NBCXrhqGPSFsd6MV7pRo",
      "name": "Inbound WhatsApp Leads",
      "type": "Incoming from Unknown Contacts",
      "status": "Live",
      "enabled": true,
      "archived": false,
      "created_at": 1700000000000,
      "ai_mode": true,
      "language": "en",
      "enabled_channels": ["whatsapp", "instagram"]
    }
  ],
  "next_cursor": "NBCXrhqGPSFsd6MV7pRo"
}

next_cursor, null olduğunda son sayfaya ulaşmışsınız demektir.

Bir kampanya al #

GET /campaigns/{campaignId}

Canlı bot yapılandırması (bot), takip ayarları, etkin kanallar ve tüm anahtar kelimeler dahil olmak üzere tam kampanya belgesini döndürür. Zaman damgaları epoch milisaniyesi olarak döner.

cURL

curl "https://api.youraiconnector.com/v1/campaigns/NBCXrhqGPSFsd6MV7pRo?apiKey=YOUR_API_KEY"

JavaScript

const res = await fetch(
  "https://api.youraiconnector.com/v1/campaigns/NBCXrhqGPSFsd6MV7pRo",
  { headers: { "X-API-Key": "YOUR_API_KEY" } }
);
const { campaign } = await res.json();

Python

import requests

res = requests.get(
    "https://api.youraiconnector.com/v1/campaigns/NBCXrhqGPSFsd6MV7pRo",
    headers={"X-API-Key": "YOUR_API_KEY"},
)
campaign = res.json()["campaign"]

Yanıt

{
  "success": true,
  "campaign": {
    "id": "NBCXrhqGPSFsd6MV7pRo",
    "name": "Inbound WhatsApp Leads",
    "type": "Incoming from Unknown Contacts",
    "status": "Live",
    "language": "en",
    "ai_mode": true,
    "enabled": true,
    "archived": false,
    "created_at": 1700000000000,
    "enabled_channels": ["whatsapp", "instagram"],
    "bot": {
      "instructions": "Greet warmly and ask about their goals.",
      "goal": "Book a discovery call.",
      "ai_speed": "balanced",
      "anthropic_model": "standard",
      "max_messages": 20
    }
  }
}

Bir kampanya oluştur #

POST /campaigns

Yeni bir kampanya oluşturur. name ve type zorunludur; diğer her şey isteğe bağlıdır. Aynı istekte başka herhangi bir kampanya alanını dahil edebilirsiniz — örneğin language, ai_mode veya tam bir bot yapılandırma nesnesi — ve bu, yeni kampanya ile birlikte kaydedilecektir. Sahibi ve oluşturulma zamanı otomatik olarak ayarlanır.

İstek alanları

cURL

curl -X POST "https://api.youraiconnector.com/v1/campaigns?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Spring Promo",
    "type": "Outgoing",
    "language": "en",
    "ai_mode": true,
    "bot": {
      "instructions": "Greet warmly and ask about their goals.",
      "goal": "Book a discovery call."
    }
  }'

JavaScript

const res = await fetch("https://api.youraiconnector.com/v1/campaigns", {
  method: "POST",
  headers: {
    "X-API-Key": "YOUR_API_KEY",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    name: "Spring Promo",
    type: "Outgoing",
    language: "en",
    ai_mode: true,
    bot: {
      instructions: "Greet warmly and ask about their goals.",
      goal: "Book a discovery call.",
    },
  }),
});
const { campaign_id } = await res.json();

Python

import requests

res = requests.post(
    "https://api.youraiconnector.com/v1/campaigns",
    headers={"X-API-Key": "YOUR_API_KEY"},
    json={
        "name": "Spring Promo",
        "type": "Outgoing",
        "language": "en",
        "ai_mode": True,
        "bot": {
            "instructions": "Greet warmly and ask about their goals.",
            "goal": "Book a discovery call.",
        },
    },
)
campaign_id = res.json()["campaign_id"]

Yanıt

{
  "success": true,
  "campaign_id": "NBCXrhqGPSFsd6MV7pRo"
}

Bir kampanyayı güncelle #

PUT /campaigns/{campaignId}

Bir kampanyayı kısmen günceller — yalnızca değiştirmek istediğiniz alanları gönderin. Bu tek genel güncelleme fiilidir; PATCH /campaigns/{campaignId} yoktur (iki PATCH rotası, dar etkinleştir ve arşivle geçişleridir).

Hangi alanları değiştirebilirsiniz. Kampanya düzenleyicinin yazdığı her şey; name, status, type, language, ai_mode, enabled_channels, tetikleyici ve damla ayarları, rezervasyon ve takip bayrakları, Instagram/Facebook izleme alanları ve tüm bot yapılandırması dahil. Kimlik ve sahiplik, kampanyanın ömrü boyunca kilitlidir: user, id ve created_at reddedilir, uç noktanın tanımadığı herhangi bir alan adı da aynı şekilde reddedilir. Reddetme alan bazında değil, istek bazında yapılır — bir bilinmeyen anahtar 400 döndürür ve o istekteki hiçbir şey yazılmaz.

Temsilci destekli bir kampanyadaki ai_mode, Temsilciyi yansıtır. Bir kampanya bir AI Temsilcisi tarafından yanıtlandığında, kampanyayı okumak, o Temsilcinin Etkin anahtarından türetilen ai_mode değerini döndürür; bu, AI’nın yanıt verip vermeyeceğine karar veren tek anahtardır. Böyle bir kampanyada ai_mode yazılması kabul edilir ancak okuduğunuz değeri değiştirmez; bunun yerine Temsilcinin Etkin anahtarını açın veya kapatın (panodan veya Temsilciler API’si aracılığıyla). Temsilcisi olmayan klasik kampanyalarda, ai_mode daha önce olduğu gibi saklanan değeri okur ve yazar.

Bot alanları birleştirilir, üzerine yazılmaz. Bot ayarlarını noktalı anahtarlar ("bot.instructions": "...") veya iç içe geçmiş bir nesne ("bot": { "instructions": "..." }) olarak gönderin — her ikisi de yaprak yaprak yazar, bu nedenle dışarıda bıraktığınız alanlar mevcut değerlerini korur. bot.instructions, bot.goal, bot.rules ve bot.personality bu şekilde düzenlenebilir, Bot yapılandırma alanları altında listelenen diğer tüm bot ayarları da öyledir. Aynı durum test_bot, frequency ve follow_up_config için de geçerlidir.

Bir bot yapılandırmasını tamamen değiştirmek için — göndermediğiniz herhangi bir alanı silerek — tam nesne ile bot_replace (veya test_bot_replace) kullanın. Aynı nesne için bir değiştirme ve birleştirmeyi tek bir istekte birleştiremezsiniz; bu bir 400 döndürür.

Birkaç alan doğrudan yazılmak yerine özel bir anahtar aracılığıyla ayarlanır: kişi listesi için list_id, etkinlik türü için event_id (veya yapay zekanın birkaç tane rezerve etmesine izin vermek için sıralı bir etkinlik türü kimlikleri dizisi olan event_ids — ilki varsayılandır; boş bir dizi hepsinin bağlantısını keser) ve kampanyanın kişileri için contact_ids (kişi kimliklerinden oluşan bir dizi) kullanın. Bilgi tabanı girişleri bu uç nokta ile değil, SSS API aracılığıyla yönetilir.

Etiketler birleştirilmez, değiştirilir. tags öğesini tam dizi olarak gönderdiğinizde, bu kampanya etiket kümesi haline gelir — alanlar ve tek bir etiketi ekleyen veya düzenleyen uç noktalar için Kampanya etiketleri bölümüne bakın.

cURL

curl -X PUT "https://api.youraiconnector.com/v1/campaigns/NBCXrhqGPSFsd6MV7pRo?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "name": "Spring Promo v2", "enabled_channels": ["whatsapp"] }'

JavaScript

const res = await fetch(
  "https://api.youraiconnector.com/v1/campaigns/NBCXrhqGPSFsd6MV7pRo",
  {
    method: "PUT",
    headers: {
      "X-API-Key": "YOUR_API_KEY",
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      name: "Spring Promo v2",
      enabled_channels: ["whatsapp"],
    }),
  }
);
const data = await res.json();

Python

import requests

res = requests.put(
    "https://api.youraiconnector.com/v1/campaigns/NBCXrhqGPSFsd6MV7pRo",
    headers={"X-API-Key": "YOUR_API_KEY"},
    json={"name": "Spring Promo v2", "enabled_channels": ["whatsapp"]},
)
data = res.json()

Yanıt

{
  "success": true,
  "campaign_id": "NBCXrhqGPSFsd6MV7pRo"
}

Bir kampanyayı sil #

DELETE /campaigns/{campaignId}

Bir kampanyayı kalıcı olarak siler. Bu işlem geri alınamaz; kampanyaya tekrar ihtiyaç duyabileceğinizi düşünüyorsanız, bunun yerine arşivleyin.

cURL

curl -X DELETE "https://api.youraiconnector.com/v1/campaigns/NBCXrhqGPSFsd6MV7pRo?apiKey=YOUR_API_KEY"

JavaScript

const res = await fetch(
  "https://api.youraiconnector.com/v1/campaigns/NBCXrhqGPSFsd6MV7pRo",
  { method: "DELETE", headers: { "X-API-Key": "YOUR_API_KEY" } }
);
const data = await res.json();

Python

import requests

res = requests.delete(
    "https://api.youraiconnector.com/v1/campaigns/NBCXrhqGPSFsd6MV7pRo",
    headers={"X-API-Key": "YOUR_API_KEY"},
)
data = res.json()

Yanıt

{
  "success": true
}

Bir kampanyayı çoğaltma #

POST /campaigns/{campaignId}/duplicate

Kampanyanın tüm ayarlarını koruyarak bir kopyasını oluşturur. Kopya devre dışı olarak başlar ve adına bir (copy) soneki eklenir; böylece siz açıkça etkinleştirene kadar asla ileti göndermez.

cURL

curl -X POST "https://api.youraiconnector.com/v1/campaigns/NBCXrhqGPSFsd6MV7pRo/duplicate?apiKey=YOUR_API_KEY"

JavaScript

const res = await fetch(
  "https://api.youraiconnector.com/v1/campaigns/NBCXrhqGPSFsd6MV7pRo/duplicate",
  { method: "POST", headers: { "X-API-Key": "YOUR_API_KEY" } }
);
const { campaign_id } = await res.json();

Python

import requests

res = requests.post(
    "https://api.youraiconnector.com/v1/campaigns/NBCXrhqGPSFsd6MV7pRo/duplicate",
    headers={"X-API-Key": "YOUR_API_KEY"},
)
new_campaign_id = res.json()["campaign_id"]

Yanıt

{
  "success": true,
  "campaign_id": "aZ9plnewCopyId01234"
}

Aynı hesap içindeki yinelenen kopyalar.

Bir kampanyayı etkinleştirme veya devre dışı bırakma #

PATCH /campaigns/{campaignId}/enabled

Bir kampanyayı açar veya kapatır. Devre dışı bırakılan bir kampanya kişilerle etkileşimi durdurur ancak tüm yapılandırmasını korur.

İstek alanları

cURL

curl -X PATCH "https://api.youraiconnector.com/v1/campaigns/NBCXrhqGPSFsd6MV7pRo/enabled?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "enabled": true }'

JavaScript

const res = await fetch(
  "https://api.youraiconnector.com/v1/campaigns/NBCXrhqGPSFsd6MV7pRo/enabled",
  {
    method: "PATCH",
    headers: {
      "X-API-Key": "YOUR_API_KEY",
      "Content-Type": "application/json",
    },
    body: JSON.stringify({ enabled: true }),
  }
);
const data = await res.json();

Python

import requests

res = requests.patch(
    "https://api.youraiconnector.com/v1/campaigns/NBCXrhqGPSFsd6MV7pRo/enabled",
    headers={"X-API-Key": "YOUR_API_KEY"},
    json={"enabled": True},
)
data = res.json()

Yanıt

{
  "success": true,
  "campaign_id": "NBCXrhqGPSFsd6MV7pRo",
  "enabled": true
}

Bir kampanyayı arşivleyin veya geri yükleyin #

PATCH /campaigns/{campaignId}/archived

Bir kampanyayı arşivler veya geri yükler. Arşivlenen kampanyalar varsayılan kampanya listesinde gizlenir ancak tüm verilerini korurlar ve istendiği zaman geri yüklenebilirler.

İstek alanları

cURL

curl -X PATCH "https://api.youraiconnector.com/v1/campaigns/NBCXrhqGPSFsd6MV7pRo/archived?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "archived": true }'

JavaScript

const res = await fetch(
  "https://api.youraiconnector.com/v1/campaigns/NBCXrhqGPSFsd6MV7pRo/archived",
  {
    method: "PATCH",
    headers: {
      "X-API-Key": "YOUR_API_KEY",
      "Content-Type": "application/json",
    },
    body: JSON.stringify({ archived: true }),
  }
);
const data = await res.json();

Python

import requests

res = requests.patch(
    "https://api.youraiconnector.com/v1/campaigns/NBCXrhqGPSFsd6MV7pRo/archived",
    headers={"X-API-Key": "YOUR_API_KEY"},
    json={"archived": True},
)
data = res.json()

Yanıt

{
  "success": true,
  "campaign_id": "NBCXrhqGPSFsd6MV7pRo",
  "archived": true
}

Bot yapılandırmasını güncelle #

PUT /campaigns/{campaignId}/bot-config

Bu, bireysel bot ayarlarını değiştirmenin güvenli yoludur. Gönderdiğiniz her alan mevcut bot yapılandırmasıyla birleştirilir, bu nedenle dışarıda bıraktığınız tüm alanlar korunur. Botun yalnızca bir kısmında değişiklik yapmak istediğinizde bunu campaign-update uç noktası yerine kullanın.

Alan anahtarları yalnızca harf, rakam, alt çizgi ve kısa çizgi içermelidir.

cURL

curl -X PUT "https://api.youraiconnector.com/v1/campaigns/NBCXrhqGPSFsd6MV7pRo/bot-config?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "instructions": "Always answer in a friendly, concise tone.",
    "ai_speed": "balanced"
  }'

JavaScript

const res = await fetch(
  "https://api.youraiconnector.com/v1/campaigns/NBCXrhqGPSFsd6MV7pRo/bot-config",
  {
    method: "PUT",
    headers: {
      "X-API-Key": "YOUR_API_KEY",
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      instructions: "Always answer in a friendly, concise tone.",
      ai_speed: "balanced",
    }),
  }
);
const data = await res.json();

Python

import requests

res = requests.put(
    "https://api.youraiconnector.com/v1/campaigns/NBCXrhqGPSFsd6MV7pRo/bot-config",
    headers={"X-API-Key": "YOUR_API_KEY"},
    json={
        "instructions": "Always answer in a friendly, concise tone.",
        "ai_speed": "balanced",
    },
)
data = res.json()

Yanıt

{
  "success": true,
  "campaign_id": "NBCXrhqGPSFsd6MV7pRo"
}

Bot yapılandırma alanları #

Tüm bot alanları isteğe bağlıdır. Yalnızca ayarlamak istediklerinizi gönderin. Burada listelenenlerin dışındaki tüm ek bot alanları kabul edilir ve olduğu gibi saklanır.

Bot aktif saatlerini ayarla #

PUT /campaigns/{campaignId}/active-hours

Botun uygunluk programını ayarlar. Yapılandırılmış zaman aralıklarının dışında bot otomatik olarak yanıt vermez. Bu, bot yapılandırmasının availability alanına yazılır.

İstek alanları

Her hafta içi günü ya tek bir zaman aralığı ya da bir aralık dizisi tutar. Bir aralık, 24 saatlik HH:MM biçiminde bir start_time ve end_time içerir.

cURL

curl -X PUT "https://api.youraiconnector.com/v1/campaigns/NBCXrhqGPSFsd6MV7pRo/active-hours?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "availability": {
      "monday": { "start_time": "09:00", "end_time": "17:00" },
      "tuesday": [
        { "start_time": "09:00", "end_time": "12:00" },
        { "start_time": "13:00", "end_time": "17:00" }
      ]
    }
  }'

JavaScript

const res = await fetch(
  "https://api.youraiconnector.com/v1/campaigns/NBCXrhqGPSFsd6MV7pRo/active-hours",
  {
    method: "PUT",
    headers: {
      "X-API-Key": "YOUR_API_KEY",
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      availability: {
        monday: { start_time: "09:00", end_time: "17:00" },
        tuesday: [
          { start_time: "09:00", end_time: "12:00" },
          { start_time: "13:00", end_time: "17:00" },
        ],
      },
    }),
  }
);
const data = await res.json();

Python

import requests

res = requests.put(
    "https://api.youraiconnector.com/v1/campaigns/NBCXrhqGPSFsd6MV7pRo/active-hours",
    headers={"X-API-Key": "YOUR_API_KEY"},
    json={
        "availability": {
            "monday": {"start_time": "09:00", "end_time": "17:00"},
            "tuesday": [
                {"start_time": "09:00", "end_time": "12:00"},
                {"start_time": "13:00", "end_time": "17:00"},
            ],
        }
    },
)
data = res.json()

Yanıt

{
  "success": true,
  "campaign_id": "NBCXrhqGPSFsd6MV7pRo"
}

Bir kampanyanın özel işlevlerini listele #

GET /campaigns/{campaignId}/custom-functions

Bu kampanyaya bağlı olan ve tam tanımlara çözümlenmiş özel işlevleri döndürür. Özel işlevler, botun bir konuşma sırasında çağırabileceği harici HTTP eylemleridir; örneğin, mağazanızdaki stok durumunu kontrol etmek veya CRM’inizde bir kayıt oluşturmak gibi.

cURL

curl "https://api.youraiconnector.com/v1/campaigns/NBCXrhqGPSFsd6MV7pRo/custom-functions?apiKey=YOUR_API_KEY"

JavaScript

const res = await fetch(
  "https://api.youraiconnector.com/v1/campaigns/NBCXrhqGPSFsd6MV7pRo/custom-functions",
  { headers: { "X-API-Key": "YOUR_API_KEY" } }
);
const { custom_functions } = await res.json();

Python

import requests

res = requests.get(
    "https://api.youraiconnector.com/v1/campaigns/NBCXrhqGPSFsd6MV7pRo/custom-functions",
    headers={"X-API-Key": "YOUR_API_KEY"},
)
custom_functions = res.json()["custom_functions"]

Yanıt

{
  "success": true,
  "custom_functions": [
    {
      "id": "fn_abc123",
      "name": "check_stock",
      "description": "Looks up whether a product is in stock.",
      "url": "https://example.com/api/stock",
      "method": "POST",
      "input": [
        { "name": "sku", "type": "string" }
      ],
      "ai_action": "Tell the customer whether the item is available.",
      "created_at": 1700000000000,
      "updated_at": 1700000500000
    }
  ]
}

Bir özel işlevi bir kampanyaya bağlayın #

POST /campaigns/{campaignId}/custom-functions

Botun bir görüşme sırasında çağırabilmesi için mevcut bir özel işlevi bu kampanyaya bağlar. Zaten bağlı olan bir işlevi bağlamak hiçbir işlem yapmaz.

curl -X POST "https://api.youraiconnector.com/v1/campaigns/NBCXrhqGPSFsd6MV7pRo/custom-functions?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "custom_function_id": "fn_abc123" }'

Yanıt

{
  "success": true,
  "campaign_id": "NBCXrhqGPSFsd6MV7pRo",
  "custom_function_id": "fn_abc123"
}

Bir özel işlevin bir kampanyayla bağlantısını kesin #

DELETE /campaigns/{campaignId}/custom-functions/{customFunctionId}

Bağlı olmayan bir işlevin bağlantısını kesmek hiçbir işlem yapmaz.

curl -X DELETE "https://api.youraiconnector.com/v1/campaigns/NBCXrhqGPSFsd6MV7pRo/custom-functions/fn_abc123?apiKey=YOUR_API_KEY"

Yanıt

{
  "success": true,
  "campaign_id": "NBCXrhqGPSFsd6MV7pRo",
  "custom_function_id": "fn_abc123"
}

Bir bilgi tabanı kaynağını bir kampanyaya bağlayın #

POST /campaigns/{campaignId}/kb-sources

Botun yanıt verirken yararlanabilmesi için bir bilgi tabanı kaynağını (SSS API aracılığıyla oluşturulmuş) bu kampanyaya bağlar. Zaten bağlı olan bir kaynağı bağlamak hiçbir işlem yapmaz.

curl -X POST "https://api.youraiconnector.com/v1/campaigns/NBCXrhqGPSFsd6MV7pRo/kb-sources?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "kb_source_id": "kb_abc123" }'

Yanıt

{
  "success": true,
  "campaign_id": "NBCXrhqGPSFsd6MV7pRo",
  "kb_source_id": "kb_abc123"
}

Bir bilgi tabanı kaynağının bir kampanyayla bağlantısını kesin #

DELETE /campaigns/{campaignId}/kb-sources/{kbSourceId}

Bağlı olmayan bir kaynağın bağlantısını kesmek hiçbir işlem yapmaz.

curl -X DELETE "https://api.youraiconnector.com/v1/campaigns/NBCXrhqGPSFsd6MV7pRo/kb-sources/kb_abc123?apiKey=YOUR_API_KEY"

Yanıt

{
  "success": true,
  "campaign_id": "NBCXrhqGPSFsd6MV7pRo",
  "kb_source_id": "kb_abc123"
}

Bir MCP sunucusunu bir kampanyaya bağlayın #

POST /campaigns/{campaignId}/mcp-servers

Bir MCP sunucusunu bu kampanyaya bağlayarak, botun bir görüşme sırasında o sunucunun araçlarına erişmesini sağlar. Hâlihazırda bağlı olan bir sunucuyu bağlamak hiçbir işlem yapmaz.

curl -X POST "https://api.youraiconnector.com/v1/campaigns/NBCXrhqGPSFsd6MV7pRo/mcp-servers?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "mcp_server_id": "mcp_abc123" }'

Yanıt

{
  "success": true,
  "campaign_id": "NBCXrhqGPSFsd6MV7pRo",
  "mcp_server_id": "mcp_abc123"
}

Bir MCP sunucusunun kampanyayla bağlantısını kesme #

DELETE /campaigns/{campaignId}/mcp-servers/{mcpServerId}

Bağlı olmayan bir sunucunun bağlantısını kesmek hiçbir işlem yapmaz.

curl -X DELETE "https://api.youraiconnector.com/v1/campaigns/NBCXrhqGPSFsd6MV7pRo/mcp-servers/mcp_abc123?apiKey=YOUR_API_KEY"

Yanıt

{
  "success": true,
  "campaign_id": "NBCXrhqGPSFsd6MV7pRo",
  "mcp_server_id": "mcp_abc123"
}

Kampanya medya kütüphanesi #

Medya kütüphanesi, botun bir görüşme sırasında gönderebileceği görselleri, videoları, belgeleri ve sesli notları barındırır.

Bir kampanyanın medya kütüphanesini listeleme #

GET /campaigns/{campaignId}/media-library

curl "https://api.youraiconnector.com/v1/campaigns/NBCXrhqGPSFsd6MV7pRo/media-library?apiKey=YOUR_API_KEY"

Yanıt

{
  "success": true,
  "campaign_id": "NBCXrhqGPSFsd6MV7pRo",
  "media_items": [
    {
      "id": "media_abc123",
      "item_id": "media_abc123",
      "title": "Pricing sheet",
      "description": "Send when the contact asks about pricing.",
      "media_url": "https://example.com/pricing.pdf",
      "media_content_type": "application/pdf",
      "type": "document",
      "agent_id": "",
      "campaign_id": "NBCXrhqGPSFsd6MV7pRo",
      "media_home": "campaign"
    }
  ]
}

media_url, yükleme sırasında oluşturulan imzalı bir URL’dir; siz onu tekrar okuduğunuzda süresi dolmuş olabilir; kontrol paneli istendiğinde onu yeniden imzalar.

Bir medya öğesi yükleme #

POST /campaigns/{campaignId}/media-library

curl -X POST "https://api.youraiconnector.com/v1/campaigns/NBCXrhqGPSFsd6MV7pRo/media-library?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "base64Data": "iVBORw0KGgoAAAANSUhEUgAA...",
    "mimeType": "image/png",
    "title": "Product photo",
    "description": "Send when the contact asks what the product looks like."
  }'

Yanıt

{
  "success": true,
  "itemId": "media_abc123",
  "mediaUrl": "https://example.com/product.png",
  "storagePath": "ai_media/campaigns/NBCXrhqGPSFsd6MV7pRo/media_abc123.png",
  "mediaContentType": "image/png",
  "type": "image",
  "isVoiceNote": false
}

Bir medya öğesini güncelle #

PATCH /campaigns/{campaignId}/media-library/{itemId}

Yalnızca öğenin meta verilerini düzenler — dosyanın kendisini değiştirmek için öğeyi silip yenisini yükleyin.

curl -X PATCH "https://api.youraiconnector.com/v1/campaigns/NBCXrhqGPSFsd6MV7pRo/media-library/media_abc123?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "title": "Updated pricing sheet" }'

Yanıt

{
  "success": true,
  "campaign_id": "NBCXrhqGPSFsd6MV7pRo",
  "item_id": "media_abc123"
}

Bir medya öğesini sil #

DELETE /campaigns/{campaignId}/media-library/{itemId}

Zaten silinmiş bir öğeyi silmek hiçbir işlem yapmaz.

curl -X DELETE "https://api.youraiconnector.com/v1/campaigns/NBCXrhqGPSFsd6MV7pRo/media-library/media_abc123?apiKey=YOUR_API_KEY"

Yanıt

{ "success": true, "deleted": true }

Kampanya etiketleri #

Kampanya etiketi, botun bir görüşme sırasında kişiye uygulamasını öğrettiğiniz bir etikettir — hot-lead, not-interested, booked-a-call. Her etiketin üç parçası vardır:

Etiket adları bir kampanya içinde benzersiz olmalıdır. Bot etiketleri ada göre uygular, bu nedenle aynı adı paylaşan iki girişin kazananı tanımlı değildir.

Bir kampanyanın tüm etiketlerini ayarlama #

PUT /campaigns/{campaignId}, tags dizisi ile.

Bu işlem, kampanyanın etiketlerini tam olarak gönderdiğiniz verilerle değiştirir; bu, kontrol panelindeki Etiketler sekmesini kaydettiğinizde yapılan işlemin aynısıdır. Her seferinde tam diziyi gönderin — dışarıda bıraktığınız bir etiket, sildiğiniz bir etiket demektir. [] göndermek hepsini temizler.

cURL

curl -X PUT "https://api.youraiconnector.com/v1/campaigns/NBCXrhqGPSFsd6MV7pRo?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "tags": [
      {
        "name": "hot-lead",
        "description": "The person confirms they want to buy, or asks how to get started right away.",
        "webhook": "https://example.com/hooks/campaign-events"
      },
      {
        "name": "not-interested",
        "description": "The person declines the offer or says they are not a fit."
      }
    ]
  }'

JavaScript

const res = await fetch(
  "https://api.youraiconnector.com/v1/campaigns/NBCXrhqGPSFsd6MV7pRo",
  {
    method: "PUT",
    headers: {
      "X-API-Key": "YOUR_API_KEY",
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      tags: [
        {
          name: "hot-lead",
          description:
            "The person confirms they want to buy, or asks how to get started right away.",
          webhook: "https://example.com/hooks/campaign-events",
        },
        {
          name: "not-interested",
          description: "The person declines the offer or says they are not a fit.",
        },
      ],
    }),
  }
);
const data = await res.json();

Python

import requests

res = requests.put(
    "https://api.youraiconnector.com/v1/campaigns/NBCXrhqGPSFsd6MV7pRo",
    headers={"X-API-Key": "YOUR_API_KEY"},
    json={
        "tags": [
            {
                "name": "hot-lead",
                "description": "The person confirms they want to buy, or asks how to get started right away.",
                "webhook": "https://example.com/hooks/campaign-events",
            },
            {
                "name": "not-interested",
                "description": "The person declines the offer or says they are not a fit.",
            },
        ]
    },
)
data = res.json()

Yanıt

{
  "success": true,
  "campaign_id": "NBCXrhqGPSFsd6MV7pRo"
}

Etiketleri GET /campaigns/{campaignId} ile geri okuyun.

Bir etiket ekleme #

POST /campaigns/{campaignId}/tags

Geri kalanını yeniden göndermeden tek bir etiket ekler. Bunu, bu istekte oluşturmadığınız bir kümeye ekleme yaparken kullanın.

curl -X POST "https://api.youraiconnector.com/v1/campaigns/NBCXrhqGPSFsd6MV7pRo/tags?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "tag": { "name": "booked-a-call", "description": "The person confirms a booked time." } }'

Tam olarak aynı etiketi iki kez göndermek, ikinci seferde hiçbir şey yapmaz. Aynı tag_id değerini farklı bir ad veya açıklama ile göndermek, ilkini düzenlemek yerine ikinci bir giriş ekler — yerinde düzenleme yapmak için aşağıdaki uç noktayı kullanın.

Bir etiketi güncelleme veya kaldırma #

PUT /campaigns/{campaignId}/tags/{tagId} DELETE /campaigns/{campaignId}/tags/{tagId}

Bunlar, bir girdiyi tag_id değeriyle adresler, bu nedenle yalnızca bununla oluşturulmuş etiketlerde çalışırlar. Bir etiketin tag_id değeri yoksa, yukarıdaki tüm dizi PUT /campaigns/{campaignId} ile değiştirin.

curl -X PUT "https://api.youraiconnector.com/v1/campaigns/NBCXrhqGPSFsd6MV7pRo/tags/tag_abc123?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "tag": { "name": "hot-lead", "description": "Updated instruction." } }'

Kampanyada olmayan bir tagId, "Tag not found in campaign tags" ile 404 döndürür.

Bir kampanyanın kanallarını değiştirme #

POST /campaigns/{campaignId}/channels

Kampanyanın enabled_channels dizisindeki kanalları, dizinin tamamını yeniden göndermeden ekler veya kaldırır — başka bir işlem aynı anda kampanyayı düzenliyor olabileceğinde PUT /campaigns/{campaignId} kullanmaktan daha güvenlidir.

Tek bir geçiş veya toplu işlem gönderin — aynı istekte her ikisini birden göndermeyin:

{ "channel": "whatsapp", "action": "add" }

{ "add": ["whatsapp", "instagram"], "remove": ["sms"] }

Geçerli kanallar: whatsapp, whatsapp_web, sms, instagram, messenger, facebook, chat_widget, custom_channel, imessage, telegram, instagram_private, line, viber, tiktok, email, linkedin, skool.

curl -X POST "https://api.youraiconnector.com/v1/campaigns/NBCXrhqGPSFsd6MV7pRo/channels?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "channel": "whatsapp", "action": "add" }'

Yanıt

{
  "success": true,
  "campaign_id": "NBCXrhqGPSFsd6MV7pRo",
  "added": ["whatsapp"],
  "removed": []
}

Bu yalnızca kampanyanın hangi kanallarda reklam yapacağını değiştirir — bir kanalı kimin yanıtlayacağına karar vermez. Bunun için yukarıdaki Kampanya türleri bölümüne ve aşağıdaki Bir kampanyayı gelen kanallara yönlendirme bölümüne bakın.

Yorumdan DM’e (Instagram ve Facebook) #

Yorumdan DM’e özelliği, gönderilerinizden birine yapılan bir yorumu özel bir sohbete dönüştürür: birisi yorum yapar, bot onlara bir DM gönderir ve kampanya sohbeti oradan devralır. Tamamen kampanya nesnesi üzerinden yapılandırıldığından, bunun kullanıcı arayüzüne özgü bir yanı yoktur.

Önce Facebook Sayfasını bağlayın — bkz. Kanal Bağlantısı. Ardından aşağıdaki alanları PUT /campaigns/{campaignId} ile ayarlayın.

Kampanya Live olmalıdır. Yorum izleme yalnızca status değeri Live olan kampanyaları alır (büyük/küçük harf duyarlı değildir — bkz. Kampanya türleri). Başka herhangi bir durum onu sessizce devre dışı bırakır ve "Active" gibi uydurma bir durum artık saklanmak yerine bir 400 ile reddedilir. Geçerli durumlar arasında Draft, Pending Approval, Scheduled, Live, Paused, Completed, Sent ve Failed bulunur.

Alanlar

Bir alanı temizleme

Bu alanlar, null gönderdiğinizde null olarak ayarlanmak yerine kaldırılır, böylece bot varsayılanlarına geri döner: instagram_post_ids, facebook_post_ids, instagram_comment_delay_minutes, facebook_comment_delay_minutes, public_comment_reply_instructions, follower_outreach_instructions, first_response_exact_text, first_response_exact_text_variants, public_comment_reply_exact_text, public_comment_reply_exact_text_variants.

Bilinmeyen bir anahtar tüm isteği reddeder. PUT /campaigns/{campaignId}, tüm gövdeyi bir izin listesine göre doğrular. Tanınmayan bir anahtar, isteğin tamamı için 400 döndürür; sessizce göz ardı edilmez ve o gövdedeki diğer alanların hiçbiri yazılmaz.

cURL

curl -X PUT "https://api.youraiconnector.com/v1/campaigns/NBCXrhqGPSFsd6MV7pRo?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "status": "Live",
    "monitor_instagram_posts": true,
    "instagram_comment_delay_minutes": 2,
    "first_response_mode": "exact_text",
    "first_response_exact_text": "Hey! Sending the details over now.",
    "first_response_exact_text_variants": [
      "Hi there, here are the details you asked for.",
      "Thanks for commenting, here is what you need."
    ],
    "public_comment_reply_exact_text": "Just sent you a DM."
  }'

JavaScript

const res = await fetch(
  "https://api.youraiconnector.com/v1/campaigns/NBCXrhqGPSFsd6MV7pRo",
  {
    method: "PUT",
    headers: {
      "X-API-Key": "YOUR_API_KEY",
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      status: "Live",
      monitor_instagram_posts: true,
      instagram_comment_delay_minutes: 2,
      first_response_mode: "ai",
      public_comment_reply_instructions:
        "Tell them to check their message requests folder too.",
    }),
  }
);
const data = await res.json();

Python

import requests

res = requests.put(
    "https://api.youraiconnector.com/v1/campaigns/NBCXrhqGPSFsd6MV7pRo",
    headers={"X-API-Key": "YOUR_API_KEY"},
    json={
        "status": "Live",
        "monitor_facebook_posts": True,
        "facebook_post_ids": None,
        "facebook_comment_delay_minutes": 5,
    },
)
data = res.json()

Yanıt

{
  "success": true,
  "campaign_id": "NBCXrhqGPSFsd6MV7pRo"
}

Yorumda bırakılan görünür yanıt, planınızda yorum yanıtlama özelliğinin olmasını gerektirir. Bu özellik olmadan DM yine de gönderilir ancak herkese açık yanıt atlanır.

Bir kampanyayı yapay zeka ile optimize etme #

POST /campaigns/{campaignId}/optimize

Kontrol panelindeki Optimize et ve beğenmeme geri bildirim akışlarıyla aynı yapay zeka yeniden yazma işlemini çalıştırır: geri bildiriminizi alır, botun talimatlarını yeniden yazar ve sonucu incelemeniz için yeni bir taslak revizyon olarak hazırlar.

curl -X POST "https://api.youraiconnector.com/v1/campaigns/NBCXrhqGPSFsd6MV7pRo/optimize?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "user_feedback": "Make the tone more casual and mention the free trial earlier." }'

Yanıt (202 — yeniden yazma işlemi arka planda çalışır)

{ "success": true, "campaign_id": "NBCXrhqGPSFsd6MV7pRo" }

GET /campaigns/{campaignId} anketini yapın ve test_bot.status’i izleyin: hemen "Optimizing" durumuna geçer, ardından yeniden yazma işlemi test_bot’e ulaştığında tekrar "Draft" durumuna döner. Buradan itibaren herhangi bir kontrol paneli taslağı gibi davranır; inceleyin ve ardından canlıya almak için kontrol panelinde yayınlayın. 409, bu kampanya için halihazırda bir optimizasyonun çalıştığı anlamına gelir.

Optimizasyon, hesabınızdaki diğer tüm yapay zeka işlemlerinde olduğu gibi kredi harcar.

Bir kişiyi kampanyaya atama #

POST /campaigns/{campaignId}/contacts/{contactId}/assign

Mevcut bir kişiyi bir kampanyaya dahil eder ve talep etmeniz durumunda kampanyanın açılış mesajını hemen gönderir. Bir kampanyanın onaylı WhatsApp şablonunu bir kişiye göndermenin yolu budur: Bir kampanyanın onaylandığı şablon o kampanyaya aittir, bu nedenle Templates API kütüphanesinde görünmez ve /whatsapp-templates/send aracılığıyla gönderilemez.

curl -X POST "https://api.youraiconnector.com/v1/campaigns/NBCXrhqGPSFsd6MV7pRo/contacts/contact_abc123/assign?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "sendOpeningMessage": true }'

Yanıt

{
  "success": true,
  "data": { "contactId": "contact_abc123", "campaignId": "NBCXrhqGPSFsd6MV7pRo" }
}

Krediler: Bir WhatsApp kampanyasında açılış mesajı göndermek, alıcının ülkesine ve şablonun kategorisine göre fiyatlandırılan herhangi bir şablon gönderimi gibi ücretlendirilir. Diğer kanallarda açılış mesajı normal bir giden mesajdır.

Bir kampanyayı gelen kanallara yönlendirme #

Bu uç noktalar, bir kampanyanın bir kanaldaki yeni ve bilinmeyen kişilere nasıl yanıt vereceğini yönetir. Yeni entegrasyonlar için Giriş Noktalarını Tercih Edin (Kampanya türleri altındaki nota bakın) — bunlar, eski yöntemle yönlendirme yapan kampanyalarla çalışmak ve iki gelen kampanya arasındaki kanal sahipliği çakışmasını çözmek için yararlı olmaya devam eder.

Bir kampanyayı gelen kanallara atama #

POST /campaigns/{campaignId}/incoming-routing

curl -X POST "https://api.youraiconnector.com/v1/campaigns/NBCXrhqGPSFsd6MV7pRo/incoming-routing?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "channels": ["whatsapp", "instagram"] }'

Yanıt

{
  "success": true,
  "uid": "abc123",
  "campaignId": "NBCXrhqGPSFsd6MV7pRo",
  "channels": ["whatsapp", "instagram"],
  "failed": []
}

channels yalnızca bu kampanyaya yönlendirilen kanalları listeler; failed ise yönlendirilmeyenleri listeler. İstenen her kanal başarısız olursa, isteğin kendisi de başarısız olur.

Bir kampanyanın gelen yönlendirmesini temizleme #

DELETE /campaigns/{campaignId}/incoming-routing

curl -X DELETE "https://api.youraiconnector.com/v1/campaigns/NBCXrhqGPSFsd6MV7pRo/incoming-routing?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "channelToUnassign": "instagram" }'

Yanıt

{
  "success": true,
  "uid": "abc123",
  "campaignId": "NBCXrhqGPSFsd6MV7pRo",
  "channelsRemoved": ["instagram"]
}

Uyuyan bir kampanyayı yeniden etkinleştirme #

POST /campaigns/{campaignId}/reactivate

Bir kampanyayı Ended, Completed, Paused veya Draft durumundan geri getirir ve kanallarını yeniden talep eder. Yalnızca Incoming from Unknown Contacts veya Combined durumundaki kampanyalarda çalışır; zaten Live olan bir kampanya başarılı kabul edilir ve yapılacak bir işlem yoktur.

curl -X POST "https://api.youraiconnector.com/v1/campaigns/NBCXrhqGPSFsd6MV7pRo/reactivate?apiKey=YOUR_API_KEY"

Yanıt

{
  "success": true,
  "data": {
    "success": true,
    "channelsReactivated": ["whatsapp"],
    "channelsBlockedByConflict": [],
    "campaignType": "Incoming from Unknown Contacts"
  }
}

Farklı bir kampanyanın temsilcisi tarafından halihazırda talep edilmiş bir kanal, tüm çağrıyı başarısız kılmak yerine channelsBlockedByConflict içinde görünür; bu kampanyanın kanalı devralmasını istiyorsanız, önce kanalı serbest bırakmak için aşağıdaki çakışan bir gelen kampanyayı durdur seçeneğini kullanın. Yeniden etkinleştirmeyi desteklemeyen bir kampanya türü veya yukarıdaki uyku durumlarından biri olmayan bir durum için 400 döndürülür.

Çakışan bir gelen kampanyayı durdur #

POST /campaigns/{campaignId}/stop-incoming

Bu kampanyanın kanallarını, şu anda onları elinde tutan DİĞER kampanyadan serbest bırakır, böylece bu kampanya onları bir sonraki adımda talep edebilir. Bu, bir gelen kampanyayı başka birinin zaten yanıtladığı bir kanala başlattığınızda kontrol panelinin otomatik olarak yaptığı işlemin REST sürümüdür.

curl -X POST "https://api.youraiconnector.com/v1/campaigns/NBCXrhqGPSFsd6MV7pRo/stop-incoming?apiKey=YOUR_API_KEY"

Yanıt

{
  "success": true,
  "campaign_id": "NBCXrhqGPSFsd6MV7pRo",
  "ended_campaign_ids": [],
  "released_channels": ["whatsapp"],
  "cleared_entire_field": false
}

Bu kampanya reklamını yaptığı her kanala zaten sahip olduğunda released_channels boş döner; devralınacak bir şey yoktur.

Maliyet tahminleri #

Bir kampanyayı göndermeden önce başlatmanın ne kadara mal olacağını tahmin edin.

WhatsApp şablonu maliyet tahmini #

GET /campaigns/{campaignId}/template-cost-estimate

curl "https://api.youraiconnector.com/v1/campaigns/NBCXrhqGPSFsd6MV7pRo/template-cost-estimate?apiKey=YOUR_API_KEY"

Yanıt

{
  "success": true,
  "billing_mode": "credits",
  "data": {
    "countries": [
      {
        "countryCode": "1",
        "name": "United States",
        "iso": "US",
        "flag": "🇺🇸",
        "contactCount": 120,
        "costPerContact": 2,
        "subtotal": 240
      }
    ],
    "totalContacts": 120,
    "totalTemplateCost": 240,
    "templateCategory": "marketing",
    "billing_mode": "credits",
    "service_messages_billable_soon": false
  }
}

billing_mode, yönetilen WhatsApp hattında "credits"'dir. Meta’nın WhatsApp İşletme Hesabınızı doğrudan faturalandırdığı bir hatta, costPerContact, subtotal ve totalTemplateCost değerleri null olarak döner; bildirilecek bir kredi rakamı olmadığından asla ücretsiz olarak okunacak 0 değeri dönmez.

SMS maliyet tahmini #

GET /campaigns/{campaignId}/sms-cost-estimate

curl "https://api.youraiconnector.com/v1/campaigns/NBCXrhqGPSFsd6MV7pRo/sms-cost-estimate?apiKey=YOUR_API_KEY"

Yanıt

{
  "success": true,
  "billing_mode": "twilio_direct",
  "data": {
    "totalContacts": 120,
    "messageLength": 87,
    "segmentsPerMessage": 1,
    "totalSegments": 120,
    "estimatedCostUsd": 0.96,
    "priceUnit": "USD per segment",
    "billedByTwilio": true
  }
}

SMS her zaman kendi Twilio hesabınız üzerinden gönderilir (bkz. SMS sağlayıcısı), bu nedenle bu her zaman doğrudan Twilio tarafından faturalandırılır; estimatedCostUsd, bir kredi ücreti değil, bu Twilio faturasının bir tahminidir.

Limit kontrolleri #

Başarısız bir gönderimden sonra öğrenmek yerine, başlatmadan önce bir limiti kontrol edin.

Kampanya kapsamlı kontroller #

GET /campaigns/{campaignId}/limits/ai-credit-messaging — bu kampanyayı başlatmanın veya planlamanın hesabınızın yapay zeka kredisi mesajlaşma limitini aşıp aşmayacağı.

GET /campaigns/{campaignId}/limits/messaging — hesabınızın günlük mesajlaşma limitini aşıp aşmayacağı.

curl "https://api.youraiconnector.com/v1/campaigns/NBCXrhqGPSFsd6MV7pRo/limits/messaging?apiKey=YOUR_API_KEY"

Yanıt (limit aşılmadı)

{
  "success": true,
  "data": "Campaign is within the daily messaging limit."
}

Limit aşıldığında bunun yerine bir 400 döndürülür ve nedeni error içinde belirtilir.

Hesap kapsamlı kontroller #

GET /campaigns/limits/campaigns — aboneliğinizin aylık kampanya oluşturma limitine ulaşıp ulaşmadığınız.

GET /campaigns/limits/contacts — aboneliğinizin kişi limitine ulaşıp ulaşmadığınız.

curl "https://api.youraiconnector.com/v1/campaigns/limits/campaigns?apiKey=YOUR_API_KEY"

Yanıt

{
  "success": true,
  "data": "You can create 3 more campaigns this month."
}

Kampanya istatistik toplamları #

GET /campaigns/stats/totals

Hesabınızdaki her kampanya VE her yapay zeka temsilcisi için, geriye dönük bir pencere üzerinden gönderilen ve yanıtlanan toplamlar — kampanya listesi sayfasında her satırın yanında gösterilen sayıların aynısı, kampanya başına bir istek yerine tek bir çağrıda.

curl "https://api.youraiconnector.com/v1/campaigns/stats/totals?days=30&apiKey=YOUR_API_KEY"

Yanıt

{
  "success": true,
  "byCampaign": {
    "NBCXrhqGPSFsd6MV7pRo": { "sent": 1204, "replied": 318 }
  },
  "byAgent": {
    "agent_abc123": { "sent": 1204, "replied": 318 }
  },
  "windowDays": 30
}

byAgent kendi başına bir toplamdır, byCampaign toplamı değildir — yapay zeka temsilcisi tabanlı bir hesabın trafiği hiçbir kampanyaya bağlı olmayabilir, bu nedenle aksi takdirde burada görünmez olurdu.

Oyun alanında bir kampanyayı test etme #

Oyun alanı, gerçek bir kanala veya gerçek bir kişiye dokunmadan bir kampanyanın botuyla sohbet etmenizi sağlar. Bu, kontrol panelinin deneme paneliyle aynı korumalı alandır ve API üzerinden tamamen kullanılabilir.

Akış şöyledir: gizli bir test kişisi oluşturun, bir mesaj gönderin ve ardından botun yanıtı için kampanyayı sorgulayın. Yanıtlar asenkron olarak oluşturulur, bu nedenle yanıt gövdesinde değil, kampanyadaki test_messages içinde gelirler.

Playground, API maliyet kredileri üzerinden çalışır. Bir API anahtarı ile başlatılan test konuşması, gerçek bir yanıtta olduğu gibi normal yapay zeka mesajı ücreti üzerinden ücretlendirilir ve kullanım geçmişinizde normal bir giriş olarak görünür. Kontrol panelinden yapılan testler ücretsiz kalmaya devam eder. Aradaki fark kasıtlıdır: bir test çalışması, canlı bir çalışma ile aynı yapay zeka işini yapar, bu nedenle sınırsız bir API playground’u, başkasının hesabına sınırsız yapay zeka çalıştırmanın bir yolu olurdu.

Adım 1 - Test kişisini oluşturun #

POST /campaigns/{campaignId}/try-out/contact

Gizli test kişisini oluşturur ve onu kampanyaya bağlar. Tüm gövde alanları isteğe bağlıdır; boş bıraktığınız her şey yerleşik bir örnek kimliğe (John Doe) geri döner.

curl -X POST "https://api.youraiconnector.com/v1/campaigns/NBCXrhqGPSFsd6MV7pRo/try-out/contact?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "first_name": "Maria", "last_name": "Lopez" }'

Yanıt

{
  "success": true,
  "contactId": "8kQx1vNbA2fLpR7d"
}

Adım 2 - Gelen mesajı kaydet #

POST /campaigns/{campaignId}/try-out/messages

Mesajları test dizisine ekler. Ziyaretçinin mesajını önce buraya gönderin, böylece botun okuduğu konuşma geçmişinde görünür.

curl -X POST "https://api.youraiconnector.com/v1/campaigns/NBCXrhqGPSFsd6MV7pRo/try-out/messages?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "messages": [
      {
        "body": "Do you ship to Belgium?",
        "direction": "inbound",
        "timestamp": "2026-07-22T09:30:00Z"
      }
    ]
  }'

Yanıt

{
  "success": true,
  "campaign_id": "NBCXrhqGPSFsd6MV7pRo",
  "appended": 1
}

Adım 3 - Botun yanıt vermesini iste #

POST /campaigns/{campaignId}/try-out/test-message

Mesajı yapay zeka hattına gönderir. Bot yanıtını fiilen üreten çağrı budur.

curl -X POST "https://api.youraiconnector.com/v1/campaigns/NBCXrhqGPSFsd6MV7pRo/try-out/test-message?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "message": "Do you ship to Belgium?" }'

Yanıt

{
  "success": true,
  "data": "Published"
}

"Published", mesajın yapay zeka hattına gittiği anlamına gelir. "Ignored", daha yeni bir test mesajının bunun yerini aldığı anlamına gelir; oyun alanı, gerçek bir konuşmada birinin yazmayı bitirmesinin beklenmesi gibi, son mesajdan yaklaşık dört saniye sonra hızlı bir mesaj dizisini tek bir yanıtta birleştirir. Bu birleştirme penceresi nedeniyle, bu çağrının dönmesi birkaç saniye sürer.

Adım 4 - Yanıtı oku #

GET /campaigns/{campaignId}

Botun yanıtı, kampanyanın test_messages dizisine eklenir. Yeni bir outbound girişi görünene kadar kampanyayı sorgulayın.

{
  "success": true,
  "campaign": {
    "id": "NBCXrhqGPSFsd6MV7pRo",
    "test_messages": [
      { "body": "Do you ship to Belgium?", "direction": "inbound" },
      { "body": "Yes, we ship across the EU.", "direction": "outbound" }
    ]
  }
}

Oyun alanını sıfırla #

POST /campaigns/{campaignId}/try-out/reset

Tüm korumalı alanı temizler: test kişisini siler, test_messages içeriğini temizler ve botun yanıt kilitlerini serbest bırakır. Bunu test çalıştırmaları arasında kullanın.

curl -X POST "https://api.youraiconnector.com/v1/campaigns/NBCXrhqGPSFsd6MV7pRo/try-out/reset?apiKey=YOUR_API_KEY"

Yanıt

{
  "success": true,
  "campaign_id": "NBCXrhqGPSFsd6MV7pRo"
}

Diğer oyun alanı uç noktaları #

Kampanyalar API hataları #

Kampanya uç noktaları standart hata zarfını döndürür:

{
  "success": false,
  "error": "Campaign not found"
}

Her uç noktanın döndürebileceği ortak kodlar — 401, 403 (planınız API erişimini içermiyor), 429 (hız sınırı) ve 500 — yeniden deneme rehberliği ile birlikte Hatalar ve Sayfalandırma bölümünde listelenmiştir.

İlgili #

• Bir kanalı bir kampanyaya yönlendirin — Giriş Noktalarını kullanarak Instagram, WhatsApp veya yanıtlaması gereken herhangi bir kanalı Yapay Zeka Temsilcisine yönlendirin.
• Yapay zeka ile takip şablonları oluşturun — Bir kampanyanın WhatsApp takip şablonlarını yazan bir arka plan işi başlatın.
• SSS API’si — Kampanyalarınızın kullandığı soru-cevap girişlerini yönetin.
• API Erişimi — API anahtarınızı oluşturun.
• Kimlik Doğrulama — Anahtarınızı iletmenin tüm yolları.