Mesajlar ve Konuşmalar #

Messages API, herhangi bir kişiye mesaj göndermenize, bir konuşmayı okumanıza, gönderdiğiniz bir mesajı düzeltmenize veya silmenize, bir mesaja tepki vermenize, tam bir sohbet oturumu dizisini çekmenize, bir dökümü dışa aktarmanıza ve sohbetleri okundu veya okunmadı olarak işaretlemenize olanak tanır; üstelik tüm bunları gelen kutusunu açmadan yapabilirsiniz.

Bu sayfadaki tüm yollar https://api.youraiconnector.com/v1 temel URL’sine göredir. Her istek API anahtarınızı gerektirir — gönderme yollarının tam listesi için Kimlik Doğrulama bölümüne bakın. Aşağıdaki örnekler X-API-Key başlığını kullanır; bir cURL örneği ise ?apiKey= sorgu biçimini de gösterir.

Teslimat nasıl çalışır: Bir mesaj göndermek, mesajın ulaşmasını beklemez. API mesajınızı kabul eder, hemen bir mesaj kimliği ile yanıt verir ve ardından mesajı arka planda kişinin kanalında (WhatsApp, SMS, Instagram vb.) teslim eder. Bir mesajın gerçekten teslim edilip edilmediğini veya okunup okunmadığını takip etmek için Webhooks ile durum güncellemelerini dinleyin; yoklama (polling) yapmayın. Gönderme yanıtı yalnızca mesajın kabul edildiğini onaylar.

Mesaj gönder #

Göndermenin iki yolu vardır. Kişiyi halihazırda nasıl tanımladığınıza uygun olanı seçin:

• Kişi kimliği ile gönder — kişinin kimliğini zaten biliyorsunuz (örneğin, kişiyi API aracılığıyla oluşturdunuz veya bir web kancasından aldınız). POST /contacts/{contactId}/send-message kullanın.
• Kişi kimliği (identity) ile gönder — kişinin telefon numarasını, Instagram kimliğini vb. biliyorsunuz ancak dahili kimliğini bilmiyorsunuz. POST /contacts/send kullanın ve platformun doğru kişiyi bulmasını sağlayın.

Her ikisi de mesajı aynı şekilde sıraya alır ve kişinin bulunduğu kanaldan teslim eder. Bir taşıma yöntemi seçmezsiniz; platform, WhatsApp kişilerini WhatsApp üzerinden, SMS kişilerini SMS üzerinden vb. yönlendirir.

Her ikisi de yalnızca halihazırda var olan kişileri bulur. Hiçbir çağrı yeni bir kişi oluşturmaz: eşleşme bulunamadığında dönen ID veya kimlik 404 değerindedir, yeni bir kişi oluşturulmaz. Bu nedenle, biriyle ilk kez mesajlaşıyorsanız, ya önce POST /contacts ile kişiyi oluşturun ya da WhatsApp Web’de aşağıda yer alan Doğrudan bir WhatsApp Web numarasına gönder seçeneğini kullanın; bu seçenek aynı çağrı içinde kişiyi de oluşturur.

Kişi kimliği ile gönder #

POST /contacts/{contactId}/send-message

LinkedIn’de bu şekilde veya gelen kutusundan gönderdiğiniz bir mesaj, kişi LinkedIn tarafında yazışmayı yönetirken bile iletilir. Yapay zekanın kendi yanıtları ve takip mesajları böyle bir yazışmada bekletilir. Bekletilen bir yanıt, başarısız olarak gösterilmek yerine sohbetten kaldırılır; çünkü hiçbir şey gönderilmemiştir ve herhangi bir kredi kullanılmamıştır. Yapay zekanın bir yazışmayı bir kişiye devretmeden önceki son yanıtı iletilmeye devam eder.

cURL

curl -X POST "https://api.youraiconnector.com/v1/contacts/contact123/send-message" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "body": "Hi! Your appointment is confirmed for tomorrow at 10:00."
  }'

JavaScript

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

Python

import requests

res = requests.post(
    "https://api.youraiconnector.com/v1/contacts/contact123/send-message",
    headers={
        "X-API-Key": "YOUR_API_KEY",
        "Content-Type": "application/json",
    },
    json={"body": "Hi! Your appointment is confirmed for tomorrow at 10:00."},
)
print(res.json()["messageId"])

Yanıt (200 OK):

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

Kişi kimliği (identity) ile gönder #

POST /contacts/send

Bunu, kişinin dahili kimliğine sahip olmadığınızda kullanın. Mesaj body değerini ve ya bir contact_id ya da o kanalla eşleşen kimlik alanı ile birlikte bir channel sağlayın.

Hangi kanallar kimlik bilgisi ile çözümlenebilir. 14 kanaldan sadece altısı contact_id yerine bir kimlik alanı kabul eder: whatsapp, whatsapp_web ve sms, phone_number ile; instagram, instagram_id ile; messenger, messenger_id ile ve telegram, telegram_user_id ile aranır. Diğer sekizi — instagram_private, chat-widget, custom, email, line, imessage, linkedin ve viber — aranabilecek genel bir kimliğe sahip değildir, bu nedenle bu kanallar üzerinden gönderim yapmak contact_id gerektirir; yalnızca channel geçmek, contact_id bilgisinin gerekli olduğunu belirten bir 400 döndürür.

cURL (?apiKey= sorgu formunu kullanarak)

curl -X POST "https://api.youraiconnector.com/v1/contacts/send?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "channel": "whatsapp",
    "phone_number": "+31612345678",
    "body": "Hi! Your appointment is confirmed."
  }'

JavaScript

const res = await fetch("https://api.youraiconnector.com/v1/contacts/send", {
  method: "POST",
  headers: {
    "X-API-Key": "YOUR_API_KEY",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    channel: "whatsapp",
    phone_number: "+31612345678",
    body: "Hi! Your appointment is confirmed.",
  }),
});
const data = await res.json();
console.log(data.message_id, data.channel);

Python

import requests

res = requests.post(
    "https://api.youraiconnector.com/v1/contacts/send",
    headers={
        "X-API-Key": "YOUR_API_KEY",
        "Content-Type": "application/json",
    },
    json={
        "channel": "whatsapp",
        "phone_number": "+31612345678",
        "body": "Hi! Your appointment is confirmed.",
    },
)
data = res.json()
print(data["message_id"], data["channel"])

Yanıt (201 Created):

{
  "success": true,
  "message_id": "aB3dE5fG7hI9jK1lM2nO",
  "contact_id": "contact123",
  "channel": "whatsapp"
}

Bir mesaj neden reddedilebilir: Rahatsız etmeyin veya gizli modu açık olan bir kişi giden mesajları alamaz — istek 422 hatasıyla başarısız olur. Sağladığınız kimlik veya tanımlayıcı ile eşleşen bir kişi yoksa, 404 alırsınız.

WhatsApp Web üzerinden gönderim: varyasyonlar ve toplu gönderim koruması #

Kişi WhatsApp Web üzerindeyken body için iki durum geçerlidir.

Spintax parantezleri her gönderimde genişletilir. body içeren bir {Hi|Hello|Hey} there, quick question, o gönderim için seçilen üç selamlamadan biri olarak iletilir; parantezler asla kişiye ulaşmaz. Bunu, aynı entegrasyon koduyla her kişiye farklı bir açılış mesajı göndermek için kullanın. Parantez içermeyen metinler tam olarak yazıldığı gibi gönderilir.

Birbirinin aynısı olan açılış mesajlarının toplu gönderimi reddedilir. Bir saat içinde bir WhatsApp Web numarasından, size daha önce hiç yazmamış kişilere on adet birbirine çok yakın açılış mesajı gönderilirse, sonraki mesajlar iletilmez: gönderim her zamanki gibi kabul edilir (yine de bir messageId alırsınız) ve mesaj daha sonra status: "failed" ve error_code: "opener_burst" ile bırakılır; üzerinde müşteri tarafından okunabilir bir neden belirtilir. Aynı metni tekrar denemek işe yaramaz; metni değiştirin, bir saat bekleyin ve tekrar gönderin. Mevcut konuşmalar içindeki yanıtlar bundan asla etkilenmez. Bunun nedeni Aynı açılış mesajları numaraların kısıtlanmasına yol açar bölümünde açıklanmıştır.

Doğrudan bir WhatsApp Web numarasına gönder #

POST /whatsapp-web/send

Önce bir kişiyi aratmadan WhatsApp Web’de bir telefon numarasına mesaj gönderin. Numara henüz bir kişi değilse, kişi aynı çağrı içinde oluşturulur ve üzerinde yapay zeka kapalı tutulur; böylece mesaj sanki elinizle göndermişsiniz gibi görünür ve sonrasında hiçbir asistan konuşmayı devralmaz. Mevcut bir kişi ise olduğu gibi kullanılır.

curl -X POST "https://api.youraiconnector.com/v1/whatsapp-web/send?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "phoneNumber": "+31612345678",
    "message": "Hi Alex, your quote is ready."
  }'

Başarılı bir çağrı 202 yanıtını verir:

{ "success": true, "queued": true, "contactId": "abc123" }

202 kabul edildiği anlamına gelir, henüz teslim edilmemiştir. ignoreActiveHours parametresini göndermediğiniz sürece, aktif saatler dışındaysa gönderim bekletilir ve bir sonraki izin verilen zaman diliminde gerçekleştirilir. Mesajın kendi durumunu, buradan aldığınız contactId değerini kullanarak Bir kişinin mesajlarını listele ile kontrol edin.

Gönderim gerçekleşmediğinde:

Bekleyen bir gönderim varken aynı kişi için yapılan ikinci bir çağrı 409 yanıtını verir, böylece bir kişi için asla kuyruk birikmez.

Bir konuşmaya not ekleyin #

POST /contacts/notes

Bir kişinin konuşmasına gönderilmeden bir satır ekler. Bunu, ekibinizin ve yapay zekanın sahip olması gereken ancak kişinin asla görmemesi gereken bağlamlar için kullanın: sesli temsilcinizin yeni yaptığı bir telefon görüşmesinin özeti, CRM’inizden bir hatırlatma veya bir iş arkadaşınızdan gelen bir not. Tüm kanallarda (WhatsApp, SMS, Instagram, Messenger, Telegram, sohbet penceresi, özel kanallar vb.) çalışır.

Bir nota ne olur:

• Gelen kutusundaki sohbette, gönderdiyseniz yazarın adıyla birlikte sarı bir Not kartı olarak görünür.
• Yapay zeka bunu konuşma geçmişinin bir parçası olarak okur ve dahili bir not olarak işaretler, böylece bir sonraki yanıtında bunu dikkate alır.
• Kişiye asla gönderilmez, mesaj kredisi harcamaz ve hiçbir şeyi tetiklemez: yapay zeka yanıtı, otomasyon, webhook, bildirim veya okunmamış rozeti oluşturmaz. Yapay zekayı duraklatmaz ve ekibinizden gelen bir yanıt olarak sayılmaz.

Kişiyi Kişi kimliğiyle gönder ile aynı şekilde bulun: ya kimliği ya da bir channel ve eşleşen tanımlayıcı. Bir not yalnızca zaten var olan bir kişiye gider; eşleşmeyen hiçbir şey 404 hatası verir.

cURL

curl -X POST "https://api.youraiconnector.com/v1/contacts/notes" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "channel": "whatsapp",
    "phone_number": "+31612345678",
    "author": "Voice agent",
    "body": "Voice call, 3:12. Asked about knee surgery waiting times, prefers a call back on Tuesday morning.",
    "external_id": "call_8f2k1"
  }'

Yanıt (201 veya external_id zaten kaydedilmişse duplicate: true ile 200)

{
  "success": true,
  "messageId": "note_4c1f0e...",
  "contactId": "contact123"
}

Bir not, Bir kişinin mesajlarını listele kısmında type: "note" ile görünür.

Yapay zeka ile yanıt taslağı oluşturun #

POST /contacts/{contactId}/draft-reply

Bir konuşmayı yöneten yapay zeka temsilcisinden bir sonraki yanıtı yazmasını ister ve metni size geri verir. Hiçbir şey gönderilmez. Bu, gelen kutusundaki Yanıt Oluştur düğmesinin yazdığı taslağın aynısıdır: temsilci kendi kurulumunu, bilgi tabanını ve konuşmanın şimdiye kadarki kısmını kullanır ve kişinin dilinde yanıt verir. Bunu, yapay zeka ile kişi arasına bir insan (veya kendi uygulamanız) koymak için kullanın: taslağı getirin, onay için gösterin ve ardından Kişi kimliğine göre gönder ile değiştirilmiş veya olduğu haliyle gönderin.

• Taslak, kişiyle eşleştirilmiş temsilci tarafından yazılır. Henüz bir temsilcisi olmayan bir kişi, bir sonraki mesajını yanıtlayacak olan temsilciyi alır.
• Taslak oluşturulurken temsilci herhangi bir araç veya işlev çalıştırmaz, bu nedenle rezervasyon, etiketleme, devretme veya başka bir işlem gerçekleşmez.
• Konuşmada hiçbir şey saklanmaz ve kişi hiçbir şey görmez.
• Bir taslak, bu konuşmada o temsilciden gelen bir yapay zeka yanıtıyla aynı miktarda kredi harcar; kendi yapay zeka anahtarınız bağlı olduğunda ise hiçbir şey harcamaz.
• Konuşmanın en az bir mesaj içermesi gerekir.

Tüm gövde alanları isteğe bağlıdır; boş bir gövde (veya gövde olmaması) bir sonraki yanıtı taslak olarak oluşturur.

cURL

curl -X POST "https://api.youraiconnector.com/v1/contacts/contact123/draft-reply" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "instruction": "Offer Tuesday at 3pm for the consultation" }'

Yanıt (200)

{
  "success": true,
  "contact_id": "contact123",
  "draft": "Hi Sara, Tuesday at 3pm works for the consultation. Shall I put you down for it?"
}

400, konuşmada henüz mesaj olmadığını, kredilerinizin tükendiğini veya kişinin taslak oluşturacak bir temsilcisi veya kampanyası olmadığını gösterir (error hangisi olduğunu belirtir). 404, kişinin mevcut olmadığını veya bir ekip üyesinin anahtarının göremediği kişilerle sınırlı olduğunu gösterir. Anahtarın veya ekip üyesinin mesajları düzenleme iznine sahip olması gerekir.

MCP üzerinden bir yapay zeka istemcisi mi kullanıyorsunuz? Aynı eylem generate_reply_draft aracı olarak mevcuttur.

Bir kişinin mesajlarını listele #

GET /contacts/{contactId}/messages

Bir kişinin mesajlarını, imleç tabanlı sayfalama ile en yeniden başlayacak şekilde döndürür.

Filtreleme ve sayfalama hakkında not: filter ve direction filtreleri, okunduktan sonra her sayfaya uygulanır, bu nedenle filtrelenmiş bir sayfa limit değerinden daha az öğe içerebilir. next_cursor tüm konuşma boyunca ilerlemeye devam eder, bu nedenle next_cursor değeri null olana kadar sayfalamaya devam edin.

cURL

curl "https://api.youraiconnector.com/v1/contacts/contact123/messages?limit=50&direction=inbound" \
  -H "X-API-Key: YOUR_API_KEY"

JavaScript

const params = new URLSearchParams({ limit: "50", direction: "inbound" });
const res = await fetch(
  `https://api.youraiconnector.com/v1/contacts/contact123/messages?${params}`,
  { headers: { "X-API-Key": "YOUR_API_KEY" } }
);
const data = await res.json();
console.log(data.messages, data.next_cursor);

Python

import requests

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

Yanıt (200 OK):

{
  "success": true,
  "contact_id": "contact123",
  "messages": [
    {
      "id": "aB3dE5fG7hI9jK1lM2nO",
      "body": "Hi! Thanks for reaching out.",
      "direction": "inbound",
      "channel": "whatsapp",
      "status": "delivered",
      "type": null,
      "timestamp": "2026-06-01T10:00:00.000Z",
      "media_url": null,
      "media_content_type": null,
      "bot_reply": false
    }
  ],
  "next_cursor": "cD4eF6gH8iJ0kL2mN3oP"
}

Mesaj alanları #

Bir mesajın ekini indirme #

POST /chat-exports/media/download-url

Bir mesaja ekli dosya (görsel, sesli not, video veya belge) için size yeni bir indirme bağlantısı verir. Bağlantı 1 saat boyunca geçerlidir. Ekleri başka bir yere kaydetmek istediğinizde (örneğin, bir kişinin gönderdiği özgeçmişleri veya sesli notları arşivlemek) ya da bir mesajdaki media_url veya Yeni Mesaj web kancası artık açılmadığında kullanın.

Ekli mesajları bulmak için, bir kişinin mesajlarını filter=media ile listeleyin. Her mesajın id değeri ve kişinin kimliği messagePath değerini oluşturur.

cURL

curl -X POST "https://api.youraiconnector.com/v1/chat-exports/media/download-url" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"messagePath": "contacts/contact123/messages/aB3dE5fG7hI9jK1lM2nO"}'

JavaScript

const res = await fetch("https://api.youraiconnector.com/v1/chat-exports/media/download-url", {
  method: "POST",
  headers: { "X-API-Key": "YOUR_API_KEY", "Content-Type": "application/json" },
  body: JSON.stringify({ messagePath: "contacts/contact123/messages/aB3dE5fG7hI9jK1lM2nO" }),
});
const { data } = await res.json();
console.log(data.url); // download the file within the hour

Python

import requests

res = requests.post(
    "https://api.youraiconnector.com/v1/chat-exports/media/download-url",
    headers={"X-API-Key": "YOUR_API_KEY"},
    json={"messagePath": "contacts/contact123/messages/aB3dE5fG7hI9jK1lM2nO"},
)
file_url = res.json()["data"]["url"]

Yanıt (200 OK):

{
  "success": true,
  "data": {
    "url": "https://storage.googleapis.com/...",
    "expiresInMs": 3600000
  }
}

MCP üzerinden bir yapay zeka istemcisi mi kullanıyorsunuz? Aynı işlem get_chat_media_download_url aracı olarak da mevcuttur.

Sohbet oturumlarını listele #

Bir sohbet oturumu, bir kişiyle olan tek bir konuşma penceresidir. Oturum açık değilken gelen ilk mesajla açılır ve kişinin son gelen mesajından 48 saat sonra otomatik olarak kapanır (gelen her yeni mesaj, kapanma süresini 48 saat daha ileriye taşır). Yapay zekanın bir sohbeti sonlandırması oturumu kapatmaz; yalnızca Sohbet Sonlandırıldı (Chat Concluded) webhook’unu tetikler. Oturumlar, uzun bir geçmişi tek bir sonsuz liste yerine okunabilir konuşmalar halinde sayfalara ayırmanızı sağlar.

Tüm kişilerdeki son oturumlar #

GET /chat-sessions/recent

Hesaptaki her kişi genelinde, son X saat içinde başlayan oturumları en yeniden başlayarak döndürür.

cURL

curl "https://api.youraiconnector.com/v1/chat-sessions/recent?hours=24&status=ChatSessionClosed" \
  -H "X-API-Key: YOUR_API_KEY"

JavaScript

const params = new URLSearchParams({ hours: "24", status: "ChatSessionClosed" });
const res = await fetch(`https://api.youraiconnector.com/v1/chat-sessions/recent?${params}`, {
  headers: { "X-API-Key": "YOUR_API_KEY" },
});
const data = await res.json();
console.log(data.data.total_sessions, data.data.sessions);

Python

import requests

res = requests.get(
    "https://api.youraiconnector.com/v1/chat-sessions/recent",
    headers={"X-API-Key": "YOUR_API_KEY"},
    params={"hours": 24, "status": "ChatSessionClosed"},
)
data = res.json()["data"]
print(data["total_sessions"], data["sessions"])

Yanıt (200 OK):

{
  "success": true,
  "data": {
    "hours_ago": 24,
    "total_sessions": 2,
    "sessions": [
      {
        "session_id": "session456",
        "contact_id": "contact123",
        "contact_name": "Jane Doe",
        "contact_phone": "+31612345678",
        "contact_email": "jane@example.com",
        "start_date_time": "2026-06-01T09:55:00.000Z",
        "end_date_time": "2026-06-01T10:20:00.000Z",
        "status": "ChatSessionClosed",
        "tag": "Booking enquiry"
      }
    ]
  }
}

Bir kişi için tüm oturumlar #

GET /chat-sessions/{contactId}

Tek bir kişi için tüm sohbet oturumlarını döndürür. Yukarıdakiyle aynı status, limit ve includeMessages parametrelerini kullanır; hours burada geçerli değildir.

cURL

curl "https://api.youraiconnector.com/v1/chat-sessions/contact123?limit=20" \
  -H "X-API-Key: YOUR_API_KEY"

Yanıt (200 OK):

{
  "success": true,
  "data": {
    "contact_id": "contact123",
    "contact_name": "Jane Doe",
    "total_sessions": 2,
    "sessions": [
      {
        "id": "session456",
        "start_date_time": "2026-06-01T09:55:00.000Z",
        "end_date_time": "2026-06-01T10:20:00.000Z",
        "status": "ChatSessionClosed",
        "tag": "Booking enquiry"
      }
    ]
  }
}

Oturum kimliği alan adları iki uç nokta arasında farklılık gösterir. Son oturumlar listesi buna session_id der (ayrıca kişinin ayrıntılarını da taşır, çünkü oturumlar birçok kişiden gelir); kişi bazlı liste ise id olarak adlandırır. Aşağıdaki tam diziyi çekerken {sessionId} olarak her iki değeri de kullanabilirsiniz.

includeMessages=true olduğunda, her oturum id, body, direction, timestamp, type, channel ve status içeren girişlere sahip bir messages dizisi kazanır.

Bir sohbet oturumu dizisini getir #

GET /contacts/{contactId}/chat-sessions/{sessionId}/messages

Bir sohbet oturumu, bir kişinin mesajlarını tek bir konuşma penceresinde gruplandırır. Bu uç nokta, oturumun meta verileriyle birlikte tek bir oturumun tam dizisini en eskiden başlayarak döndürür. Bir kişi için oturum kimliklerini sohbet oturumları uç noktaları aracılığıyla bulabilirsiniz.

cURL

curl "https://api.youraiconnector.com/v1/contacts/contact123/chat-sessions/session456/messages" \
  -H "X-API-Key: YOUR_API_KEY"

JavaScript

const res = await fetch(
  "https://api.youraiconnector.com/v1/contacts/contact123/chat-sessions/session456/messages",
  { headers: { "X-API-Key": "YOUR_API_KEY" } }
);
const data = await res.json();
console.log(data.session, data.messages);

Python

import requests

res = requests.get(
    "https://api.youraiconnector.com/v1/contacts/contact123/chat-sessions/session456/messages",
    headers={"X-API-Key": "YOUR_API_KEY"},
)
data = res.json()
print(data["session"], data["messages"])

Yanıt (200 OK):

{
  "success": true,
  "contact_id": "contact123",
  "session": {
    "id": "session456",
    "status": "ChatSessionClosed",
    "start_date_time": "2026-06-01T09:55:00.000Z",
    "end_date_time": "2026-06-01T10:20:00.000Z",
    "tag": "Booking enquiry"
  },
  "messages": [
    {
      "id": "aB3dE5fG7hI9jK1lM2nO",
      "body": "Hi! Thanks for reaching out.",
      "direction": "inbound",
      "channel": "whatsapp",
      "status": "delivered",
      "type": null,
      "timestamp": "2026-06-01T09:55:00.000Z",
      "media_url": null,
      "media_content_type": null,
      "bot_reply": false
    }
  ]
}

session nesnesi status (etkin olduğunda ChatSessionOpened, sona erdiğinde ChatSessionClosed), start_date_time, end_date_time ve insan tarafından okunabilir bir tag bildirir. messages dizisi, liste uç noktasıyla aynı mesaj alanlarını kullanır.

Mesajları düzenle, sil ve tepki ver #

Bu uç noktalar, bir mesaj gönderildikten sonra üzerinde değişiklik yapar. Bunlardan ikisi, kendi kopyanızın yanı sıra kişinin kanalına da ulaşır, bu nedenle bunları bağlamadan önce bölüm girişini okuyun; nelerin mümkün olduğu tamamen konuşmanın gerçekleştiği kanala bağlıdır.

Her kanalın izin verdikleri

Diğer tüm kanallarda — WhatsApp Business API, SMS, Instagram, Messenger, e-posta, LINE, özel kanallar — silme işlemi mesajı gelen kutunuzdan kaldırır ancak kişi kendi kopyasını tutmaya devam eder ve düzenleme veya tepki verme işlemleri hiç mümkün değildir.

Bir mesajı düzenle #

POST /contacts/{contactId}/messages/{messageId}/edit

Zaten gönderdiğiniz bir mesajı, kişinin cihazında ve sizin kopyanızda yeniden yazar.

Silme işleminin aksine, kanal reddettiğinde bu işlem belirgin bir şekilde başarısız olur: bir 409 alırsınız ve kopyanız, kişinin sahip olduğuyla tamamen aynı kalır; çünkü almadıkları bir düzenlemeyi göstermek iki tarafın uyumunu bozacaktır. edit_reason alanı size nedenini söyler — kanalın düzenleme süresi dolmuştur, kanalın bağlantısı kesilmiştir, mesaj kanalın düzenleyemeyeceği bir ek içermektedir (media_not_editable: WhatsApp Web’de yalnızca metin mesajları düzenlenebilir, fotoğraf, video veya dosya altındaki metinler düzenlenemez) veya başka bir sorun oluşmuştur.

cURL

curl -X POST "https://api.youraiconnector.com/v1/contacts/contact123/messages/msg_1/edit" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "body": "Sorry - I meant Thursday at 3pm." }'

JavaScript

const res = await fetch(
  "https://api.youraiconnector.com/v1/contacts/contact123/messages/msg_1/edit",
  {
    method: "POST",
    headers: {
      "X-API-Key": "YOUR_API_KEY",
      "Content-Type": "application/json",
    },
    body: JSON.stringify({ body: "Sorry - I meant Thursday at 3pm." }),
  }
);
const data = await res.json();
console.log(data.edited, data.edit_reason);

Python

import requests

res = requests.post(
    "https://api.youraiconnector.com/v1/contacts/contact123/messages/msg_1/edit",
    headers={
        "X-API-Key": "YOUR_API_KEY",
        "Content-Type": "application/json",
    },
    json={"body": "Sorry - I meant Thursday at 3pm."},
)
data = res.json()
print(data.get("edited"), data.get("edit_reason"))

Yanıt (200 OK):

{
  "success": true,
  "contact_id": "contact123",
  "message_id": "msg_1",
  "edited": true,
  "edit_reason": "edit_dispatched"
}

Kanal düzenlemeyi kabul etmezse bunun yerine bir 409 alırsınız ve hiçbir şey değiştirilmez:

{
  "success": false,
  "error": "The message could not be edited",
  "edit_reason": "channel_disconnected"
}

Zaten silinmiş bir mesaj, hiç düzenleme yapamayan bir kanal ve kanalı için çok eski olan bir mesajın tümü 400 döndürür — istek kanala asla ulaşmaz.

Bir mesajı sil #

DELETE /contacts/{contactId}/messages/{messageId}

Mesajı konuşmanızdan kaldırır ve kanalın izin verdiği durumlarda kişinin kopyasını da geri çeker. İstek gövdesi yoktur.

Bu, mesaj mevcut olduğunda, kişinin kopyası geri çekilemese bile her zaman 200 yanıtını verir — sizin kopyanız silinmiştir, bu nedenle bir hata mesajı yanıltıcı olur. Kullanıcıya gerçekte ne olduğunu söylemek için yanıttaki üç alanı okuyun:

cURL

curl -X DELETE "https://api.youraiconnector.com/v1/contacts/contact123/messages/msg_1" \
  -H "X-API-Key: YOUR_API_KEY"

JavaScript

const res = await fetch(
  "https://api.youraiconnector.com/v1/contacts/contact123/messages/msg_1",
  { method: "DELETE", headers: { "X-API-Key": "YOUR_API_KEY" } }
);
const data = await res.json();
console.log(data.revoked, data.revoke_reason);

Python

import requests

res = requests.delete(
    "https://api.youraiconnector.com/v1/contacts/contact123/messages/msg_1",
    headers={"X-API-Key": "YOUR_API_KEY"},
)
data = res.json()
print(data["revoked"], data["revoke_reason"])

Yanıt (200 OK):

{
  "success": true,
  "contact_id": "contact123",
  "message_id": "msg_1",
  "revoke_supported": true,
  "revoked": true,
  "revoke_reason": "revoke_dispatched"
}

Silinen iletiler konuşma geçmişinden kaldırılmaz. Bunlar GET /contacts/{contactId}/messages içinde is_deleted: true ve boş bir body ve media_url ile kalır.

Birden fazla iletiyi aynı anda silme #

POST /contacts/{contactId}/messages/bulk-delete

Bir grup iletiyi yalnızca kendi tarafınızdan temizler. İçerikler ve ekler boşaltılır, ancak karşı tarafın cihazında hiçbir şey geri alınmaz — bir iletiyi tamamen geri çekmek için, yukarıdaki tekli ileti uç noktasını kullanarak tek tek silin.

cURL

curl -X POST "https://api.youraiconnector.com/v1/contacts/contact123/messages/bulk-delete" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "message_ids": ["msg_1", "msg_2"] }'

JavaScript

const res = await fetch(
  "https://api.youraiconnector.com/v1/contacts/contact123/messages/bulk-delete",
  {
    method: "POST",
    headers: {
      "X-API-Key": "YOUR_API_KEY",
      "Content-Type": "application/json",
    },
    body: JSON.stringify({ message_ids: ["msg_1", "msg_2"] }),
  }
);
console.log((await res.json()).deleted);

Python

import requests

res = requests.post(
    "https://api.youraiconnector.com/v1/contacts/contact123/messages/bulk-delete",
    headers={
        "X-API-Key": "YOUR_API_KEY",
        "Content-Type": "application/json",
    },
    json={"message_ids": ["msg_1", "msg_2"]},
)
print(res.json()["deleted"])

Yanıt (200 OK):

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

Bir iletiye tepki verme #

POST /contacts/{contactId}/messages/{messageId}/react

Bir iletiye kendi emoji tepkinizi ekler veya boş bir dize göndererek tepkinizi geri alır. Karşı tarafın kendi tepkilerine asla dokunulmaz.

Düzenleme işleminde olduğu gibi, bu işlem karşı tarafın hiç almadığı bir tepkiyi göstermek yerine başarısız olur ve hata, yeniden denemenin mantıklı olup olmadığını size bildirir:

• 422 — bu konuşmada asla iletilemez: kanal tepkileri desteklemiyor, iletinin kanal tarafında bir kimliği yok veya emoji, kanalın izin verdiği kümenin dışında.
• 409 — kanala anlık olarak ulaşılamadı. Yeniden deneme işe yarayabilir.

cURL

curl -X POST "https://api.youraiconnector.com/v1/contacts/contact123/messages/msg_1/react" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "emoji": "👍" }'

JavaScript

const res = await fetch(
  "https://api.youraiconnector.com/v1/contacts/contact123/messages/msg_1/react",
  {
    method: "POST",
    headers: {
      "X-API-Key": "YOUR_API_KEY",
      "Content-Type": "application/json",
    },
    body: JSON.stringify({ emoji: "👍" }),
  }
);
const data = await res.json();
console.log(data.reactions);

Python

import requests

res = requests.post(
    "https://api.youraiconnector.com/v1/contacts/contact123/messages/msg_1/react",
    headers={
        "X-API-Key": "YOUR_API_KEY",
        "Content-Type": "application/json",
    },
    json={"emoji": "👍"},
)
print(res.json()["reactions"])

Yanıt (200 OK):

{
  "success": true,
  "contact_id": "contact123",
  "message_id": "msg_1",
  "reaction_supported": true,
  "reaction_reason": "reaction_dispatched",
  "reactions": [
    {
      "emoji": "👍",
      "from_phone_number": "+31612345678",
      "from_me": true,
      "reacted_at": "2026-06-01T10:05:00.000Z"
    }
  ]
}

reactions dizisi, iletideki hem sizin hem de karşı tarafın tepkilerini içeren tam kümedir. Bir 409 veya 422 durumunda dizi değişmeden döndürülür, bu nedenle doğrudan bu diziden görüntüleme yapan bir istemci, iletilmemiş bir tepkiyi asla göstermez.

Bir iletiyi oylama veya yıldızlama #

PATCH /contacts/{contactId}/messages/{messageId}

Bir iletiyi başparmak yukarı veya aşağı ile oylar ve/veya önemli olarak yıldızlar. Bu işlem yalnızca sizin tarafınızdaki kayıt tutma amaçlıdır; karşı tarafa hiçbir şey gönderilmez.

İkisinden en az birini gönderin, aksi takdirde bir 400 alırsınız. Yalnızca gönderdiğiniz şey yazılır, bu nedenle bir mesajı yıldızlamak derecelendirmesini asla temizlemez ve bunun tersi de geçerlidir — ve yanıt yalnızca gönderdiğiniz alanları geri yansıtır.

cURL

curl -X PATCH "https://api.youraiconnector.com/v1/contacts/contact123/messages/msg_1" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "score": 1, "is_important": true }'

JavaScript

await fetch("https://api.youraiconnector.com/v1/contacts/contact123/messages/msg_1", {
  method: "PATCH",
  headers: {
    "X-API-Key": "YOUR_API_KEY",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({ score: 1, is_important: true }),
});

Python

import requests

requests.patch(
    "https://api.youraiconnector.com/v1/contacts/contact123/messages/msg_1",
    headers={"X-API-Key": "YOUR_API_KEY"},
    json={"score": 1, "is_important": True},
)

Yanıt (200 OK):

{
  "success": true,
  "contact_id": "contact123",
  "message_id": "msg_1",
  "score": 1,
  "is_important": true
}

Mesajları okundu olarak işaretle #

Okunmamış durumunu belirli mesajlar için veya tüm konuşma için temizleyebilirsiniz.

Belirli mesajları okundu olarak işaretle #

POST /contacts/{contactId}/messages/mark-read

Okundu olarak işaretlenecek mesajların kimliklerini iletin.

cURL

curl -X POST "https://api.youraiconnector.com/v1/contacts/contact123/messages/mark-read" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "message_ids": ["aB3dE5fG7hI9jK1lM2nO", "cD4eF6gH8iJ0kL2mN3oP"]
  }'

JavaScript

const res = await fetch(
  "https://api.youraiconnector.com/v1/contacts/contact123/messages/mark-read",
  {
    method: "POST",
    headers: {
      "X-API-Key": "YOUR_API_KEY",
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      message_ids: ["aB3dE5fG7hI9jK1lM2nO", "cD4eF6gH8iJ0kL2mN3oP"],
    }),
  }
);
const data = await res.json();
console.log(data.marked_read);

Python

import requests

res = requests.post(
    "https://api.youraiconnector.com/v1/contacts/contact123/messages/mark-read",
    headers={
        "X-API-Key": "YOUR_API_KEY",
        "Content-Type": "application/json",
    },
    json={"message_ids": ["aB3dE5fG7hI9jK1lM2nO", "cD4eF6gH8iJ0kL2mN3oP"]},
)
print(res.json()["marked_read"])

Yanıt (200 OK):

{
  "success": true,
  "contact_id": "contact123",
  "marked_read": 2
}

Tüm sohbeti okundu olarak işaretle #

POST /contacts/{contactId}/mark-read

Gelen kutusundaki kişinin tüm konuşması için okunmamış rozetini temizler. İstek gövdesi gerekmez.

cURL

curl -X POST "https://api.youraiconnector.com/v1/contacts/contact123/mark-read" \
  -H "X-API-Key: YOUR_API_KEY"

JavaScript

const res = await fetch(
  "https://api.youraiconnector.com/v1/contacts/contact123/mark-read",
  { method: "POST", headers: { "X-API-Key": "YOUR_API_KEY" } }
);
const data = await res.json();
console.log(data.success);

Python

import requests

res = requests.post(
    "https://api.youraiconnector.com/v1/contacts/contact123/mark-read",
    headers={"X-API-Key": "YOUR_API_KEY"},
)
print(res.json()["success"])

Yanıt (200 OK):

{
  "success": true,
  "contact_id": "contact123"
}

Tüm sohbeti okunmadı olarak işaretle #

POST /contacts/{contactId}/mark-unread

Okunmadı rozetini konuşmaya geri koyar — ekibinizden biri bir sohbeti açtığında ancak geri devrettiğinde kullanışlıdır. İstek gövdesi gerekmez.

Bu yalnızca gelen kutusuna özel bir bayraktır: konuşmanın en son ne zaman okunduğunu değiştirmez, bu nedenle destekleyen kanallarda kişiye okundu bilgisi gönderilmez.

cURL

curl -X POST "https://api.youraiconnector.com/v1/contacts/contact123/mark-unread" \
  -H "X-API-Key: YOUR_API_KEY"

Yanıt (200 OK):

{
  "success": true,
  "contact_id": "contact123"
}

Bir konuşmayı dışa aktar #

Dışa aktarmalar, mesajlar arasında gezinmek yerine size tüm konuşmayı okunabilir bir döküm olarak verir. Her dışa aktarma uç noktası, mesaj listesindeki filtreyle eşleşen all (varsayılan), text, media veya tool_use değerinde bir filter kabul eder.

Bir kişinin sohbetini dışa aktar #

GET /chat-exports/{contactId}

cURL

curl "https://api.youraiconnector.com/v1/chat-exports/contact123?format=json" \
  -H "X-API-Key: YOUR_API_KEY"

Python

import requests

res = requests.get(
    "https://api.youraiconnector.com/v1/chat-exports/contact123",
    headers={"X-API-Key": "YOUR_API_KEY"},
    params={"format": "json"},
)
print(res.json()["data"]["messages"])

format=json ile yanıt (200 OK):

{
  "success": true,
  "data": {
    "contact": {
      "id": "contact123",
      "name": "Jane Doe",
      "phone": "+31612345678",
      "email": "jane@example.com"
    },
    "messages": [
      {
        "body": "Hi! I have a question about my order.",
        "direction": "inbound",
        "timestamp": "2026-06-01T09:55:00.000Z",
        "type": "text",
        "media_url": null,
        "media_content_type": null,
        "name": null,
        "args": null
      }
    ]
  }
}

format=txt (varsayılan) ile, data bunun yerine oluşturulan döküm dosyasına bir indirme bağlantısıdır:

{
  "success": true,
  "data": "https://storage.googleapis.com/.../chat-export-contact123-....txt"
}

İndirme bağlantısının ömrü kısadır. Dosyayı depolamak yerine bağlantıyı alır almaz indirin — döküme tekrar ihtiyacınız olduğunda yeni bir dışa aktarma isteğinde bulunun.

Tüm son konuşmaları dışa aktar #

GET /chat-exports/recent

Son X saat içinde aktif olan tüm kişilerin konuşmalarını tek bir çağrıda dışa aktarır.

cURL

curl "https://api.youraiconnector.com/v1/chat-exports/recent?hours=24&limit=25" \
  -H "X-API-Key: YOUR_API_KEY"

Yanıt (200 OK):

{
  "success": true,
  "data": {
    "hours_ago": 24,
    "total_contacts": 2,
    "exports": [
      {
        "contactId": "contact123",
        "contactName": "Jane Doe",
        "phoneNumber": "+31612345678",
        "email": "jane@example.com",
        "messageCount": 12,
        "chatExport": "Acme Export - Jane Doe\nPhone: +31612345678\n..."
      }
    ]
  }
}

format=txt ile yanıt, JSON yerine doğrudan indirme olarak gönderilen metin dosyasının kendisidir.

Bu tek çağrı, eşleşen her kişinin tam geçmişini çeker, bu nedenle yoğun hesaplarda hours ve limit değerlerini makul tutun.

Bir konuşma dökümünü kişiye e-posta ile gönderin #

POST /chat-exports/{contactId}/email

Kişiye kendi konuşma dökümünü e-posta yoluyla gönderir — kendi sisteminizden yönetilen “bu sohbeti bana e-posta ile gönder” akışı.

cURL

curl -X POST "https://api.youraiconnector.com/v1/chat-exports/contact123/email" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "note": "Here is a copy of our chat, as promised." }'

Yanıt (200 OK):

{
  "success": true,
  "data": {
    "via": "transactional",
    "recipientEmail": "jane@example.com",
    "messageCount": 42,
    "omittedCount": 0
  }
}

omittedCount, e-postayı makul bir uzunlukta tutmak için en eski mesajlardan kaçının hariç tutulduğunu söyler. 200, dökümün oluşturulduğunu ve gönderilmek üzere sıraya alındığını belirtir, henüz gelen kutusuna ulaştığı anlamına gelmez.

Bir kişi için yapay zekayı duraklatma veya devam ettirme #

PUT /contacts/{contactId}

Yapay zekanın bir kişiye yanıt vermesini durdurmak için is_bot_active değerini false olarak ayarlayın, konuşmayı geri vermek için tekrar true değerine getirin. Bir insan konuşmaya dahil olduğunda kullanmak istediğiniz devralma anahtarı budur: API ile gönderdiğiniz giden mesajlar, bot duraklatılmış olsa bile iletilmeye devam eder.

cURL

curl -X PUT "https://api.youraiconnector.com/v1/contacts/contact123" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "is_bot_active": false }'

JavaScript

await fetch("https://api.youraiconnector.com/v1/contacts/contact123", {
  method: "PUT",
  headers: {
    "X-API-Key": "YOUR_API_KEY",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({ is_bot_active: false }),
});

Python

import requests

requests.put(
    "https://api.youraiconnector.com/v1/contacts/contact123",
    headers={"X-API-Key": "YOUR_API_KEY"},
    json={"is_bot_active": False},
)

Yanıt

{
  "success": true,
  "contact_id": "contact123"
}

Yanıtın bir parçası olarak duraklatma

Bir insan bir yanıt göndererek kontrolü devralıyorsa, ikinci bir çağrı yapmak yerine aynı istek içinde botu duraklatabilirsiniz. POST /contacts/{contactId}/send-message şu isteğe bağlı bayrakları kabul eder:

curl -X POST "https://api.youraiconnector.com/v1/contacts/contact123/send-message" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "body": "Hi, Sarah here - taking over from the assistant.",
    "pauseBot": true,
    "clearIncompleteReply": true,
    "human_reply": true
  }'

Yanıt, duraklatma uygulandığında "botPaused": true bilgisini içerir.

Bir kişiyi POST /contacts/bulk-flag ile özel olarak işaretlemek, botu onlar için de duraklatır. Tüm alan listesi için Kişiler bölümüne bakın.

Kendi gelen kutunuzu oluşturma #

Bir gelen kutusunun ihtiyaç duyduğu her şey bu sayfada ve Kişiler bölümünde mevcuttur:

Canlı güncellemeler için, bu API’yi bir zamanlayıcı ile sorgulamak yerine Webhooks ile New Message, Replies, Human Alerted ve Chat Concluded olaylarına abone olun.

Mesajlar API hataları #

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

{
  "success": false,
  "error": "Contact 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.

Sonraki adımlar #

• Web kancaları — yoklama yapmak yerine teslimat durumu güncellemelerini size iletilmesini sağlayın.
• Kişiler — mesaj gönderdiğiniz kişileri oluşturun ve arayın.
• Randevular — kişileriniz için randevuları ayırtın ve yönetin.