Kişiler API’si #

Bir kişi, mesajlaştığınız tek bir bireydir; adı, telefon numarası, e-postası, kanalı, etiketleri, özel alanları ve dahil olduğu listeler ve kampanyalar bu kapsamdadır. Kişiler API’si, kontrol panelini kullanmadan kişileri oluşturmanıza, aramanıza, güncellemenize, etiketlemenize, toplu olarak içe aktarmanıza ve silmenize olanak tanır.

Bu sayfadaki tüm yollar, temel URL’ye göre belirlenmiştir:

https://api.youraiconnector.com/v1

Yani /contacts ifadesi https://api.youraiconnector.com/v1/contacts anlamına gelir.

API’de yeni misiniz? Öncelikle API Erişimi bölümünü okuyun; bu bölüm API anahtarınızı nasıl oluşturacağınızı, üç kimlik doğrulama yöntemini, hız sınırlarını ve hata biçimini kapsar. Bu sayfadaki her şey, halihazırda çalışan bir API anahtarınız olduğunu varsayar.

Kişi kimlikleri (ID) hakkında #

Her kişinin benzersiz bir kimliği (ID) vardır. Bir kişiyi oluşturduğunuzda (bkz. data.contactId) aldığınız kimlik, diğer her yerde (o kişiyi getirmek, güncellemek, etiketlemek, mesaj göndermek veya silmek için) kullandığınız kimliğin aynısıdır. Bir kez kaydedin ve tekrar kullanın.

Kimliğini almak için bir kişi oluşturmak zorunda değilsiniz. Ayrıca telefon numarası veya e-posta ile arama yapabilir (bkz. Bir kişiyi getir) veya tüm kişilerinizi sayfalayarak listeleyebilirsiniz (bkz. Kişileri listele). Bunların her biri aynı kimliği döndürür.

Bir kişi oluştur #

POST /contacts

Hesabınıza yeni bir kişi ekler. Ülke koduyla birlikte bir telefon numarası zorunludur; sadece e-posta yeterli değildir. Diğer her şey isteğe bağlıdır.

İsteğe bağlı olarak, yeni kişiyi listId (tek bir liste) veya listIds (bir dizi) kullanarak doğrudan bir veya daha fazla listeye ekleyebilirsiniz. Her ikisi de gönderilirse, listIds önceliklidir.

Aşağıdaki Kişi oluşturma alanı tablosunda listelenen standart oluşturma alanlarından biri olmayan gönderdiğiniz her alan (phoneNumber, firstName, lastName, email, channel, is_bot_active, is_private, lead_profile, listId, listIds, custom_fields) otomatik olarak özel alan olarak kaydedilir; bu sayede Make veya Zapier gibi bir araçtan gelen düz bir yük, iç içe yerleştirme gerektirmeden çalışır. Ayrıca açık bir custom_fields nesnesi de iletebilirsiniz.

cURL

curl -X POST "https://api.youraiconnector.com/v1/contacts?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "phoneNumber": "+15551234567",
    "firstName": "Jane",
    "lastName": "Smith",
    "email": "jane@example.com",
    "is_bot_active": true,
    "listIds": ["list123", "list456"]
  }'

JavaScript

const res = await fetch("https://api.youraiconnector.com/v1/contacts", {
  method: "POST",
  headers: {
    "X-API-Key": "YOUR_API_KEY",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    phoneNumber: "+15551234567",
    firstName: "Jane",
    lastName: "Smith",
    email: "jane@example.com",
    is_bot_active: true,
    listIds: ["list123", "list456"],
  }),
});
const data = await res.json();
console.log(data.data.contactId);

Python

import requests

res = requests.post(
    "https://api.youraiconnector.com/v1/contacts",
    headers={"X-API-Key": "YOUR_API_KEY"},
    json={
        "phoneNumber": "+15551234567",
        "firstName": "Jane",
        "lastName": "Smith",
        "email": "jane@example.com",
        "is_bot_active": True,
        "listIds": ["list123", "list456"],
    },
)
print(res.json()["data"]["contactId"])

Yanıt

{
  "success": true,
  "data": {
    "message": "Successfully created new contact",
    "contactId": "contact_abc123",
    "listsAdded": ["list123", "list456"]
  }
}

Yeni kişinin kimliği data.contactId adresindedir. Eklendiği listeler data.listsAdded içinde geri yansıtılır.

Yinelenenler oluşturulmaz. Aynı telefon numarasına sahip bir kişi zaten mevcutsa, oluşturma çağrısı onu oluşturmaz veya döndürmez. Yanıt, HTTP durumu 200 ve gövdesinde 409 değerine sahip bir error_code ile döner, bu nedenle HTTP durumu yerine error_code değerine göre dallanma yapın:

{ "success": false, "error_code": 409, "error": "A contact with this phone number already exists for the current user." }

error_code değeri 409 olan bir işlemden sonra mevcut bir kişiyle çalışmak için, Telefon veya e-posta ile kişi alma yöntemini kullanarak onu arayın — GET /contacts?phoneNumber=... — ve döndürdüğü kimliği (ID) yeniden kullanın.

Eşdeğer WhatsApp yazımları aynı numara olarak sayılır. Bazı ülkelerde aynı mobil hat için iki geçerli yazım biçimi bulunur ve WhatsApp bunlardan herhangi birini bildirebilir: Meksika (+52… ve eski +521…), Brezilya (dokuzuncu hane olsun veya olmasın) ve Arjantin (+54’ten sonra 9 olsun veya olmasın). Oluşturma sırasındaki kopya denetimi ve GET /contacts?phoneNumber=, her iki yazım biçimiyle de eşleşir; bu sayede hangi biçimi gönderirseniz gönderin mevcut kişiyi geri alırsınız. Kişi üzerinde kayıtlı olan phone_number hiçbir zaman yeniden yazılmaz.

Telefon veya e-posta ile kişi getirme #

GET /contacts?phoneNumber=... veya GET /contacts?email=...

Tek bir kişiyi arar ve { id, name } çiftlerine çözümlenmiş listeleri, etiketleri ve kampanyaları ile son mesajlaşmayı içeren tam, zenginleştirilmiş kişi nesnesini döndürür.

Ya phoneNumber (uluslararası formatta) ya da email gönderin. İkisini de göndermezseniz, bu uç nokta bunun yerine Kişileri listele moduna geçer.

cURL

curl "<span data-t="apiBaseUrl">https://api.youraiconnector.com</span>/v1/contacts?phoneNumber=%2B15551234567&apiKey=YOUR_API_KEY"

JavaScript

const phone = encodeURIComponent("+15551234567");
const res = await fetch(`https://api.youraiconnector.com/v1/contacts?phoneNumber=${phone}`, {
  headers: { "X-API-Key": "YOUR_API_KEY" },
});
const data = await res.json();
console.log(data.contact);

Python

import requests

res = requests.get(
    "<span data-t="apiBaseUrl">https://api.youraiconnector.com</span>/v1/contacts",
    headers={"X-API-Key": "YOUR_API_KEY"},
    params={"phoneNumber": "+15551234567"},
)
print(res.json()["contact"])

Yanıt

{
  "success": true,
  "contactId": "contact_abc123",
  "contact": {
    "id": "contact_abc123",
    "firstName": "Jane",
    "lastName": "Smith",
    "email": "jane@example.com",
    "phoneNumber": "+15551234567",
    "channel": "whatsapp",
    "isBotActive": true,
    "isPrivate": false,
    "doNotDisturb": false,
    "lead_profile": null,
    "avatarUrl": "https://example.com/photo.jpg",
    "customFields": {},
    "lists": [{ "id": "list123", "name": "VIP customers" }],
    "tags": [{ "id": "tagHotLead", "name": "Hot lead" }],
    "campaigns": [{ "id": "campaign789", "name": "Spring promo" }],
    "currentCampaign": { "id": "campaign789", "name": "Spring promo" },
    "lastMessage": {
      "direction": "inbound",
      "body": "Sounds good, thanks!",
      "status": "received",
      "timestamp": "2026-06-09T10:21:00.000Z"
    }
  }
}

Kişi kimliği hem en üst düzeyde (contactId) hem de nesnenin içinde (contact.id) döndürülür. Eşleşme olmazsa, { "success": false, "message": "Contact not found" } içeren bir 404 alırsınız.

avatarUrl, kişiye mesaj attığında WhatsApp veya Meta’dan alınan profil fotoğrafıdır. Salt okunurdur: bunu ayarlayamazsınız ve fotoğrafı olmayan veya fotoğraf paylaşmayan bir kanaldan size ulaşan kişiler için null değerindedir. Bu fotoğraf bağlantılarından bazıları süreli olup otomatik olarak yenilendiğinden, bağlantıyı saklamak yerine geçici olarak değerlendirin. (Aşağıdaki liste uç noktasında aynı değer avatar_url olarak adlandırılır.)

URL’lerdeki telefon numaraları. Sorgu dizesindeki bir + işareti %2B olarak URL kodlanmalıdır, aksi takdirde boşluk olarak okunur. Yukarıdaki örnekler bunu sizin için yapar.

Kimlik (ID) ile kişi getirme #

GET /contacts/{contactId}

Bir kişinin kimliğine (ID) zaten sahipseniz, onu doğrudan getirebilirsiniz. Yanıt biçimi yukarıdaki arama ile aynıdır.

cURL

curl "<span data-t="apiBaseUrl">https://api.youraiconnector.com</span>/v1/contacts/contact_abc123?apiKey=YOUR_API_KEY"

JavaScript

const res = await fetch("<span data-t="apiBaseUrl">https://api.youraiconnector.com</span>/v1/contacts/contact_abc123", {
  headers: { "X-API-Key": "YOUR_API_KEY" },
});
const data = await res.json();
console.log(data.contact);

Python

import requests

res = requests.get(
    "<span data-t="apiBaseUrl">https://api.youraiconnector.com</span>/v1/contacts/contact_abc123",
    headers={"X-API-Key": "YOUR_API_KEY"},
)
print(res.json()["contact"])

Hesabınızda bulunmayan bir kişi kimliği, 404 döndürür.

İletişim istatistiklerini al #

GET /contacts/{contactId}/stats

Bir kişi için toplu mesaj istatistiklerini döndürür: toplamlar, yapay zeka ve insan yanıtları, harcanan krediler ve ilk/son mesaj zaman damgaları.

cURL

curl "<span data-t="apiBaseUrl">https://api.youraiconnector.com</span>/v1/contacts/contact_abc123/stats?apiKey=YOUR_API_KEY"

JavaScript

const res = await fetch("<span data-t="apiBaseUrl">https://api.youraiconnector.com</span>/v1/contacts/contact_abc123/stats", {
  headers: { "X-API-Key": "YOUR_API_KEY" },
});
const data = await res.json();
console.log(data.totalMessages, data.creditsUsed);

Python

import requests

res = requests.get(
    "<span data-t="apiBaseUrl">https://api.youraiconnector.com</span>/v1/contacts/contact_abc123/stats",
    headers={"X-API-Key": "YOUR_API_KEY"},
)
data = res.json()
print(data["totalMessages"], data["creditsUsed"])

Yanıt

{
  "success": true,
  "totalMessages": 48,
  "sent": 21,
  "received": 27,
  "aiReplies": 18,
  "humanReplies": 3,
  "creditsUsed": 34,
  "botMessageCount": 18,
  "firstMessageAt": "2026-05-01T09:00:00.000Z",
  "lastMessageAt": "2026-06-09T10:21:00.000Z"
}

botMessageCount, uygulama içindeki “sıfırla” düğmesinin bir kişi için sıfırladığı yapay zeka mesaj sayacıyla aynıdır. creditsUsed, sadece bu yanıtın sayıları değil, bu kişi için devam eden toplam kredi miktarıdır. Hesabınızda bulunmayan bir kişi kimliği 404 döndürür.

Kişileri listeleme #

GET /contacts

Tüm kişilerinizi en yeniden başlayarak sayfalamak için GET /contacts öğesini ne phoneNumber ne de email olmadan çağırın. Her sayfa, kompakt kişi özetleri (listeler, etiketler ve kampanyalar tam nesneler yerine kimlik dizileri olarak döner) ve bir next_cursor döndürür.

Her sayfayı gezmek için: ilk çağrıyı imleç (cursor) olmadan yapın, ardından dönen next_cursor değerini cursor olarak iletmeye devam edin. next_cursor değeri null olduğunda durun — bu, başka sonuç kalmadığı anlamına gelir.

cURL

curl "<span data-t="apiBaseUrl">https://api.youraiconnector.com</span>/v1/contacts?limit=50&apiKey=YOUR_API_KEY"

# next page:
curl "<span data-t="apiBaseUrl">https://api.youraiconnector.com</span>/v1/contacts?limit=50&cursor=contact_abc123&apiKey=YOUR_API_KEY"

JavaScript

async function listAllContacts() {
  const all = [];
  let cursor = null;
  do {
    const url = new URL("<span data-t="apiBaseUrl">https://api.youraiconnector.com</span>/v1/contacts");
    url.searchParams.set("limit", "100");
    if (cursor) url.searchParams.set("cursor", cursor);
    const res = await fetch(url, { headers: { "X-API-Key": "YOUR_API_KEY" } });
    const data = await res.json();
    all.push(...data.contacts);
    cursor = data.next_cursor;
  } while (cursor);
  return all;
}

Python

import requests

def list_all_contacts():
    all_contacts = []
    cursor = None
    while True:
        params = {"limit": 100}
        if cursor:
            params["cursor"] = cursor
        res = requests.get(
            "<span data-t="apiBaseUrl">https://api.youraiconnector.com</span>/v1/contacts",
            headers={"X-API-Key": "YOUR_API_KEY"},
            params=params,
        )
        data = res.json()
        all_contacts.extend(data["contacts"])
        cursor = data["next_cursor"]
        if not cursor:
            break
    return all_contacts

Yanıt

{
  "success": true,
  "contacts": [
    {
      "id": "contact_abc123",
      "first_name": "Jane",
      "last_name": "Smith",
      "email": "jane@example.com",
      "phone_number": "+15551234567",
      "channel": "whatsapp",
      "is_bot_active": true,
      "is_private": false,
      "do_not_disturb": false,
      "avatar_url": "https://example.com/photo.jpg",
      "custom_fields": {},
      "created_at": "2026-06-01T09:00:00.000Z",
      "list_ids": ["list123"],
      "tag_ids": ["tagHotLead"],
      "campaign_ids": ["campaign789"],
      "current_campaign_id": "campaign789"
    }
  ],
  "next_cursor": "contact_abc123"
}

Kişi sayısını al #

GET /contacts/count

Filtreyle eşleşen kaç kişi olduğunu, kanal bazlı dağılımıyla birlikte, sayfalandırma yapmadan döndürür. Bu uç nokta; kontrol paneli kutucukları, otomasyonlar veya Champ’e soru sormak gibi “kaç tane” sorusunun sorulduğu her durum için doğru tercihtir. Tüm filtreler isteğe bağlıdır ve birden fazlasını birleştirmek sayıyı daraltır (bir kişinin gönderdiğiniz her bir filtreyle eşleşmesi gerekir).

Hiç filtre göndermezseniz, hesabınızdaki toplam kişi sayısını alırsınız.

cURL

# everything
curl "<span data-t="apiBaseUrl">https://api.youraiconnector.com</span>/v1/contacts/count?apiKey=YOUR_API_KEY"

# only the contacts one agent handles on Messenger
curl "<span data-t="apiBaseUrl">https://api.youraiconnector.com</span>/v1/contacts/count?agentId=agent_xyz789&channel=messenger&apiKey=YOUR_API_KEY"

JavaScript

const url = new URL("<span data-t="apiBaseUrl">https://api.youraiconnector.com</span>/v1/contacts/count");
url.searchParams.set("agentId", "agent_xyz789");
url.searchParams.set("channel", "messenger");

const res = await fetch(url, { headers: { "X-API-Key": "YOUR_API_KEY" } });
const data = await res.json();
console.log(data.total);

Python

import requests

res = requests.get(
    "<span data-t="apiBaseUrl">https://api.youraiconnector.com</span>/v1/contacts/count",
    headers={"X-API-Key": "YOUR_API_KEY"},
    params={"agentId": "agent_xyz789", "channel": "messenger"},
)
data = res.json()
print(data["total"])

Yanıt

{
  "success": true,
  "total": 3423,
  "by_channel": { "messenger": 2744, "instagram": 667, "none": 12 },
  "filters": { "agentId": "agent_xyz789" }
}

by_channel, aynı toplamı kanal bazında böler; hiçbir kanalda olmayan kişiler none altında sayılır. filters, uygulanan filtreleri geri yansıtır, böylece çağrının istediğiniz işlemi yapıp yapmadığını kontrol edebilirsiniz.

Bir kişiyi güncelle #

PUT /contacts/{contactId}

Mevcut bir kişiyi günceller. Yalnızca dahil ettiğiniz alanlar değiştirilir; dokunmak istemediğiniz hiçbir şeyi göndermeyin. En az bir alan göndermelisiniz, aksi takdirde bir 400 (“Güncellenecek alan yok”) alırsınız.

cURL

curl -X PUT "<span data-t="apiBaseUrl">https://api.youraiconnector.com</span>/v1/contacts/contact_abc123?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "firstName": "Jane", "do_not_disturb": true }'

JavaScript

const res = await fetch("<span data-t="apiBaseUrl">https://api.youraiconnector.com</span>/v1/contacts/contact_abc123", {
  method: "PUT",
  headers: {
    "X-API-Key": "YOUR_API_KEY",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({ firstName: "Jane", do_not_disturb: true }),
});
const data = await res.json();
console.log(data.message);

Python

import requests

res = requests.put(
    "<span data-t="apiBaseUrl">https://api.youraiconnector.com</span>/v1/contacts/contact_abc123",
    headers={"X-API-Key": "YOUR_API_KEY"},
    json={"firstName": "Jane", "do_not_disturb": True},
)
print(res.json()["message"])

Yanıt

{
  "success": true,
  "message": "Contact updated successfully"
}

Özel alanlar değiştirilmez, birleştirilir. { "custom_fields": { "tier": "gold" } } göndermek yalnızca tier değerini ayarlar; kişideki diğer tüm özel alanlar tam olarak oldukları gibi kalır. Bir özel alanı tüm kişiler genelinde tamamen kaldırmak için Özel alanı sil özelliğini kullanın.

Etiket ekle veya kaldır #

POST /contacts/{contactId}/tags

Tek bir çağrıda tek bir kişiye etiket ekler ve/veya kaldırır. Etiket ID’lerini addTagIds ve removeTagIds içinde iletin. İkisinden en az biri boş olmamalıdır.

Etiketler hesabınızda zaten mevcut olmalıdır; bunları önce etiketler uç noktası aracılığıyla oluşturun. Kişi veya referans verilen herhangi bir etiket mevcut değilse, bir 404 alırsınız.

cURL

curl -X POST "<span data-t="apiBaseUrl">https://api.youraiconnector.com</span>/v1/contacts/contact_abc123/tags?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "addTagIds": ["tagHotLead"], "removeTagIds": ["tagColdLead"] }'

JavaScript

const res = await fetch("<span data-t="apiBaseUrl">https://api.youraiconnector.com</span>/v1/contacts/contact_abc123/tags", {
  method: "POST",
  headers: {
    "X-API-Key": "YOUR_API_KEY",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    addTagIds: ["tagHotLead"],
    removeTagIds: ["tagColdLead"],
  }),
});
const data = await res.json();
console.log(data.added, data.removed);

Python

import requests

res = requests.post(
    "<span data-t="apiBaseUrl">https://api.youraiconnector.com</span>/v1/contacts/contact_abc123/tags",
    headers={"X-API-Key": "YOUR_API_KEY"},
    json={"addTagIds": ["tagHotLead"], "removeTagIds": ["tagColdLead"]},
)
data = res.json()
print(data["added"], data["removed"])

Yanıt

{
  "success": true,
  "contact_id": "contact_abc123",
  "added": 1,
  "removed": 1
}

Etiket kitaplığınızı yönetin #

Bu uç noktalar, bir kişiye etiket uygulamak veya kaldırmaktan (yukarıdaki Etiket ekle veya kaldır bölümüne bakın) farklı olarak, etiketin kendisini yönetir; yani hesabınızdaki bir etiketi yeniden adlandırır veya siler. Hesabınızdaki her etiketin bir kimliği (tagId) vardır: bu, kontrol panelinizin etiket yöneticisinde gösterilen ve POST /tags ile { "name": "..." } JSON gövdesi (hiçbir phoneNumber, email veya contactId olmadan) kullanarak bir etiket oluşturduğunuzda data.tag_id olarak döndürülen kimliktir.

Bir etiketi güncelle #

PUT /tags/{tagId}

Yalnızca değiştirdiğiniz alanları gönderin.

curl -X PUT "<span data-t="apiBaseUrl">https://api.youraiconnector.com</span>/v1/tags/tagHotLead?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "name": "Hot lead (Q3)" }'

Yanıt

{ "success": true, "tag_id": "tagHotLead" }

Hesabınızda bulunmayan bir tagId, 404 döndürür.

Bir etiketi sil #

DELETE /tags/{tagId}

Bir etiketi kimliğine göre siler. Bu işlem geri alınamaz — etiketi taşıyan kişiler etiketi kaybeder. Zaten silinmiş (veya hiç var olmamış) bir etiketi silmek, numaralandırılacak bir şey olmadığından 404 yerine deleted: 0 ile 200 döndürür.

curl -X DELETE "<span data-t="apiBaseUrl">https://api.youraiconnector.com</span>/v1/tags/tagColdLead?apiKey=YOUR_API_KEY"

Yanıt

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

Birden fazla etiketi aynı anda sil #

DELETE /tags

curl -X DELETE "<span data-t="apiBaseUrl">https://api.youraiconnector.com</span>/v1/tags?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "tagIds": ["tagColdLead", "tagUnsubscribed"] }'

Yanıt

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

Mevcut olmayan veya başka bir hesaba ait olan kimlikler sessizce atlanır ve deleted içinde sayılmaz.

Toplu bayrak ayarla #

POST /contacts/bulk-flag

Birçok kişide aynı anda bir boolean bayrağı ayarlar. İstek başına en fazla 500 kişi kimliği. Hesabınızda bulunmayan kimlikler atlanır ve skipped içinde sayılır.

cURL

curl -X POST "<span data-t="apiBaseUrl">https://api.youraiconnector.com</span>/v1/contacts/bulk-flag?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "contactIds": ["contactId1", "contactId2"],
    "field": "bot_active",
    "value": false
  }'

JavaScript

const res = await fetch("<span data-t="apiBaseUrl">https://api.youraiconnector.com</span>/v1/contacts/bulk-flag", {
  method: "POST",
  headers: {
    "X-API-Key": "YOUR_API_KEY",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    contactIds: ["contactId1", "contactId2"],
    field: "bot_active",
    value: false,
  }),
});
const data = await res.json();
console.log(data.updated, data.skipped);

Python

import requests

res = requests.post(
    "<span data-t="apiBaseUrl">https://api.youraiconnector.com</span>/v1/contacts/bulk-flag",
    headers={"X-API-Key": "YOUR_API_KEY"},
    json={
        "contactIds": ["contactId1", "contactId2"],
        "field": "bot_active",
        "value": False,
    },
)
data = res.json()
print(data["updated"], data["skipped"])

Yanıt

{
  "success": true,
  "updated": 2,
  "skipped": 0
}

Toplu kişi içe aktarma #

POST /contacts/import

Bir JSON dizisinden tek bir çağrıda 500’e kadar kişi oluşturur. Her kaydın uluslararası formatta bir phone_number değerine ihtiyacı vardır; diğer her şey isteğe bağlıdır. Geçersiz telefon numaralarına veya desteklenmeyen kanallara sahip kayıtlar atlanır (oluşturulmaz) ve atlanan her kayıt, dizini ve nedeni ile birlikte raporlanır; böylece yalnızca hatalı olanları düzeltip yeniden deneyebilirsiniz.

Hesabınızda zaten mevcut olan telefon numaraları varsayılan olarak duplicate şeklinde atlanır. Bunun yerine bu kişileri güncellemek için updateExisting: true gönderin: kayıtta bulunan alanlar kişinin (first_name, last_name, email, lead_profile ve custom_fields anahtar bazında birleştirilir) üzerine yazılır, tags eklenir ve kişi listId listesine eklenir. Mevcut bir kişide kanal, telefon numarası ve bot bayrakları asla değiştirilmez.

İsteğe bağlı olarak, içe aktarılan (veya güncellenen) her kişiyi listId ile bir listeye ekleyebilir, belirtilmeyen kayıtlar için bir defaultChannel ayarlayabilir ve kayıtları tags ile etiketleyebilirsiniz (etiket adları — eksik etiketler oluşturulur, mevcut olanlar büyük/küçük harf duyarsız olarak eşleştirilir).

Üst düzey alanlar

Kayıt bazlı alanlar

cURL

curl -X POST "<span data-t="apiBaseUrl">https://api.youraiconnector.com</span>/v1/contacts/import?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "contacts": [
      { "phone_number": "+12025551234", "first_name": "Ann", "last_name": "Lee", "tags": ["vip", "newsletter"] },
      { "phone_number": "+12025551235", "first_name": "Bob" }
    ],
    "listId": "list123",
    "defaultChannel": "whatsapp_web",
    "updateExisting": true
  }'

JavaScript

const res = await fetch("<span data-t="apiBaseUrl">https://api.youraiconnector.com</span>/v1/contacts/import", {
  method: "POST",
  headers: {
    "X-API-Key": "YOUR_API_KEY",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    contacts: [
      { phone_number: "+12025551234", first_name: "Ann", last_name: "Lee", tags: ["vip", "newsletter"] },
      { phone_number: "+12025551235", first_name: "Bob" },
    ],
    listId: "list123",
    defaultChannel: "whatsapp_web",
    updateExisting: true,
  }),
});
const data = await res.json();
console.log(`Imported ${data.imported}, updated ${data.updated}, skipped ${data.skipped.length}`);

Python

import requests

res = requests.post(
    "<span data-t="apiBaseUrl">https://api.youraiconnector.com</span>/v1/contacts/import",
    headers={"X-API-Key": "YOUR_API_KEY"},
    json={
        "contacts": [
            {"phone_number": "+12025551234", "first_name": "Ann", "last_name": "Lee", "tags": ["vip", "newsletter"]},
            {"phone_number": "+12025551235", "first_name": "Bob"},
        ],
        "listId": "list123",
        "defaultChannel": "whatsapp_web",
        "updateExisting": True,
    },
)
data = res.json()
print(f"Imported {data['imported']}, updated {data['updated']}, skipped {len(data['skipped'])}")

Yanıt

{
  "success": true,
  "imported": 2,
  "contact_ids": ["contact_abc123", "contact_def456"],
  "updated": 0,
  "updated_contact_ids": [],
  "skipped": []
}

Bazı kayıtlar oluşturulamazsa, nedeni ile birlikte skipped içinde görünürler (burada updateExisting olmadan, bu nedenle mevcut numara atlanır):

{
  "success": true,
  "imported": 1,
  "contact_ids": ["contact_abc123"],
  "updated": 0,
  "updated_contact_ids": [],
  "skipped": [
    { "index": 1, "phone_number": "+12025551235", "reason": "duplicate" }
  ]
}

updateExisting: true ile aynı istek, mevcut kişiyi updated / updated_contact_ids altında raporlar.

Olası atlama nedenleri: invalid_record, missing_phone_number, invalid_phone_number, invalid_channel, duplicate_in_request, duplicate, contact_limit_reached, create_failed.

Plan limitleri. Planınızın kişi limiti bu kadar yeni kişiye izin vermiyorsa, isteğin tamamı en başta 403 ile reddedilir. Limit işlem sırasında aşılırsa, kalan kayıtlar contact_limit_reached nedeni ile atlanmış olarak geri döner.

Bir CSV dosyasından kişileri içe aktarma #

Toplu içe aktarma özelliğinin desteklediğinden daha büyük içe aktarmalar için (yaklaşık 50.000 satıra kadar), hesabınızın depolama alanında zaten bulunan bir CSV dosyası için eşzamansız (async) bir içe aktarma işini sıraya alın ve tamamlanana kadar sorgulayın.

İçe aktarmayı başlatma #

POST /contacts/import-csv

curl -X POST "<span data-t="apiBaseUrl">https://api.youraiconnector.com</span>/v1/contacts/import-csv?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "csvStoragePath": "users/abc123/imports/leads.csv",
    "listName": "Webinar signups"
  }'

JavaScript

const res = await fetch("<span data-t="apiBaseUrl">https://api.youraiconnector.com</span>/v1/contacts/import-csv", {
  method: "POST",
  headers: {
    "X-API-Key": "YOUR_API_KEY",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    csvStoragePath: "users/abc123/imports/leads.csv",
    listName: "Webinar signups",
  }),
});
const data = await res.json();
console.log(data.job_id);

Python

import requests

res = requests.post(
    "<span data-t="apiBaseUrl">https://api.youraiconnector.com</span>/v1/contacts/import-csv",
    headers={"X-API-Key": "YOUR_API_KEY"},
    json={
        "csvStoragePath": "users/abc123/imports/leads.csv",
        "listName": "Webinar signups",
    },
)
job_id = res.json()["job_id"]

Yanıt (202 — içe aktarma sıraya alındı, henüz tamamlanmadı)

{
  "success": true,
  "job_id": "csvimp_abc123",
  "status": "queued"
}

Dosyayı depolama alanına alma. Bu uç nokta içe aktarma işini başlatır ve takip eder; dosya yüklemesini doğrudan kabul etmez. CSV dosyasının, siz bu uç noktayı çağırmadan önce csvStoragePath konumunda bulunması gerekir — kontrol panelinin kendi CSV içe aktarıcısı bu işlemi ilk adım olarak gerçekleştirir.

İçe aktarma işini sorgulama #

GET /contacts/import-csv/{jobId}

curl "<span data-t="apiBaseUrl">https://api.youraiconnector.com</span>/v1/contacts/import-csv/csvimp_abc123?apiKey=YOUR_API_KEY"

Yanıt

{
  "success": true,
  "job_id": "csvimp_abc123",
  "status": "completed",
  "imported": 812,
  "updated": 0,
  "skipped": 14,
  "errors": [],
  "error_message": null
}

status, queued → processing → completed aşamalarından geçer veya error_message içindeki neden ile failed durumuna düşer. Hesabınızda bulunmayan bir jobId, 404 döndürür.

Kişileri dışa aktarma #

Kişilerinizin eşzamansız (async) CSV dışa aktarma işlemini başlatır ve tamamlanma durumunu sorgulayabileceğiniz bir iş döndürür.

Dışa aktarmayı başlat #

POST /contacts/export

Her ikisini de boş bırakmak, hesabınızdaki tüm kişileri dışa aktarır.

curl -X POST "<span data-t="apiBaseUrl">https://api.youraiconnector.com</span>/v1/contacts/export?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "listId": "list123" }'

JavaScript

const res = await fetch("<span data-t="apiBaseUrl">https://api.youraiconnector.com</span>/v1/contacts/export", {
  method: "POST",
  headers: {
    "X-API-Key": "YOUR_API_KEY",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({ listId: "list123" }),
});
const data = await res.json();
console.log(data.job_id);

Python

import requests

res = requests.post(
    "<span data-t="apiBaseUrl">https://api.youraiconnector.com</span>/v1/contacts/export",
    headers={"X-API-Key": "YOUR_API_KEY"},
    json={"listId": "list123"},
)
job_id = res.json()["job_id"]

Yanıt (202 — dışa aktarma kuyruğa alındı)

{
  "success": true,
  "job_id": "export_abc123",
  "status": "queued"
}

Dışa aktarma işini sorgula #

GET /contacts/export/{jobId}

curl "<span data-t="apiBaseUrl">https://api.youraiconnector.com</span>/v1/contacts/export/export_abc123?apiKey=YOUR_API_KEY"

Yanıt

{
  "success": true,
  "job_id": "export_abc123",
  "status": "completed",
  "export_id": "exp_xyz789",
  "contact_count": 812,
  "error_message": null
}

status "completed" olduğunda export_id ve contact_count alırsınız. Oluşturulan CSV dosyasını indirme işlemi, kontrol panelinizin Dışa Aktarmalar sayfasından yapılır.

Bir kişiye mesaj gönderin #

POST /contacts/{contactId}/send-message

Mevcut bir kişiye, zaten kullandıkları kanal üzerinden bir mesaj gönderir. Mesaj kuyruğa alınır ve arka planda iletilir; yanıt, mesajın teslim edildiğini değil, kabul edildiğini doğrular.

cURL

curl -X POST "<span data-t="apiBaseUrl">https://api.youraiconnector.com</span>/v1/contacts/contact_abc123/send-message?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "body": "Hi! Your appointment is confirmed." }'

JavaScript

const res = await fetch("<span data-t="apiBaseUrl">https://api.youraiconnector.com</span>/v1/contacts/contact_abc123/send-message", {
  method: "POST",
  headers: {
    "X-API-Key": "YOUR_API_KEY",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({ body: "Hi! Your appointment is confirmed." }),
});
const data = await res.json();
console.log(data.messageId);

Python

import requests

res = requests.post(
    "<span data-t="apiBaseUrl">https://api.youraiconnector.com</span>/v1/contacts/contact_abc123/send-message",
    headers={"X-API-Key": "YOUR_API_KEY"},
    json={"body": "Hi! Your appointment is confirmed."},
)
print(res.json()["messageId"])

Yanıt

{
  "success": true,
  "messageId": "aB3dE5fG7hI9jK1lM2nO",
  "contactId": "contact_abc123",
  "channel": "whatsapp",
  "message": "Message created successfully. Delivery is being processed."
}

Şu anda gönderilemiyor mu? Kişinin rahatsız etmeyin veya gizli modu etkinse ya da giden mesajları alabilen bir kanalda değilse, istek bir 422 ve açıklayıcı bir error ile reddedilir.

Kişi kimliği yerine telefon numarası, Instagram kimliği veya diğer kanal kimlikleri ile göndermek için — ve genel olarak mesajlaşma hakkında daha fazla bilgi için — Messages API bölümüne bakın.

Bir kişiye yapay zeka temsilcisi atayın #

POST /contacts/{contactId}/assign-agent

Mevcut bir konuşmayı, bir sonraki mesajdan itibaren farklı bir yapay zeka temsilcisine taşır. Bu, bir sohbetin menüsündeki Yapay Zeka Temsilcisi Ata seçeneğiyle ve Otomasyonlardaki Yapay zeka temsilcisi veya kampanya ata eyleminin kullandığı adımla aynıdır.

triggerAIResponse: true ile dikkatli olun — kişiye o anda bir mesaj gönderir, bu yüzden yalnızca hemen mesajlaşmak istediğinizde kullanın. Messenger ve Instagram’da, kişi size en son 24 saatten daha uzun süre önce yazdıysa bu mesaj başarısız olur.

cURL

curl -X POST "<span data-t="apiBaseUrl">https://api.youraiconnector.com</span>/v1/contacts/contact_abc123/assign-agent?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "agentId": "agent_xyz789" }'

JavaScript

const res = await fetch("<span data-t="apiBaseUrl">https://api.youraiconnector.com</span>/v1/contacts/contact_abc123/assign-agent", {
  method: "POST",
  headers: {
    "X-API-Key": "YOUR_API_KEY",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({ agentId: "agent_xyz789" }),
});
const data = await res.json();
console.log(data.data.agentId);

Python

import requests

res = requests.post(
    "<span data-t="apiBaseUrl">https://api.youraiconnector.com</span>/v1/contacts/contact_abc123/assign-agent",
    headers={"X-API-Key": "YOUR_API_KEY"},
    json={"agentId": "agent_xyz789"},
)
print(res.json()["data"]["agentId"])

Yanıt

{
  "success": true,
  "data": {
    "contactId": "contact_abc123",
    "agentId": "agent_xyz789",
    "aiResponseTriggered": false
  }
}

Temsilci, kişiyle aynı hesaba ait olmalıdır; aksi takdirde istek bir 404 veya 403 ile reddedilir. Temsilci kimliklerini Yapay Zeka Temsilcileri sayfasında bulabilirsiniz (her temsilcinin URL’si kendi kimliğiyle biter).

Birçok kişiye yapay zeka temsilcisi atama #

POST /contacts/bulk-assign-agent

Birçok görüşmeyi tek bir çağrıda farklı bir yapay zeka temsilcisine taşır veya null ile hepsinin atamasını temizler. Bu tamamen bir yönlendirme değişikliğidir: hiçbir mesaj gönderilmez ve temsilci kimseye yanıt vermez. Her kişi, bir sonraki yazışmasında yeni temsilciye atanmış olur. (Bu yüzden burada triggerAIResponse yoktur.)

contactIds, filter veya rules değerlerinden tam olarak birini gönderin.

cURL

curl -X POST "<span data-t="apiBaseUrl">https://api.youraiconnector.com</span>/v1/contacts/bulk-assign-agent?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "agentId": "agent_xyz789",
    "filter": { "agentId": "agent_abc123", "channel": "messenger" }
  }'

JavaScript

const res = await fetch("<span data-t="apiBaseUrl">https://api.youraiconnector.com</span>/v1/contacts/bulk-assign-agent", {
  method: "POST",
  headers: {
    "X-API-Key": "YOUR_API_KEY",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    agentId: "agent_xyz789",
    filter: { agentId: "agent_abc123", channel: "messenger" },
  }),
});
const data = await res.json();
console.log(data.updated, data.remaining);

Python

import requests

res = requests.post(
    "<span data-t="apiBaseUrl">https://api.youraiconnector.com</span>/v1/contacts/bulk-assign-agent",
    headers={"X-API-Key": "YOUR_API_KEY"},
    json={
        "agentId": "agent_xyz789",
        "filter": {"agentId": "agent_abc123", "channel": "messenger"},
    },
)
data = res.json()
print(data["updated"], data["remaining"])

Yanıt

{
  "success": true,
  "agentId": "agent_xyz789",
  "matched": 3415,
  "updated": 500,
  "skipped": 0,
  "remaining": 2915,
  "filters": { "agentId": "agent_abc123" }
}

matched, seçimin toplamda kaç kişi bulduğudur, updated bu çağrıyla kaç kişinin taşındığıdır, skipped gönderdiğiniz kimliklerden kaçının hesabınızda bulunamadığıdır ve remaining bu çağrı bittiğinde hala kaç kişinin eşleştiğidir.

Herkesi taşıma. Bir çağrı en fazla 500 kişiyi taşıdığından, büyük bir grup birkaç çağrı gerektirir. Bir kişi taşındıktan sonra eşleşmeyi durduran bir filtre kullanın — örneğin agent_xyz789’e atarken filter: { "agentId": "agent_abc123" } kullanın — ve remaining değeri 0 olarak dönene kadar aynı çağrıyı tekrarlayın. Bunun yerine contactIds gönderdiğinizde, remaining her zaman 0 olur.

Bir kişiyi departmana ata #

POST /contacts/{contactId}/department

“Bu adayı Satış departmanına ata” — bir kişiyi adlandırılmış bir departman altında dosyalar ve varsayılan olarak, o departmanda şu anda en az kişiye sahip olan kişiye yönlendirir. Bu, bir yapay zeka temsilcisi atamaktan ayrıdır: bir departman “bunun sahibi hangi ekip” sorusunu yanıtlar, bir temsilci “bunu hangi yapay zeka yanıtlar” sorusunu yanıtlar ve birini ayarlamak diğerini asla temizlemez.

cURL

curl -X POST "<span data-t="apiBaseUrl">https://api.youraiconnector.com</span>/v1/contacts/contact_abc123/department?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "department_id": "dept_sales" }'

JavaScript

const res = await fetch("<span data-t="apiBaseUrl">https://api.youraiconnector.com</span>/v1/contacts/contact_abc123/department", {
  method: "POST",
  headers: {
    "X-API-Key": "YOUR_API_KEY",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({ department_id: "dept_sales" }),
});
const data = await res.json();
console.log(data.assigned_to);

Python

import requests

res = requests.post(
    "<span data-t="apiBaseUrl">https://api.youraiconnector.com</span>/v1/contacts/contact_abc123/department",
    headers={"X-API-Key": "YOUR_API_KEY"},
    json={"department_id": "dept_sales"},
)
print(res.json()["assigned_to"])

Yanıt

{
  "success": true,
  "department_id": "dept_sales",
  "assigned_to": "member_uid_123"
}

assigned_to, kişi zaten birine ait olduğunda veya hand_to_member: false değerini ilettiğinizde null olur.

Bir kişiyi kanallar arasında bağla #

“WhatsApp’ta devam et” (veya SMS), bu kişinin iletişim bilgilerini başka bir telefon tabanlı kanalda bulur veya oluşturur ve uygulamanın geri kalanının onları aynı kişi olarak tanıması için ikisini birbirine bağlar.

Başka bir kanala bağlantı kurma #

POST /contacts/{contactId}/link-channel

curl -X POST "<span data-t="apiBaseUrl">https://api.youraiconnector.com</span>/v1/contacts/contact_abc123/link-channel?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "channel": "sms" }'

Yanıt

{
  "success": true,
  "data": {
    "contact_id": "contact_def456",
    "person_id": "person_xyz789",
    "created": true
  }
}

created, hedef kanal için yeni bir kişi oluşturulup oluşturulmadığını veya mevcut bir kişinin bulunup bağlanıp bağlanmadığını size bildirir. Bunu ikinci kez çağırmak güvenlidir; kopya oluşturmak yerine created: false ile aynı contact_id değerini döndürür.

422, hesabın bu bağlantıyı şu anda gerçekleştiremeyeceği anlamına gelir: kişi zaten o kanal ailesindedir, kullanılacak bir telefon numarası yoktur veya hedef kanal için bağlı bir gönderici bulunmamaktadır. 409 ise iki kişinin zaten iki farklı kişiye bağlı olduğu anlamına gelir; önce birinin bağlantısını kesin.

Bir kişinin bağlı görüşmelerini listeleme #

GET /contacts/{contactId}/linked

Bu kişiyle aynı kişi olan diğer görüşmeleri döndürür. Bağlantısı olmayan bir kişi, 404 yerine boş bir dizi döndürür; “bu kişinin başka kanalı yok” durumu normal bir durumdur.

curl "<span data-t="apiBaseUrl">https://api.youraiconnector.com</span>/v1/contacts/contact_abc123/linked?apiKey=YOUR_API_KEY"

Yanıt

{
  "success": true,
  "data": [
    {
      "contact_id": "contact_def456",
      "channel": "sms",
      "custom_channel": null,
      "first_name": "Jane",
      "last_name": "Smith",
      "phone_number": "+15551234567",
      "last_message": "Sounds good, thanks!",
      "last_message_timestamp": "2026-06-09T10:21:00.000Z",
      "linked_from": {
        "contact_id": "contact_abc123",
        "channel": "whatsapp",
        "linked_at": "2026-06-01T09:00:00.000Z",
        "reason": "continue_on_channel"
      }
    }
  ]
}

Bir kişinin bağlantısını kesme #

DELETE /contacts/{contactId}/link

Bu kişiyi, tek taraflı olarak bağlı olduğu kişiden ayırır; o kişiye bağlı olan diğer kişiler bağlantılarını korur, bu nedenle üç kişiden birinin bağlantısını kesmek grubu dağıtmaz.

curl -X DELETE "<span data-t="apiBaseUrl">https://api.youraiconnector.com</span>/v1/contacts/contact_abc123/link?apiKey=YOUR_API_KEY"

Yanıt

{ "success": true }

Bir kişinin profil resmini getirme #

POST /contacts/{contactId}/profile-pic

Kişinin WhatsApp veya Meta profil fotoğrafını talep üzerine getirir (ve önbelleğe alır); bu, Kişi getirme işleminde avatarUrl olarak döndürülen fotoğrafın aynısıdır ve yenilenmiştir.

curl -X POST "<span data-t="apiBaseUrl">https://api.youraiconnector.com</span>/v1/contacts/contact_abc123/profile-pic?apiKey=YOUR_API_KEY"

Yanıt

{
  "success": true,
  "avatar_url": "https://example.com/photo.jpg",
  "cached": false
}

cached: true, URL’nin yeni bir sağlayıcı sorgusu yerine yakın zamandaki bir getirme işleminden geldiği anlamına gelir; resimler 7 gün boyunca önbelleğe alınır ve sağlayıcının ulaşılabilir bir fotoğrafı olmadığını bildirdiği bir kişi, 24 saat boyunca kullanılamaz olarak önbelleğe alınır. Getirilecek bir resim olmadığında avatar_url atlanır ve message bunun nedenini açıklar.

Kişileri yapay zeka ile otomatik etiketleme #

Hesabınızın etiket kurallarını bir veya daha fazla kişinin tüm konuşma geçmişi üzerinde çalıştırır ve tıpkı canlı sohbet sırasında çalışan gerçek zamanlı etiketlemede olduğu gibi etiketleri uygular (veya kaldırır) — aynı kurallar, etiket başına aynı kredi maliyeti geçerlidir.

Bir çalıştırma başlatın #

POST /contacts/auto-tag

curl -X POST "<span data-t="apiBaseUrl">https://api.youraiconnector.com</span>/v1/contacts/auto-tag?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "scope": "contacts", "contact_ids": ["contact_abc123", "contact_def456"] }'

Tek bir kişi satır içi olarak çalışır ve sonucu hemen döndürür:

{ "success": true, "result": { "tags_applied": 2, "tags_removed": 0 } }

İki veya daha fazla kişi (veya scope: "agent") arka plan işi olarak çalışır ve hemen 202 döndürür:

{ "success": true, "run_id": "m1x2y3-a1b2c3d4", "total": 214 }

Bir çalıştırmayı sorgulayın #

GET /contacts/auto-tag/run

Hesabın mevcut (veya en son) çalıştırmasını döndürür, böylece run_id takibini kendiniz yapmadan ilerlemeyi sorgulayabilirsiniz.

curl "<span data-t="apiBaseUrl">https://api.youraiconnector.com</span>/v1/contacts/auto-tag/run?apiKey=YOUR_API_KEY"

Yanıt

{
  "success": true,
  "run": {
    "run_id": "m1x2y3-a1b2c3d4",
    "status": "running",
    "total": 214,
    "processed": 58,
    "tagged_contacts": 12,
    "tags_applied": 15,
    "tags_removed": 2,
    "credits_charged": 15
  }
}

Hesap hiç çalıştırma başlatmadığında run, null değerindedir. status, "running" durumundan "completed" veya "failed" durumuna geçer.

Hesap başına aynı anda yalnızca bir toplu çalıştırma devam edebilir; başka bir çalıştırma devam ederken ikincisini başlatmak error_code: "auto_tag_run_in_progress" ile 409 döndürür. Tek kişilik bir çalıştırmada kredinin bitmesi error_code: "insufficient_credits" ile 402 döndürür; toplu çalıştırma ise bunun yerine erken durur ve run içinde ne kadar ilerlediğini bildirir.

Bir kişiyi silin #

DELETE /contacts/{contactId}

Bir kişiyi kimliğiyle birlikte mesaj geçmişiyle beraber kalıcı olarak siler. Bu işlem geri alınamaz. Tek bir çağrıda birden fazla kişiyi silmek için aşağıdaki Kişileri sil kısmını kullanın.

cURL

curl -X DELETE "<span data-t="apiBaseUrl">https://api.youraiconnector.com</span>/v1/contacts/contact_abc123?apiKey=YOUR_API_KEY"

JavaScript

const res = await fetch("<span data-t="apiBaseUrl">https://api.youraiconnector.com</span>/v1/contacts/contact_abc123", {
  method: "DELETE",
  headers: { "X-API-Key": "YOUR_API_KEY" },
});
const data = await res.json();
console.log(data.success);

Python

import requests

res = requests.delete(
    "<span data-t="apiBaseUrl">https://api.youraiconnector.com</span>/v1/contacts/contact_abc123",
    headers={"X-API-Key": "YOUR_API_KEY"},
)
print(res.json()["success"])

Yanıt

{
  "success": true
}

Hesabınızda bulunmayan veya farklı bir hesaba ait olan bir kişi kimliği, 404 döndürür.

Kişileri sil #

DELETE /contacts

Tek bir çağrıda (500 kimliğe kadar) bir veya daha fazla kişiyi kimliklerine göre kalıcı olarak siler. Hesabınızda bulunmayan kimlikler atlanır ve skipped içinde sayılır. Bu işlem geri alınamaz.

cURL

curl -X DELETE "<span data-t="apiBaseUrl">https://api.youraiconnector.com</span>/v1/contacts?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "contactIds": ["contactId1", "contactId2"] }'

JavaScript

const res = await fetch("<span data-t="apiBaseUrl">https://api.youraiconnector.com</span>/v1/contacts", {
  method: "DELETE",
  headers: {
    "X-API-Key": "YOUR_API_KEY",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({ contactIds: ["contactId1", "contactId2"] }),
});
const data = await res.json();
console.log(`Deleted ${data.deleted}, skipped ${data.skipped}`);

Python

import requests

res = requests.delete(
    "<span data-t="apiBaseUrl">https://api.youraiconnector.com</span>/v1/contacts",
    headers={"X-API-Key": "YOUR_API_KEY"},
    json={"contactIds": ["contactId1", "contactId2"]},
)
data = res.json()
print(f"Deleted {data['deleted']}, skipped {data['skipped']}")

Yanıt

{
  "success": true,
  "deleted": 2,
  "skipped": 0
}

Özel bir alanı silme #

DELETE /contacts/custom-fields/{fieldKey}

Hesabınızdaki her kişiden bir özel alan anahtarını kaldırır. Bunu, özel bir alanı yeniden adlandırdıktan veya kullanımdan kaldırdıktan sonra temizlik yapmak için kullanın. Anahtar yalnızca harfler, rakamlar, alt çizgiler ve kısa çizgiler içerebilir. Kaç kişinin güncellendiğini döndürür. Bu işlem geri alınamaz.

cURL

curl -X DELETE "<span data-t="apiBaseUrl">https://api.youraiconnector.com</span>/v1/contacts/custom-fields/webinar_date_nh?apiKey=YOUR_API_KEY"

JavaScript

const res = await fetch("<span data-t="apiBaseUrl">https://api.youraiconnector.com</span>/v1/contacts/custom-fields/webinar_date_nh", {
  method: "DELETE",
  headers: { "X-API-Key": "YOUR_API_KEY" },
});
const data = await res.json();
console.log(`Removed from ${data.updated} contacts`);

Python

import requests

res = requests.delete(
    "<span data-t="apiBaseUrl">https://api.youraiconnector.com</span>/v1/contacts/custom-fields/webinar_date_nh",
    headers={"X-API-Key": "YOUR_API_KEY"},
)
print(f"Removed from {res.json()['updated']} contacts")

Yanıt

{
  "success": true,
  "updated": 42
}

Listeler #

Listeler kişileri gruplandırır. Bir liste ya statik (kimin listede olacağına siz karar verirsiniz) ya da akıllı (üyelik kurallara göre hesaplanır ve otomatik olarak güncel tutulur — bkz. Listeleri ve Kişileri Düzenleme) olabilir.

Liste oluşturma #

POST /lists

curl -X POST "<span data-t="apiBaseUrl">https://api.youraiconnector.com</span>/v1/lists?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
        "name": "Hot leads (active)",
        "type": "smart",
        "smart_rules": {
          "match": "all",
          "conditions": [
            { "field": "tags", "op": "has_any", "value": ["tagHotLead"] },
            { "field": "last_activity_at", "op": "within_last", "value": { "amount": 90, "unit": "days" } }
          ]
        }
      }'

Yanıt

{
  "success": true,
  "list_id": "list_abc123",
  "evaluation": { "added": 3, "removed": 0, "total": 3 }
}

Akıllı bir liste, aynı istek içinde satır içi olarak değerlendirilir, bu nedenle evaluation size tam olarak kimin listede yer aldığını söyler. Statik bir listede evaluation, null değerindedir.

Liste güncelleme #

PUT /lists/{listId}

Yalnızca değiştirdiğiniz alanları gönderin. smart_rules değerini değiştirmek listeyi anında yeniden değerlendirir ve aynı evaluation nesnesini döndürür.

curl -X PUT "<span data-t="apiBaseUrl">https://api.youraiconnector.com</span>/v1/lists/list_abc123?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "smart_rules": { "match": "any", "conditions": [ { "field": "tags", "op": "has_any", "value": ["tagHotLead", "tagWebinar"] } ] } }'

Bir listeyi iki tür arasında değiştirebilirsiniz:

• Statik → akıllı: { "type": "smart", "smart_rules": { … } } gönderin. Kurallar anında devreye girer.
• Akıllı → statik: { "type": "static" } gönderin. Kurallar kaldırılır ve listede kim varsa orada kalmaya devam eder.

smart_rules yapısı #

{
  "match": "all",
  "conditions": [
    { "field": "tags", "op": "has_any", "value": ["tagHotLead"] },
    { "field": "channel", "op": "is_any", "value": ["whatsapp", "sms"] },
    { "field": "last_incoming_message_at", "op": "not_within_last", "value": { "amount": 7, "unit": "days" } },
    { "field": "created_at", "op": "after", "value": "2026-01-01" },
    { "field": "is_bot_active", "op": "is", "value": true },
    { "field": "email", "op": "is_set" },
    { "field": "custom_field", "key": "Plan", "op": "eq", "value": "pro" }
  ]
}

• match — all (her koşul doğru olmalıdır) veya any (en az biri).
• conditions — 1 ila 20 koşul, her biri en fazla 100 değer, 200 karaktere kadar dizeler.

not_within_last ayrıca tarihin hiç ayarlanmadığı kişileri de eşleştirir (“N’den daha önce, veya hiç”), ve metin karşılaştırmaları büyük/küçük harf duyarlılığını göz ardı eder.

Yapay zeka etkileşimi. has_interacted_with_ai yaşam boyu bayrağıdır: Yapay zekanızın en az bir mesaj gönderdiği her kişi için true, diğer herkes için (yalnızca ekibinizin yanıt verdiği kişiler dahil) false. Bu bayrak, yapay zekanın bir kişiye gönderdiği ilk mesaja damgalanır ve asla silinmez; bu nedenle kişinin yapay zeka yanıtlarını kapatmak veya onları başka bir kampanyaya taşımak bunu sıfırlamaz. Bir dönem için — “yapay zekamın bu ay ilgilendiği kişiler”, yani genel faturalandırma sorusu — bunun yerine last_ai_interaction_at aralığını kullanın:

{ "field": "last_ai_interaction_at", "op": "within_last", "value": { "amount": 30, "unit": "days" } }

Bunların hiçbirini is_bot_active (yapay zekanın yanıt vermesine izin verilmiştir, yanıt verdiği anlamına gelmez) veya has_ever_responded (kişi herhangi birine geri yazmıştır) ile karıştırmayın. Aynı iki damga her kişide first_ai_interaction_at / last_ai_interaction_at olarak döndürülür ve tüm kural kümesi GET /contacts?rules= üzerinde de çalışır, böylece bir liste oluşturmadan eşleşmeleri sayabilirsiniz.

Bir kural kümesini önizleyin #

POST /lists/preview

Hiçbir şeyi oluşturmadan veya değiştirmeden, bir kural kümesinin eşleşeceği kişileri sayar ve örneklendirir. Kuralları kaydetmeden önce doğruluğunu kontrol etmek için kullanın.

curl -X POST "<span data-t="apiBaseUrl">https://api.youraiconnector.com</span>/v1/lists/preview?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "smart_rules": { "match": "all", "conditions": [ { "field": "tags", "op": "has_any", "value": ["tagHotLead"] } ] } }'

Yanıt

{
  "success": true,
  "count": 3,
  "sample": [
    {
      "id": "contact_abc123",
      "first_name": "Sofia",
      "last_name": "Martinez",
      "phone_number": "+31600000000",
      "email": "sofia@example.com",
      "channel": "whatsapp"
    }
  ]
}

sample, en son aktif olandan başlayarak 10 kişiye kadar tutar.

Akıllı listeyi şimdi yeniden çalıştırın #

POST /lists/{listId}/evaluate

Anında yeniden değerlendirmeyi zorunlu kılar (paneldeki Şimdi yenile ile aynı işlevi görür). Akıllı listeler zaten bir kişi değiştiğinde ve zamana dayalı kurallar için her 15 dakikada bir güncellenir, bu nedenle bu işlem yalnızca sonucu hemen şimdi istediğinizde gereklidir.

Yanıt

{
  "success": true,
  "list_id": "list_abc123",
  "evaluation": { "added": 2, "removed": 1, "total": 4 }
}

evaluation.skipped: true, aynı listenin başka bir değerlendirmesinin zaten çalışmakta olduğu ve bu çağrının hiçbir şey yapmadığı anlamına gelir.

Akıllı listeler elle seçilen üyeleri kabul etmez #

Üyelik uç noktaları, hedef liste akıllı olduğunda "This is a smart list — its members are computed from its rules. Edit the rules instead." ile 409 döndürür. Bu durum POST /contacts/lists, DELETE /contacts/lists, POST /contacts/lists/batch, contact_ids üzerindeki POST /lists ve PUT /lists/{listId} işlemlerini ve CSV içe aktarma hedefi olarak bir akıllı liste seçmeyi kapsar. Bunun yerine kuralları değiştirin.

Statik bir listede POST /lists/{listId}/evaluate çağırmak da bir 409 hatasıdır; çünkü çalıştırılacak kuralları yoktur.

Kişiler API hataları #

Kişi uç noktaları standart hata zarfını döndürür:

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

Bazı uç noktalar, genellikle HTTP durumuyla eşleşen error_code değerini de içerir; bunun tek istisnası, HTTP durumunun 200 olduğu ve yalnızca error_code değerinin 409 bilgisini taşıdığı aşağıdaki yinelenen kişi durumudur. Kişi uç noktalarına özgü kodlar şunlardır:

Bir kişi uç noktasındaki 403, plan erişiminden ziyade kişi sınırı veya liste izni sorunu anlamına da gelebilir. 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.

Sonraki adımlar #

• Mesajlar API’si — kanal kimliğine göre mesaj gönderin ve konuşmaları yönetin.
• API Başvurusu — etiketler ve listeler dahil olmak üzere tam uç nokta listesi.
• API Erişimi — kimlik doğrulama, hız sınırları ve hata işleme.