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

ממשק ה-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, וכן הלאה.

שניהם גם מוצאים רק אנשי קשר שכבר קיימים. אף אחת מהקריאות לא יוצרת איש קשר: מזהה או זהות שאין להם התאמה חוזרים כ-404, והם לא הופכים לאיש קשר חדש. לכן, אם אתם שולחים הודעה למישהו בפעם הראשונה, צרו תחילה את איש הקשר באמצעות POST /contacts, או ב-WhatsApp Web, השתמשו ב-שלח ישירות למספר ב-WhatsApp Web להלן, שיוצר את איש הקשר באותה קריאה.

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

POST /contacts/{contactId}/send-message

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

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.

שליחה ב-WhatsApp Web: וריאציות והגנה מפני שליחה מרוכזת #

שני דברים חלים על body כאשר איש הקשר נמצא ב-WhatsApp Web.

סוגרי Spintax מורחבים עבור כל שליחה. body של {Hi|Hello|Hey} there, quick question יישלח כאחת משלוש הברכות, שנבחרת עבור אותה שליחה — הסוגריים לעולם לא יגיעו לאיש הקשר. השתמש בזה כדי לתת לכל איש קשר הודעת פתיחה שונה מאותו קוד אינטגרציה. טקסט ללא סוגריים נשלח בדיוק כפי שנכתב.

צרורות של הודעות פתיחה זהות נדחים. אם עשר הודעות פתיחה כמעט זהות יוצאות ממספר WhatsApp Web אחד בתוך שעה, לאנשי קשר שמעולם לא כתבו לך, הודעות נוספות לא יועברו: השליחה מתקבלת כרגיל (אתה עדיין מקבל messageId), וההודעה נשארת עם status: "failed" ו-error_code: "opener_burst", עם סיבה שניתנת לקריאה על ידי הלקוח. ניסיון חוזר עם אותו טקסט לא יעזור — שנה את הטקסט, המתן שעה ושלח שוב. תשובות בתוך שיחות קיימות לעולם אינן מושפעות. ההסבר נמצא ב-הודעות פתיחה זהות מובילות להגבלת מספרים.

שלח ישירות למספר ב-WhatsApp Web #

POST /whatsapp-web/send

שלחו הודעה למספר טלפון ב-WhatsApp Web מבלי לחפש תחילה איש קשר. אם המספר אינו איש קשר עדיין, איש הקשר נוצר באותה קריאה, כאשר ה-AI כבוי עבורו, כך שההודעה נראית ככזו שנשלחה ידנית ואף עוזר לא משתלט על השיחה לאחר מכן. איש קשר קיים משמש כפי שהוא.

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

קריאה מוצלחת עונה ב-202:

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

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

כאשר השליחה אינה עוברת:

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

רישום הערה בשיחה #

POST /contacts/notes

מוסיף שורה לשיחה של איש קשר מבלי לשלוח אותה. השתמש בזה עבור הקשר שהצוות שלך וה-AI צריכים להכיר אך איש הקשר לעולם לא אמור לראות: סיכום של שיחת טלפון שסוכן הקולי שלך בדיוק ביצע, הערה מה-CRM שלך, או הערה מקולגה. זה עובד בכל ערוץ (WhatsApp, SMS, Instagram, Messenger, Telegram, ווידג’ט הצ’אט, ערוצים מותאמים אישית וכן הלאה).

מה קורה להערה:

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

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

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

תגובה (201, או 200 עם duplicate: true כאשר ה-external_id כבר נרשם)

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

הערה מופיעה ב-הצגת הודעות של איש קשר עם type: "note".

יצירת טיוטת תשובה באמצעות ה-AI #

POST /contacts/{contactId}/draft-reply

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

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

כל שדות הגוף הם אופציונליים; גוף ריק (או ללא גוף) יוצר טיוטה לתשובה הבאה.

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

תגובה (200)

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

400 פירושו שבשיחה עדיין אין הודעות, הקרדיטים שלך אזלו, או שלאיש הקשר אין סוכן או קמפיין ליצירת טיוטה ממנו (error מציין איזה מהם). 404 פירושו שאיש הקשר אינו קיים, או שהמפתח של חבר צוות מוגבל לאנשי קשר שהוא אינו יכול לראות. המפתח או חבר הצוות זקוקים להרשאה לעריכת הודעות.

משתמש בלקוח AI מעל MCP? אותה פעולה זמינה ככלי generate_reply_draft.

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

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

שדות הודעה #

הורדת קובץ מצורף להודעה #

POST /chat-exports/media/download-url

מספק לך קישור הורדה חדש עבור הקובץ המצורף להודעה: תמונה, הודעה קולית, סרטון או מסמך. הקישור תקף ל-שעה אחת. השתמש בו כאשר ברצונך לשמור קבצים מצורפים במקום אחר (למשל, תיוק קורות חיים או הודעות קוליות שאיש קשר שלח), או כאשר ה-media_url בהודעה או Webhook של הודעה חדשה אינו נפתח עוד.

כדי למצוא הודעות עם קבצים מצורפים, רשום את הודעות איש הקשר באמצעות filter=media. ה-id של כל הודעה ומזהה איש הקשר מרכיבים את ה-messagePath.

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

תגובה (200 OK):

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

משתמש בלקוח AI מעל MCP? אותה פעולה זמינה ככלי get_chat_media_download_url.

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

סשן צ’אט הוא חלון שיחה אחד עם איש קשר. הוא נפתח עם הודעה נכנסת ראשונה כאשר אין סשן פתוח, והוא נסגר אוטומטית 48 שעות לאחר ההודעה הנכנסת האחרונה של איש הקשר (כל הודעה נכנסת חדשה דוחה את הסגירה ב-48 שעות נוספות). סיום צ’אט על ידי ה-AI אינו סוגר את הסשן; הוא רק מפעיל את ה-webhook של Chat Concluded. סשנים הם הדרך שבה ניתן לחלק היסטוריה ארוכה לשיחות קריאות במקום לרשימה אחת אינסופית.

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

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 מפרט את הסיבה — חלון העריכה של הערוץ נסגר, הערוץ מנותק, להודעה יש קובץ מצורף שהערוץ אינו יכול לערוך (media_not_editable: ב-WhatsApp Web ניתן לערוך רק הודעות טקסט, לא את הטקסט תחת תמונה, סרטון או קובץ), או שמשהו אחר השתבש.

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,
    "human_reply": 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).
• אנשי קשר — צור וחפש את אנשי הקשר שאליהם אתה שולח הודעות.
• פגישות — קבע ונהל פגישות עבור אנשי הקשר שלך.