הודעות ושיחות #

ממשק ה-API של הודעות מאפשר לך לשלוח הודעה לכל איש קשר, לקרוא בחזרה שיחה, לתקן או להסיר הודעה שכבר שלחת, להגיב להודעה, למשוך שרשור מלא של שיחת צ’אט, לייצא תמליל, ולסמן צ’אטים כנקראו או שלא נקראו — הכל מבלי לפתוח את תיבת הדואר הנכנס.

כל הנתיבים בדף זה הם יחסיים לכתובת ה-URL הבסיסית https://api.youraiconnector.com/v1. כל בקשה דורשת את מפתח ה-API שלך — ראה אימות לרשימה המלאה של הדרכים לשליחתו. הדוגמאות להלן משתמשות בכותרת X-API-Key, כאשר דוגמת cURL אחת מציגה גם את טופס השאילתה ?apiKey=.

כיצד פועלת המסירה: שליחת הודעה אינה ממתינה להגעתה. ה-API מקבל את ההודעה שלך, מחזיר מיד מזהה הודעה, ולאחר מכן מוסר אותה ברקע בערוץ של איש הקשר (WhatsApp, SMS, Instagram וכן הלאה). כדי לעקוב אם הודעה אכן נמסרה או נקראה, האזן לעדכוני סטטוס באמצעות Webhooks — אל תבצע סקר (polling). תגובת השליחה מאשרת רק שההודעה התקבלה.

שליחת הודעה #

קיימות שתי דרכים לשלוח הודעה. בחר את הדרך המתאימה לאופן שבו אתה כבר מזהה את איש הקשר:

• שליחה לפי מזהה איש קשר — אתה כבר מכיר את המזהה של איש הקשר (למשל, יצרת את איש הקשר דרך ה-API או קיבלת אותו מ-webhook). השתמש ב-POST /contacts/{contactId}/send-message.
• שליחה לפי זהות איש קשר — אתה מכיר את מספר הטלפון של איש הקשר, מזהה ה-Instagram שלו וכו’, אך לא את המזהה הפנימי שלו. השתמש ב-POST /contacts/send ותן לפלטפורמה למצוא את איש הקשר הנכון.

שתי הדרכים מכניסות את ההודעה לתור באותו אופן ומוסרות אותה בערוץ שבו נמצא איש הקשר. אתה לא בוחר את אמצעי התעבורה — הפלטפורמה מנתבת אנשי קשר של WhatsApp דרך WhatsApp, אנשי קשר של SMS דרך SMS, וכן הלאה.

שליחה לפי מזהה איש קשר #

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"])

תגובה (200 OK):

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

שליחה לפי זהות איש קשר #

POST /contacts/send

השתמש בזה כאשר אין לך את המזהה הפנימי של איש הקשר. ספק את body ההודעה פלוס או contact_id, או channel יחד עם שדה הזהות התואם לאותו ערוץ.

אילו ערוצים ניתנים לפתרון לפי זהות. רק שישה מתוך ה-14 מקבלים שדה זהות במקום contact_id: whatsapp, whatsapp_web ו-sms מאותרים לפי phone_number, instagram לפי instagram_id, messenger לפי messenger_id, ו-telegram לפי telegram_user_id. שמונת האחרים — instagram_private, chat-widget, custom, email, line, imessage, linkedin ו-viber — הם ללא זהות ציבורית לאיתור, לכן שליחה בערוצים אלו דורשת contact_id; העברת channel בלבד תחזיר 400 המציין ש-contact_id נדרש.

cURL (באמצעות טופס השאילתה ?apiKey=)

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"])

תגובה (201 Created):

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

מדוע הודעה עלולה להידחות: איש קשר עם מצב ‘נא לא להפריע’ או מצב פרטי מופעל אינו יכול לקבל הודעות יוצאות — הבקשה תיכשל עם 422. אם אף איש קשר אינו תואם למזהה או לזהות שסיפקת, תקבל 404.

הצגת הודעות של איש קשר #

GET /contacts/{contactId}/messages

מחזיר את ההודעות של איש קשר, מהחדשה לישנה, עם דפדוף מבוסס סמן (cursor).

הערה על סינון ודפדוף: המסננים filter ו-direction מוחלים על כל עמוד לאחר קריאתו, לכן עמוד מסונן יכול להכיל פחות פריטים מ-limit. ה-next_cursor עדיין מתקדם לאורך כל השיחה, לכן המשך לדפדף עד ש-next_cursor יהיה null.

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"])

תגובה (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"
}

שדות הודעה #

רשימת סשנים של צ’אט #

סשן צ’אט הוא חלון שיחה אחד עם איש קשר: הוא נפתח כשהם מתחילים לדבר ונסגר כשהשיחה מסתיימת. סשנים הם הדרך שבה אתה מחלק היסטוריה ארוכה לשיחות קריאות במקום לרשימה אחת אינסופית.

סשנים אחרונים בכל אנשי הקשר #

GET /chat-sessions/recent

מחזיר את הסשנים שהחלו ב-X השעות האחרונות, מהחדש לישן, עבור כל איש קשר בחשבון.

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"])

תגובה (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"
      }
    ]
  }
}

כל הסשנים עבור איש קשר אחד #

GET /chat-sessions/{contactId}

מחזיר כל סשן צ’אט עבור איש קשר בודד. אותם פרמטרים status, limit ו-includeMessages כמו לעיל — hours לא חל כאן.

cURL

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

תגובה (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"
      }
    ]
  }
}

שמות שדות מזהה הסשן שונים בין שני נקודות הקצה. רשימת הסשנים האחרונים קוראת לו session_id (הוא גם נושא את פרטי איש הקשר, מכיוון שסשנים מגיעים מאנשי קשר רבים); הרשימה לפי איש קשר קוראת לו id. כל ערך הוא מה שאתה מעביר כ-{sessionId} בעת משיכת השרשור המלא להלן.

כאשר includeMessages=true, כל סשן מקבל מערך messages שהרשומות בו נושאות id, body, direction, timestamp, type, channel ו-status.

שליפת שרשור שיחה #

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

סשן צ’אט מקבץ את ההודעות של איש קשר לחלון שיחה אחד. נקודת קצה זו מחזירה את כל השרשור של סשן בודד, מהישן ביותר לחדש ביותר, יחד עם המטא-דאטה של הסשן. ניתן למצוא מזהי סשן עבור איש קשר דרך נקודות הקצה של סשני צ’אט.

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"])

תגובה (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 מדווח על status (ChatSessionOpened בזמן פעילות, ChatSessionClosed לאחר סיום), start_date_time, end_date_time, ו-tag קריא לבני אדם. המערך messages משתמש באותם שדות הודעה כמו נקודת הקצה של הרשימה.

עריכה, מחיקה ותגובה להודעות #

נקודות קצה אלו משנות הודעה לאחר שנשלחה. שתיים מהן פונות לערוץ של איש הקשר וגם לעותק שלך, לכן קרא את מבוא הסעיף לפני חיבורן — מה שאפשרי תלוי לחלוטין בערוץ שבו מתקיימת השיחה.

מה כל ערוץ מאפשר

בכל ערוץ אחר — WhatsApp Business API, SMS, אינסטגרם, מסנג’ר, אימייל, LINE, ערוצים מותאמים אישית — מחיקה עדיין מסירה את ההודעה מתיבת הדואר הנכנס שלך, אך איש הקשר שומר על העותק שלו, ועריכה או תגובה אינן אפשריות כלל.

עריכת הודעה #

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

משכתב הודעה שכבר שלחת, במכשיר של איש הקשר ובעותק שלך.

בניגוד למחיקה, פעולה זו נכשלת בקול רעש כאשר הערוץ מסרב: אתה מקבל 409 והעותק שלך נשאר בדיוק כפי שהוא אצל איש הקשר, מכיוון שהצגת עריכה שהם מעולם לא קיבלו תוציא את שני הצדדים מסנכרון. השדה edit_reason אומר לך מדוע — חלון העריכה של הערוץ נסגר, הערוץ מנותק, או שמשהו אחר השתבש.

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"))

תגובה (200 OK):

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

אם הערוץ לא יקבל את העריכה, תקבל במקום זאת 409, ושום דבר לא ישתנה:

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

הודעה שכבר נמחקה, ערוץ שלא יכול לערוך כלל, והודעה ישנה מדי עבור הערוץ שלה, כולם מחזירים 400 — הבקשה לעולם לא מגיעה לערוץ.

מחיקת הודעה אחת #

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

מסיר את ההודעה מהשיחה שלך, ובמקומות שבהם הערוץ מאפשר זאת, מושך בחזרה גם את העותק של איש הקשר. אין גוף בקשה.

פעולה זו תמיד עונה 200 כאשר ההודעה הייתה קיימת, גם אם לא ניתן היה למשוך בחזרה את העותק של איש הקשר — העותק שלך אכן נמחק, כך ששגיאה תהיה מטעה. קרא את שלושת השדות בתגובה כדי לומר למשתמש מה קרה בפועל:

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"])

תגובה (200 OK):

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

הודעות שנמחקו אינן מוסרות מהיסטוריית השיחה. הן נשארות ב-GET /contacts/{contactId}/messages עם is_deleted: true ו-body ריק ו-media_url.

מחיקת מספר הודעות בבת אחת #

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

מנקה קבוצת הודעות מהצד שלך בלבד. גוף ההודעות והקבצים המצורפים מתרוקנים, אך דבר אינו נמשך חזרה ממכשיר איש הקשר — כדי למשוך הודעה חזרה גם משם, מחק אותה אחת אחת באמצעות נקודת הקצה להודעה בודדת שלעיל.

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"])

תגובה (200 OK):

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

הגב להודעה #

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

מוסיף תגובת אימוג’י משלך להודעה, או מסיר אותה על ידי שליחת מחרוזת ריקה. התגובות של איש הקשר לעולם אינן מושפעות.

בדומה לעריכה, פעולה זו נכשלת במקום להציג תגובה שאיש הקשר מעולם לא קיבל, והכישלון מציין אם כדאי לנסות שוב:

• 422 — לא ניתן להעביר זאת לעולם בשיחה זו: הערוץ אינו תומך בתגובות, להודעה אין מזהה בצד הערוץ, או שהאימוג’י נמצא מחוץ לקבוצה שהערוץ מאפשר.
• 409 — הערוץ לא היה זמין לרגע. ניסיון חוזר עשוי להצליח.

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"])

תגובה (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 הוא קבוצת התגובות המלאה שקיימת כעת על ההודעה, שלך ושל איש הקשר. ב-409 או ב-422 הוא מוחזר ללא שינוי, כך שלקוח המרנדר ישירות ממנו לעולם לא יציג תגובה שלא הועברה.

דירוג או סימון הודעה בכוכב #

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

מדרג הודעה באגודל למעלה או למטה ו/או מסמן אותה בכוכב כחשובה. זהו רישום בצד שלך בלבד — דבר אינו נשלח לאיש הקשר.

שלח לפחות אחד משניהם, אחרת תקבל 400. רק מה שאתה שולח נכתב, לכן סימון הודעה בכוכב לעולם לא מנקה את הדירוג שלה ולהיפך — והתגובה מחזירה רק את השדות ששלחת.

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},
)

תגובה (200 OK):

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

סימון הודעות כנקראו #

ניתן לנקות את מצב ה’לא נקרא’ עבור הודעות ספציפיות או עבור השיחה כולה.

סימון הודעות ספציפיות כנקראו #

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

העבר את המזהים של ההודעות שברצונך לסמן כנקראו.

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"])

תגובה (200 OK):

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

סימון כל הצ’אט כנקרא #

POST /contacts/{contactId}/mark-read

מנקה את תגית ה’לא נקרא’ עבור כל השיחה של איש הקשר בתיבת הדואר הנכנס. אין צורך בגוף בקשה.

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"])

תגובה (200 OK):

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

סימון כל הצ’אט כלא נקרא #

POST /contacts/{contactId}/mark-unread

מחזיר את תגית ה’לא נקרא’ לשיחה — שימושי כאשר מישהו בצוות שלך פתח צ’אט אך מעביר אותו הלאה. אין צורך בגוף בקשה.

זהו דגל של תיבת דואר נכנסת בלבד: הוא לא משנה מתי השיחה נקראה לאחרונה, לכן לא נשלח אישור קריאה לאיש הקשר בערוצים התומכים בכך.

cURL

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

תגובה (200 OK):

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

ייצוא שיחה #

ייצוא נותן לך שיחה שלמה כתמליל קריא, במקום לדפדף בין הודעות. כל נקודת קצה של ייצוא מקבלת filter של all (ברירת מחדל), text, media או tool_use, בהתאם למסנן ברשימת ההודעות.

ייצוא צ’אט של איש קשר אחד #

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 (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 (ברירת המחדל), data הוא במקום זאת קישור להורדה של קובץ התמליל שנוצר:

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

קישור ההורדה הוא לזמן קצר. משוך את הקובץ ברגע שאתה מקבל את הקישור במקום לאחסן אותו — בקש ייצוא חדש כאשר תזדקק לתמליל שוב.

ייצוא כל השיחות האחרונות #

GET /chat-exports/recent

מייצא את השיחות של כל אנשי הקשר שהיו פעילים ב-X השעות האחרונות, בקריאה אחת.

cURL

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

תגובה (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 התגובה היא קובץ הטקסט עצמו, שנשלח כהורדה במקום כ-JSON.

קריאה זו מושכת את ההיסטוריה המלאה של כל איש קשר תואם, לכן יש לשמור על hours ו-limit צנועים בחשבונות עמוסים.

שליחת תמליל בדוא"ל לאיש הקשר #

POST /chat-exports/{contactId}/email

שולח לאיש הקשר את תמליל השיחה שלו בדוא"ל — תהליך ה-“שלח לי את הצ’אט הזה במייל”, המופעל מהמערכת שלך.

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." }'

תגובה (200 OK):

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

omittedCount מציין כמה מההודעות הישנות ביותר הושמטו כדי לשמור על אורך סביר של הדוא"ל. 200 פירושו שהתמליל נוצר והוכנס לתור לשליחה, לא שהוא כבר הגיע לתיבת הדואר הנכנס.

השהיה או חידוש של ה-AI עבור איש קשר בודד #

PUT /contacts/{contactId}

הגדירו את is_bot_active ל-false כדי לעצור את ה-AI מלהשיב לאיש קשר בודד, וחזרה ל-true כדי להחזיר את השיחה. זהו מתג ההשתלטות שתרצו כאשר אדם נכנס לשיחה: הודעות יוצאות שאתם שולחים באמצעות ה-API עדיין נשלחות בזמן שהבוט מושהה.

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},
)

תגובה

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

השהיה כחלק מהתשובה

אם אדם משתלט על השיחה על ידי שליחת תשובה, ניתן להשהות את הבוט באותה בקשה במקום לבצע קריאה שנייה. POST /contacts/{contactId}/send-message מקבל שני דגלים אופציונליים:

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
  }'

התגובה כוללת את "botPaused": true כאשר ההשהיה הוחלה.

סימון איש קשר כפרטי באמצעות POST /contacts/bulk-flag משהה גם את הבוט עבורו. ראו אנשי קשר לרשימת השדות המלאה.

בניית תיבת דואר נכנס משלכם #

כל מה שתיבת דואר נכנס צריכה נמצא בדף זה וב-אנשי קשר:

לקבלת עדכונים בזמן אמת, הירשמו לאירועי New Message, Replies, Human Alerted ו-Chat Concluded באמצעות Webhooks במקום לבצע סקר (polling) ל-API זה לפי טיימר.

שגיאות ב-API של הודעות #

נקודות קצה של הודעות מחזירות את מעטפת השגיאה הסטנדרטית:

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

הקודים המשותפים שכל נקודת קצה יכולה להחזיר — 401, 403 (התוכנית שלך אינה כוללת גישת API), 429 (מגבלת קצב) ו-500 — מפורטים עם הנחיות לניסיון חוזר ב-שגיאות ועימוד.

צעדים הבאים #

• Webhooks — קבל עדכוני סטטוס משלוח בדחיפה במקום לבצע תשאול (polling).
• אנשי קשר — צור וחפש את אנשי הקשר שאליהם אתה שולח הודעות.
• פגישות — קבע ונהל פגישות עבור אנשי הקשר שלך.