ממשק ה-API של תבניות WhatsApp #

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

כל הנתיבים להלן יחסיים לכתובת ה-URL הבסיסית של ה-API:

https://api.youraiconnector.com/v1

כל בקשה חייבת לעבור אימות. ראה אימות עבור ארבע השיטות המקובלות. הדוגמאות בדף זה משתמשות בכותרת X-API-Key (ובטופס פרמטר שאילתה אחד עבור cURL).

עבודה עם תת-חשבונות (סוכנויות) #

מצבי אישור #

מכיוון שהודעות שנשלחות מחוץ לשיחה פתוחה חייבות לעבור בדיקה של WhatsApp תחילה, כל תבנית נושאת status אישור:

ניתן לערוך או להגיש (מחדש) רק תבניות במצב draft ו-rejected. ברגע שתבנית היא approved היא נעולה — צור תבנית חדשה אם עליך לבצע שינויים.

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

תבניות בחשבונות המחוברים ל-Meta #

נקודות קצה אלו פועלות באותו אופן ללא קשר לחיבור ה-WhatsApp שבו פועל החשבון שלך, אך מה שקורה מאחורי הקלעים שונה:

• בחיבור WhatsApp מנוהל, תבניות נרשמות אצל ספק ההודעות ו-sid הוא מזהה התוכן של הספק (HXXXXXXXX…).
• בחשבון שמספרו פועל ב-WhatsApp Business Account משלו (אחת מאפשרויות החיבור ל-Meta), תבניות נוצרות ונבדקות בתוך אותו WhatsApp Business Account ו-sid הוא מזהה התבנית של Meta עצמה — מחרוזת מספרית כגון "3394843740694756". status עדיין משתמש בערכים שבטבלה לעיל, ו-rejection_reason עדיין נושא את ההסבר של Meta.

קיימות שתי נקודות קצה נוספות עבור זה: אחת כדי לשאול באיזה חיבור אתה משתמש, ואחת כדי לסנכרן את רשימת התבניות שלך עם ה-WhatsApp Business Account שלך. תבניות שכבר קיימות ב-WhatsApp Business Account מיובאות לספרייה שלך על ידי הסנכרון, כך ש-GET /whatsapp-templates לאחר מכן מציג אותן כמו כל תבנית אחרת.

בדוק באילו תבניות חיבור פועלות #

GET /whatsapp-templates/provider

cURL

curl "https://api.youraiconnector.com/v1/whatsapp-templates/provider?apiKey=YOUR_API_KEY"

JavaScript

const res = await fetch("https://api.youraiconnector.com/v1/whatsapp-templates/provider", {
  headers: { "X-API-Key": "YOUR_API_KEY" },
});
const data = await res.json();

Python

import requests

res = requests.get(
    "https://api.youraiconnector.com/v1/whatsapp-templates/provider",
    headers={"X-API-Key": "YOUR_API_KEY"},
)
data = res.json()

תגובה

{
  "success": true,
  "provider": "meta",
  "lane": "meta_cloud_api",
  "waba_id": "2357661648036355",
  "templates_enabled": true
}

סנכרון תבניות מ-Meta #

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

POST /whatsapp-templates/meta-sync

cURL

curl -X POST "https://api.youraiconnector.com/v1/whatsapp-templates/meta-sync?apiKey=YOUR_API_KEY"

JavaScript

const res = await fetch("https://api.youraiconnector.com/v1/whatsapp-templates/meta-sync", {
  method: "POST",
  headers: { "X-API-Key": "YOUR_API_KEY" },
});
const data = await res.json();

Python

import requests

res = requests.post(
    "https://api.youraiconnector.com/v1/whatsapp-templates/meta-sync",
    headers={"X-API-Key": "YOUR_API_KEY"},
)
data = res.json()

תגובה

{
  "success": true,
  "provider": "meta",
  "imported": 2,
  "updated": 5,
  "total": 12
}

תקשורת ישירה עם Meta (מתקדם) #

אם אתה זקוק למשהו שנקודות הקצה לעיל אינן חושפות — כותרות תבנית, כותרות תחתונות, כפתורים, או תבנית שנבנתה ידנית לחלוטין — /v1/meta-templates מעביר את הבקשה שלך ישירות ל-API התבניות של Meta, מבלי לאחסן דבר בספריית התבניות שלך. זה עובד רק בחשבונות שמספרם פועל ב-WhatsApp Business Account משלהם; בחיבור מנוהל כל קריאה מחזירה 400 המבקש ממך לחבר אפליקציית Meta תחילה.

תבנית ש-Meta מסרבת לה מחזירה 400 עם ההסבר של Meta עצמה ב-error.

הצגת רשימת תבניות #

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

GET /whatsapp-templates

cURL

curl "https://api.youraiconnector.com/v1/whatsapp-templates?apiKey=YOUR_API_KEY"

JavaScript

const res = await fetch("https://api.youraiconnector.com/v1/whatsapp-templates", {
  headers: { "X-API-Key": "YOUR_API_KEY" },
});
const data = await res.json();

Python

import requests

res = requests.get(
    "https://api.youraiconnector.com/v1/whatsapp-templates",
    headers={"X-API-Key": "YOUR_API_KEY"},
)
data = res.json()

תגובה

{
  "success": true,
  "data": [
    {
      "id": "template_abc123",
      "name": "welcome_message",
      "status": "approved",
      "language": "en",
      "body": "Hi {{first_name}}, thanks for reaching out!"
    },
    {
      "id": "template_def456",
      "name": "appointment_reminder",
      "status": "pending",
      "language": "en",
      "body": "Hi {{first_name}}, this is a reminder about your appointment."
    }
  ]
}

קבלת תבנית #

מחזיר את הפרטים המלאים של תבנית בודדת, כולל המשתנים שלה, הסטטוס וחותמות הזמן.

GET /whatsapp-templates/{templateId}

cURL

curl "https://api.youraiconnector.com/v1/whatsapp-templates/template_abc123" \
  -H "X-API-Key: YOUR_API_KEY"

JavaScript

const res = await fetch(
  "https://api.youraiconnector.com/v1/whatsapp-templates/template_abc123",
  { headers: { "X-API-Key": "YOUR_API_KEY" } }
);
const data = await res.json();

Python

import requests

res = requests.get(
    "https://api.youraiconnector.com/v1/whatsapp-templates/template_abc123",
    headers={"X-API-Key": "YOUR_API_KEY"},
)
data = res.json()

תגובה

{
  "success": true,
  "template": {
    "id": "template_abc123",
    "name": "welcome_message",
    "body": "Hi {{first_name}}, thanks for reaching out!",
    "language": "en",
    "variables": ["first_name"],
    "status": "approved",
    "sid": "HXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
    "type": "general",
    "category": "marketing",
    "rejection_reason": null,
    "campaign_id": "campaign123",
    "date_created": "2026-06-01T10:00:00.000Z",
    "date_updated": "2026-06-02T08:30:00.000Z",
    "submitted_at": "2026-06-01T10:05:00.000Z",
    "approved_at": "2026-06-02T08:30:00.000Z"
  }
}

תבנית שאינה קיימת בחשבונך תחזיר 404 עם { "success": false, "error": "Template not found" }.

יצירת תבנית #

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

POST /whatsapp-templates

ניתן לכתוב מצייני מיקום של משתנים כ-{{first_name}}, {first_name} או [first_name] — כולם מנורמלים לצורה של סוגריים מסולסלים כפולים.

התוצאה תלויה בערוצי הקמפיין:

• קמפיין WhatsApp Business API: התוכן נשלח לבדיקת WhatsApp. התגובה נושאת campaign_status (received או pending) ו-template_sid.
• ערוץ ללא שלב בדיקה חיצוני: התבנית נשמרת ומאושרת אוטומטית (campaign_status: "approved", template_sid: null).
• אין ערוץ WhatsApp בקמפיין: דבר לא נוצר ו-campaign_status הוא not_applicable.

cURL

curl -X POST "https://api.youraiconnector.com/v1/whatsapp-templates?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "campaign_id": "campaign123",
    "name": "welcome_message",
    "language": "en",
    "body": "Hi {{first_name}}, thanks for reaching out!",
    "variables": ["first_name"]
  }'

JavaScript

const res = await fetch("https://api.youraiconnector.com/v1/whatsapp-templates", {
  method: "POST",
  headers: {
    "X-API-Key": "YOUR_API_KEY",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    campaign_id: "campaign123",
    name: "welcome_message",
    language: "en",
    body: "Hi {{first_name}}, thanks for reaching out!",
    variables: ["first_name"],
  }),
});
const data = await res.json();

Python

import requests

res = requests.post(
    "https://api.youraiconnector.com/v1/whatsapp-templates",
    headers={"X-API-Key": "YOUR_API_KEY"},
    json={
        "campaign_id": "campaign123",
        "name": "welcome_message",
        "language": "en",
        "body": "Hi {{first_name}}, thanks for reaching out!",
        "variables": ["first_name"],
    },
)
data = res.json()

תגובה (הוגש לבדיקה)

{
  "success": true,
  "campaign_status": "pending",
  "template_sid": "HXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX"
}

יצירת תבנית עצמאית #

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

POST /whatsapp-templates/docs

תבניות אימות (קוד חד-פעמי). WhatsApp אינה מקבלת תבניות אימות בטקסט חופשי: גוף ההודעה מוגדר מראש על ידי WhatsApp והתבנית חייבת לכלול כפתור “העתק קוד”. כאשר אתה יוצר תבנית עם category: "authentication", אנו מגישים אותה עבורך במבנה קבוע זה. ה-body שלך נשמר כתצוגה המקדימה המוצגת באפליקציה, אך הטקסט שהאיש קשר שלך מקבל הוא הניסוח של WhatsApp עצמה (הקוד, תזכורת אבטחה והערה על תוקף של 10 דקות). הגדר משתנה אחד בדיוק, לדוגמה ["code"], והעבר את הקוד בעת השליחה (ראה את השדה variables ב-שלח תבנית לאיש קשר). הקוד חייב להיות קצר מ-15 תווים.

באיזו פעולת יצירה כדאי להשתמש? השתמש בזו כאשר ברצונך ליצור תבנית שתוכל לערוך ולהגיש בעצמך. השתמש ב-POST /whatsapp-templates (למעלה) כאשר ברצונך להגדיר את הודעת הפתיחה של קמפיין — פעולה זו דורשת campaign_id וכותבת ישירות לתוך הקמפיין.

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

cURL

curl -X POST "https://api.youraiconnector.com/v1/whatsapp-templates/docs?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "welcome_message",
    "language": "en",
    "body": "Hi {{first_name}}, thanks for reaching out!",
    "variables": ["first_name"],
    "status": "draft",
    "category": "marketing"
  }'

JavaScript

const res = await fetch("https://api.youraiconnector.com/v1/whatsapp-templates/docs", {
  method: "POST",
  headers: {
    "X-API-Key": "YOUR_API_KEY",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    name: "welcome_message",
    language: "en",
    body: "Hi {{first_name}}, thanks for reaching out!",
    variables: ["first_name"],
    status: "draft",
    category: "marketing",
  }),
});
const data = await res.json();

Python

import requests

res = requests.post(
    "https://api.youraiconnector.com/v1/whatsapp-templates/docs",
    headers={"X-API-Key": "YOUR_API_KEY"},
    json={
        "name": "welcome_message",
        "language": "en",
        "body": "Hi {{first_name}}, thanks for reaching out!",
        "variables": ["first_name"],
        "status": "draft",
        "category": "marketing",
    },
)
data = res.json()

תגובה

{
  "success": true,
  "template_id": "template_abc123",
  "status": "draft"
}

name, language או body חסרים, שפה שאינה נתמכת, status שאינו draft או submitted, type או category לא ידועים, או גוף הודעה העולה על 1024 תווים יחזירו 400 עם error הסברי. campaign_id שאינו אחד מהקמפיינים שלך יחזיר 404.

עדכון תבנית #

עורך תבנית שטרם אושרה. ניתן לערוך רק תבניות עם סטטוס draft או rejected. ספק כל שילוב של name, body, language ו-variables — רק השדות שתשלח ישונו.

PUT /whatsapp-templates/{templateId}

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

cURL

curl -X PUT "https://api.youraiconnector.com/v1/whatsapp-templates/template_abc123" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "body": "Hi {{first_name}}, here is an update for you.",
    "variables": ["first_name"]
  }'

JavaScript

const res = await fetch(
  "https://api.youraiconnector.com/v1/whatsapp-templates/template_abc123",
  {
    method: "PUT",
    headers: {
      "X-API-Key": "YOUR_API_KEY",
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      body: "Hi {{first_name}}, here is an update for you.",
      variables: ["first_name"],
    }),
  }
);
const data = await res.json();

Python

import requests

res = requests.put(
    "https://api.youraiconnector.com/v1/whatsapp-templates/template_abc123",
    headers={"X-API-Key": "YOUR_API_KEY"},
    json={
        "body": "Hi {{first_name}}, here is an update for you.",
        "variables": ["first_name"],
    },
)
data = res.json()

תגובה

{
  "success": true,
  "template_id": "template_abc123"
}

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

הגשת תבנית לאישור #

מגיש תבנית draft או rejected לבדיקה. תבניות בערוץ שאינו דורש בדיקה חיצונית מאושרות באופן מיידי; כל השאר נשלחות ל-WhatsApp וה-status שמוחזר (בדרך כלל received או pending) נשמר בתבנית.

POST /whatsapp-templates/{templateId}/submit

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

cURL

curl -X POST "https://api.youraiconnector.com/v1/whatsapp-templates/template_abc123/submit" \
  -H "X-API-Key: YOUR_API_KEY"

JavaScript

const res = await fetch(
  "https://api.youraiconnector.com/v1/whatsapp-templates/template_abc123/submit",
  { method: "POST", headers: { "X-API-Key": "YOUR_API_KEY" } }
);
const data = await res.json();

Python

import requests

res = requests.post(
    "https://api.youraiconnector.com/v1/whatsapp-templates/template_abc123/submit",
    headers={"X-API-Key": "YOUR_API_KEY"},
)
data = res.json()

תגובה

{
  "success": true,
  "template_id": "template_abc123",
  "status": "pending",
  "sid": "HXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX"
}

בדיקת סטטוס אישור #

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

GET /whatsapp-templates/{templateId}/status

cURL

curl "https://api.youraiconnector.com/v1/whatsapp-templates/template_abc123/status" \
  -H "X-API-Key: YOUR_API_KEY"

JavaScript

const res = await fetch(
  "https://api.youraiconnector.com/v1/whatsapp-templates/template_abc123/status",
  { headers: { "X-API-Key": "YOUR_API_KEY" } }
);
const data = await res.json();

Python

import requests

res = requests.get(
    "https://api.youraiconnector.com/v1/whatsapp-templates/template_abc123/status",
    headers={"X-API-Key": "YOUR_API_KEY"},
)
data = res.json()

תגובה

{
  "success": true,
  "template_id": "template_abc123",
  "name": "welcome_message",
  "status": "approved",
  "sid": "HXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
  "rejection_reason": null,
  "date_updated": "2026-06-02T08:30:00.000Z"
}

מחיקת תבנית #

מסיר את רשומת התבנית מהחשבון שלך.

DELETE /whatsapp-templates/{templateId}

cURL

curl -X DELETE "https://api.youraiconnector.com/v1/whatsapp-templates/template_abc123" \
  -H "X-API-Key: YOUR_API_KEY"

JavaScript

const res = await fetch(
  "https://api.youraiconnector.com/v1/whatsapp-templates/template_abc123",
  { method: "DELETE", headers: { "X-API-Key": "YOUR_API_KEY" } }
);
const data = await res.json();

Python

import requests

res = requests.delete(
    "https://api.youraiconnector.com/v1/whatsapp-templates/template_abc123",
    headers={"X-API-Key": "YOUR_API_KEY"},
)
data = res.json()

תגובה

{
  "success": true,
  "template_id": "template_abc123",
  "note": "The template record was removed from your account. Content already approved by WhatsApp may remain registered with the messaging provider."
}

שליחת תבנית לאיש קשר #

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

POST /whatsapp-templates/send

גוף התבנית תומך בהחלפת משתנים מתקדמת:

• משתנים בסיסיים: {{first_name}}, {{email}}, {{company}}
• ערכי ברירת מחדל: {{first_name|there}} מציג את there אם השדה ריק
• טרנספורמציות: {{company|uppercase}}, {{name|lowercase}}, {{name|capitalize}}
• משולב: {{company|Your Company|uppercase}}

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

cURL

curl -X POST "https://api.youraiconnector.com/v1/whatsapp-templates/send?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "contactId": "contact123",
    "whatsappTemplateId": "template_abc123"
  }'

JavaScript

const res = await fetch("https://api.youraiconnector.com/v1/whatsapp-templates/send", {
  method: "POST",
  headers: {
    "X-API-Key": "YOUR_API_KEY",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    contactId: "contact123",
    whatsappTemplateId: "template_abc123",
  }),
});
const data = await res.json();

Python

import requests

res = requests.post(
    "https://api.youraiconnector.com/v1/whatsapp-templates/send",
    headers={"X-API-Key": "YOUR_API_KEY"},
    json={
        "contactId": "contact123",
        "whatsappTemplateId": "template_abc123",
    },
)
data = res.json()

תגובה

{
  "success": true,
  "data": "WhatsApp template message sent successfully"
}

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

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

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

POST /whatsapp-templates/campaign/{campaignId} יוצר את תבנית הפתיחה של הקמפיין. PUT /whatsapp-templates/campaign/{campaignId} עורך אותה — על הקמפיין להיות בעל תבנית קיימת, אחרת תוחזר שגיאת 400.

cURL (יצירה)

curl -X POST "https://api.youraiconnector.com/v1/whatsapp-templates/campaign/campaign123?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "welcome_message",
    "language": "en",
    "body": "Hi {{first_name}}, thanks for reaching out!",
    "variables": ["first_name"]
  }'

JavaScript

const res = await fetch("https://api.youraiconnector.com/v1/whatsapp-templates/campaign/campaign123", {
  method: "POST",
  headers: {
    "X-API-Key": "YOUR_API_KEY",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    name: "welcome_message",
    language: "en",
    body: "Hi {{first_name}}, thanks for reaching out!",
    variables: ["first_name"],
  }),
});
const data = await res.json();

Python

import requests

res = requests.post(
    "https://api.youraiconnector.com/v1/whatsapp-templates/campaign/campaign123",
    headers={"X-API-Key": "YOUR_API_KEY"},
    json={
        "name": "welcome_message",
        "language": "en",
        "body": "Hi {{first_name}}, thanks for reaching out!",
        "variables": ["first_name"],
    },
)
data = res.json()

תגובה

{
  "success": true,
  "campaign_status": "pending",
  "template_sid": "HXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
  "message": "WhatsApp template created and campaign updated successfully."
}

כדי לערוך, החלף את השיטה ל-PUT ואת אותם השדות — פעולה זו מגישה מחדש את תבנית הפתיחה (ואת טיוטות ההמשך של הקמפיין, בקמפיין WhatsApp API) לבדיקה.

קמפיין שאינו שייך לחשבונך יחזיר 404; קמפיין השייך לחשבון אחר שאינך מורשה לגשת אליו יחזיר 403. עריכת קמפיין ללא תבנית קיימת תחזיר 400.

שליחת תבנית לאיש קשר קיים #

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

POST /whatsapp-templates/{templateId}/send-to-contact

cURL

curl -X POST "https://api.youraiconnector.com/v1/whatsapp-templates/template_abc123/send-to-contact?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "contactId": "contact123" }'

JavaScript

const res = await fetch(
  "https://api.youraiconnector.com/v1/whatsapp-templates/template_abc123/send-to-contact",
  {
    method: "POST",
    headers: {
      "X-API-Key": "YOUR_API_KEY",
      "Content-Type": "application/json",
    },
    body: JSON.stringify({ contactId: "contact123" }),
  }
);
const data = await res.json();

Python

import requests

res = requests.post(
    "https://api.youraiconnector.com/v1/whatsapp-templates/template_abc123/send-to-contact",
    headers={"X-API-Key": "YOUR_API_KEY"},
    json={"contactId": "contact123"},
)
data = res.json()

תגובה

{
  "success": true,
  "data": "WhatsApp template message sent successfully"
}

קרדיטים: שליחה צורכת קרדיטים, המתומחרים באותו אופן כמו בנקודת הקצה לעיל. contactId שחסר או שאינו בחשבונך יחזיר 403; templateId שאינו קיים יחזיר 404.

שליחה מרוכזת (Bulk) של תבנית #

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

הערכת העלות תחילה #

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

POST /whatsapp-templates/{templateId}/estimate-bulk-cost

cURL

curl -X POST "https://api.youraiconnector.com/v1/whatsapp-templates/template_abc123/estimate-bulk-cost?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "contactIds": ["contact123", "contact456"] }'

JavaScript

const res = await fetch(
  "https://api.youraiconnector.com/v1/whatsapp-templates/template_abc123/estimate-bulk-cost",
  {
    method: "POST",
    headers: {
      "X-API-Key": "YOUR_API_KEY",
      "Content-Type": "application/json",
    },
    body: JSON.stringify({ contactIds: ["contact123", "contact456"] }),
  }
);
const data = await res.json();

Python

import requests

res = requests.post(
    "https://api.youraiconnector.com/v1/whatsapp-templates/template_abc123/estimate-bulk-cost",
    headers={"X-API-Key": "YOUR_API_KEY"},
    json={"contactIds": ["contact123", "contact456"]},
)
data = res.json()

תגובה

{
  "success": true,
  "data": {
    "countries": [
      {
        "countryCode": "1",
        "name": "United States",
        "iso": "US",
        "flag": "🇺🇸",
        "contactCount": 120,
        "costPerContact": 0.5,
        "subtotal": 60.0
      }
    ],
    "totalContacts": 120,
    "totalTemplateCost": 60.0,
    "templateCategory": "marketing",
    "skippedContacts": 2
  }
}

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

שליחת האצווה #

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

POST /whatsapp-templates/{templateId}/bulk-send

cURL

curl -X POST "https://api.youraiconnector.com/v1/whatsapp-templates/template_abc123/bulk-send?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "contactIds": ["contact123", "contact456"] }'

JavaScript

const res = await fetch(
  "https://api.youraiconnector.com/v1/whatsapp-templates/template_abc123/bulk-send",
  {
    method: "POST",
    headers: {
      "X-API-Key": "YOUR_API_KEY",
      "Content-Type": "application/json",
    },
    body: JSON.stringify({ contactIds: ["contact123", "contact456"] }),
  }
);
const data = await res.json();

Python

import requests

res = requests.post(
    "https://api.youraiconnector.com/v1/whatsapp-templates/template_abc123/bulk-send",
    headers={"X-API-Key": "YOUR_API_KEY"},
    json={"contactIds": ["contact123", "contact456"]},
)
data = res.json()

תגובה

{
  "success": true,
  "data": { "sent": 118, "failed": 2, "total": 120 }
}

איש קשר שנכשל (לא נמצא, לא בחשבון שלך, או שגיאת שליחה) מדלגים עליו והוא נספר ב-failed במקום לעצור את האצווה. contactIds ריק, יותר מ-5000 מזהים בשליחה (500 בהערכה), או templateId חסר יחזירו 400.

ניסיון חוזר להודעה שנכשלה #

שתי נקודות קצה לשליחה חוזרת של הודעה שנכשלה, מבלי ליצור רשומת הודעה חדשה או לבזבז קרדיטים שוב.

POST /whatsapp-templates/messages/{contactId}/{messageId}/retry-template מבצע ניסיון חוזר להודעת תבנית שנכשלה באופן ספציפי — הוא פותר מחדש את תוכן התבנית מהקמפיין אם ההודעה שנכשלה אינה נושאת אותו כבר. רק הודעות עם סטטוס failed וסוג template ניתנות לניסיון חוזר בדרך זו.

POST /whatsapp-templates/messages/{contactId}/{messageId}/retry הוא אגנוסטי לערוץ ועובד עבור כל הודעה שאינה תבנית שנכשלה (למשל WhatsApp Web), ושולח לנתיב השליחה הנכון בהתבסס על הערוץ של ההודעה. הוא מקבל סטטוס failed, failed_connection, limit_exceeded, או queued_retry.

אף אחת מנקודות הקצה אינה מקבלת גוף בקשה.

cURL

curl -X POST "https://api.youraiconnector.com/v1/whatsapp-templates/messages/contact123/msg_abc789/retry-template?apiKey=YOUR_API_KEY"

JavaScript

const res = await fetch(
  "https://api.youraiconnector.com/v1/whatsapp-templates/messages/contact123/msg_abc789/retry-template",
  { method: "POST", headers: { "X-API-Key": "YOUR_API_KEY" } }
);
const data = await res.json();

Python

import requests

res = requests.post(
    "https://api.youraiconnector.com/v1/whatsapp-templates/messages/contact123/msg_abc789/retry-template",
    headers={"X-API-Key": "YOUR_API_KEY"},
)
data = res.json()

תגובה

{
  "success": true,
  "data": "Message retry initiated successfully"
}

עבור הגרסה האגנוסטית לערוץ, החלף את הנתיב ל-.../msg_abc789/retry. הודעה שהסטטוס שלה אינו זכאי לניסיון חוזר, או (בנקודת הקצה של התבנית) שאינה הודעת תבנית, תחזיר 400. איש קשר או הודעה חסרים יחזירו 404.

פרופיל WhatsApp Business #

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

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

PUT /whatsapp-templates/profile

cURL

curl -X PUT "https://api.youraiconnector.com/v1/whatsapp-templates/profile?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "phoneNumber": "+31612345678",
    "about": "We reply within a few hours",
    "email": "support@example.com",
    "websites": ["https://example.com"]
  }'

JavaScript

const res = await fetch("https://api.youraiconnector.com/v1/whatsapp-templates/profile", {
  method: "PUT",
  headers: {
    "X-API-Key": "YOUR_API_KEY",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    phoneNumber: "+31612345678",
    about: "We reply within a few hours",
    email: "support@example.com",
    websites: ["https://example.com"],
  }),
});
const data = await res.json();

Python

import requests

res = requests.put(
    "https://api.youraiconnector.com/v1/whatsapp-templates/profile",
    headers={"X-API-Key": "YOUR_API_KEY"},
    json={
        "phoneNumber": "+31612345678",
        "about": "We reply within a few hours",
        "email": "support@example.com",
        "websites": ["https://example.com"],
    },
)
data = res.json()

תגובה

{
  "success": true,
  "data": "WhatsApp Business profile updated successfully"
}

ערך phoneNumber חסר, כתובת אתר לא תקינה, או phoneNumber שאינו מחובר לחשבונך יחזירו 400 או 404.

העלאת תמונת פרופיל #

מוריד תמונה מכתובת URL שאתה מספק ומעלה אותה ל-WhatsApp, תוך החזרת מזהה (handle). העבר את המזהה הזה כ-profilePictureHandle בקריאת שמירת הפרופיל לעיל כדי להגדיר אותה כתמונה — נקודת קצה זו רק מעלה את התמונה, היא אינה מגדירה אותה בעצמה.

POST /whatsapp-templates/profile/picture

cURL

curl -X POST "https://api.youraiconnector.com/v1/whatsapp-templates/profile/picture?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "phoneNumber": "+31612345678",
    "fileUrl": "https://example.com/logo.png"
  }'

JavaScript

const res = await fetch("https://api.youraiconnector.com/v1/whatsapp-templates/profile/picture", {
  method: "POST",
  headers: {
    "X-API-Key": "YOUR_API_KEY",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    phoneNumber: "+31612345678",
    fileUrl: "https://example.com/logo.png",
  }),
});
const data = await res.json();

Python

import requests

res = requests.post(
    "https://api.youraiconnector.com/v1/whatsapp-templates/profile/picture",
    headers={"X-API-Key": "YOUR_API_KEY"},
    json={
        "phoneNumber": "+31612345678",
        "fileUrl": "https://example.com/logo.png",
    },
)
data = res.json()

תגובה

{
  "success": true,
  "data": "1234567890123456"
}

data הוא המזהה של התמונה שהועלתה. ערך phoneNumber או fileUrl חסר, או phoneNumber ללא אסימון גישה ל-WhatsApp בתיעוד, יחזירו 400; כתובת fileUrl שאינה נגישה או אינה תקינה תחזיר שגיאה המתארת מדוע ההורדה נכשלה.

בדיקת סטטוס השולח #

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

GET /whatsapp-templates/sender-status/{phoneNumber}

cURL

curl "https://api.youraiconnector.com/v1/whatsapp-templates/sender-status/+31612345678" \
  -H "X-API-Key: YOUR_API_KEY"

JavaScript

const res = await fetch(
  "https://api.youraiconnector.com/v1/whatsapp-templates/sender-status/+31612345678",
  { headers: { "X-API-Key": "YOUR_API_KEY" } }
);
const data = await res.json();

Python

import requests

res = requests.get(
    "https://api.youraiconnector.com/v1/whatsapp-templates/sender-status/+31612345678",
    headers={"X-API-Key": "YOUR_API_KEY"},
)
data = res.json()

תגובה

{
  "success": true,
  "data": "ONLINE"
}

data הוא אחד מ-ONLINE (שולח כרגיל), PENDING (עדיין בתהליך אימות), או DELETED (הספק אינו מזהה יותר שולח זה — חבר מחדש את המספר). ערך phoneNumber ללא פרטי WhatsApp Business בתיעוד יחזיר 404.

יצירת תבניות המשך באמצעות בינה מלאכותית #

הפלטפורמה יכולה לכתוב עבורך תבניות המשך (WhatsApp follow-up) לקמפיין — אותן תזכורות שנשלחות כאשר שיחה הופכת לשקטה — בהתבסס על ההנחיות והמטרה של הקמפיין עצמו. קיים נקודת קצה (endpoint) אחת של משימות הפועלת ברקע, בנוסף לשלוש נקודות קצה ישנות יותר שנשמרו עבור אינטגרציות קיימות. כולן משתמשות בקרדיטים של בינה מלאכותית.

התחלת משימת יצירה #

POST /campaigns/{campaignId}/template-generation

cURL

curl -X POST "https://api.youraiconnector.com/v1/campaigns/campaign_abc123/template-generation?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "type": "all" }'

JavaScript

const res = await fetch(
  "https://api.youraiconnector.com/v1/campaigns/campaign_abc123/template-generation",
  {
    method: "POST",
    headers: {
      "X-API-Key": "YOUR_API_KEY",
      "Content-Type": "application/json",
    },
    body: JSON.stringify({ type: "all" }),
  }
);
const data = await res.json();

Python

import requests

res = requests.post(
    "https://api.youraiconnector.com/v1/campaigns/campaign_abc123/template-generation",
    headers={"X-API-Key": "YOUR_API_KEY"},
    json={"type": "all"},
)
data = res.json()

תגובה (202)

{ "success": true, "campaign_id": "campaign_abc123", "type": "all" }

הקריאה חוזרת ברגע שהמשימה בתור. קרא את הקמפיין (GET /campaigns/{campaignId}, ראה את API של קמפיינים) ועקוב אחר אובייקט ה-template_generation_status שלו עד לסיום:

התבניות שנוצרו מתווספות לקמפיין כמו כל תבנית אחרת, לכן הן מופיעות ב-רשימת תבניות ועדיין עוברות אישור של WhatsApp לפני שניתן לשלוח אותן. 400 פירושו ש-type היה משהו אחר מלבד all או cold_only; 404 פירושו שהקמפיין לא קיים או שייך לחשבון אחר.

לסוכנים יש תאום לקריאה זו, POST /agents/{agentId}/template-generation, שכותב את הודעות ההמשך עבור סוכן ומסתיים במהלך הקריאה במקרה הרגיל — ראה יצירת הודעות המשך ב-API של סוכני בינה מלאכותית.

נקודות הקצה הישנות ליצירה #

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

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

שגיאות ב-API של תבניות #

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

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

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

צעדים הבאים #

• אימות — ארבע הדרכים לאימות בקשה.
• שגיאות ומגבלות קצב — קודי סטטוס ומגבלת 300 בקשות לדקה.
• API של קמפיינים — ניהול הקמפיינים שאליהם מצורפות תבניות.