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.

Kişi kimliği ile gönder #

POST /contacts/{contactId}/send-message

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.

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ı #

Sohbet oturumlarını listele #

Bir sohbet oturumu, bir kişiyle yapılan tek bir konuşma penceresidir: kişi konuşmaya başladığında açılır ve konuşma sona erdiğinde kapanır. Oturumlar, uzun bir geçmişi tek bir sonsuz liste yerine okunabilir konuşmalara bölmenizi 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.

Silmenin aksine, bu işlem kanal reddettiğinde açıkça başarısız olur: bir 409 alırsınız ve kopyanız tam olarak kişinin sahip olduğu şekilde kalır, çünkü kişinin hiç almadığı bir düzenlemeyi göstermek iki tarafın uyumunu bozar. edit_reason alanı size nedenini söyler — kanalın düzenleme penceresi kapanmıştır, kanalın bağlantısı kesilmiştir 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 yanıt göndererek devralıyorsa, ikinci bir çağrı yapmak yerine aynı istek içinde botu duraklatabilirsiniz. POST /contacts/{contactId}/send-message iki isteğe bağlı bayrağı 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
  }'

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.