مستندات API خارجی

مقدمه

API سامانه BaleCRM از استانداردهای معماری RESTful پیروی می‌کند و نقاط پایانی منبع‌محور واضح و یکنواختی ارائه می‌دهد. تمام درخواست‌ها و پاسخ‌ها در قالب JSON و با استفاده از افعال HTTP استاندارد، کدهای وضعیت و پروتکل‌های احراز هویت برای یکپارچه‌سازی امن، کارآمد و مقیاس‌پذیر ارسال می‌شوند.

آدرس پایه API

توجه داشته باشید که BaleCRM محیط sandbox یا تست ارائه نمی‌دهد. تمام درخواست‌های API در محیط واقعی پردازش می‌شوند؛ بنابراین قبل از ارسال هر درخواست، از صحت داده‌ها و پارامترها اطمینان حاصل کنید.

string 
https://balecrm.com/external-api

احراز هویت

تمام درخواست‌ها به API سامانه BaleCRM نیاز به احراز هویت دارند. هر درخواست API باید شامل client-id و client-secret معتبر در هدر درخواست باشد که از داشبورد BaleCRM در بخش ابزارهای توسعه‌دهنده قابل دریافت است.

علاوه بر اعتبارنامه‌ها، BaleCRM امنیت مبتنی بر IP را اعمال می‌کند. باید آدرس IP عمومی سرور خود را در بخش IP Whitelist داشبورد ثبت و فعال کنید. درخواست‌هایی که از IPهای غیرمجاز ارسال شوند، به‌طور خودکار رد می‌شوند.

هر دو مورد — اعتبارنامه API معتبر و IP تأییدشده — الزامی هستند. بدون تکمیل این دو مرحله، احراز هویت ناموفق خواهد بود و دسترسی به API امکان‌پذیر نیست.

فرمت پاسخ

تمام پاسخ‌های API سامانه BaleCRM در قالب JSON بازگردانده می‌شوند. هر پاسخ ساختار یکنواختی دارد و شامل نشانگر وضعیت، پیام و داده‌های مرتبط (در صورت وجود) است. کدهای وضعیت HTTP استاندارد برای نمایش نتیجه هر درخواست استفاده می‌شوند.

نمونه پاسخ موفق

JSON 
{
  "status": "success",
  "remark": "contact_list",
  "message": ["Contact list fetched successfully"],
  "data": { ... }
}

نمونه پاسخ خطا

JSON 
{
  "remark": "Unauthorized",
  "status": "error",
  "message": ["The client secret is required"]
}
نمونه کد
php 

$curl = curl_init();

curl_setopt_array($curl, array(
  CURLOPT_URL => 'https://balecrm.com/external-api/contact/list',
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => '',
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 0,
  CURLOPT_FOLLOWLOCATION => true,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => 'GET',
  CURLOPT_HTTPHEADER => array(
    'client-id: YOUR-CLIENT-ID',
    'client-secret: YOUR-CLIENT-SECRET',
  ),
));

$response = curl_exec($curl);

curl_close($curl);
echo $response;

لیست مخاطبین

این نقطه پایانی امکان دریافت لیست کامل مخاطبین مرتبط با حساب BaleCRM شما را فراهم می‌کند.

GET
contact/list
پارامترهای کوئری

پارامترهای کوئری که به شما امکان سفارشی‌سازی پاسخ API را می‌دهند.

نام توضیحات اجباری پیش‌فرض
page شماره صفحه مورد نظر برای دریافت را مشخص می‌کند. خیر 1
paginate تعداد آیتم‌های بازگشتی در هر صفحه را مشخص می‌کند. خیر 20
search جستجوی مخاطبین بر اساس نام، نام خانوادگی یا شماره موبایل. خیر -
نمونه کد
php 

$curl = curl_init();

curl_setopt_array($curl, array(
  CURLOPT_URL => 'https://balecrm.com/external-api/contact/store',
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => '',
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 0,
  CURLOPT_FOLLOWLOCATION => true,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => 'POST',
  CURLOPT_POSTFIELDS => array('firstname' => 'John','lastname' => 'Doe','mobile_code' => '880','mobile' => '01988'),
  CURLOPT_HTTPHEADER => array(
    'client-id: YOUR-CLIENT-ID',
    'client-secret: YOUR-CLIENT-SECRET',
  ),
));

$response = curl_exec($curl);

curl_close($curl);
echo $response;

ایجاد مخاطب جدید

این نقطه پایانی امکان افزودن مخاطب جدید به حساب BaleCRM شما را فراهم می‌کند. جزئیات مخاطب را ارسال کنید؛ در صورت موفقیت، API اطلاعات مخاطب ایجادشده را در قالب JSON برمی‌گرداند.

POST
/contact/store
فیلدهای الزامی

فیلدهای زیر برای ایجاد مخاطب جدید در سیستم الزامی هستند.

فیلد اجباری پیش‌فرض
firstname بله -
lastname بله -
mobile_code بله -
mobile بله -
city خیر -
state خیر -
post_code خیر -
address خیر -
profile_image خیر -
نمونه کد
php 

$curl = curl_init();

curl_setopt_array($curl, array(
  CURLOPT_URL => 'https://balecrm.com/external-api/contact/update/{contactId}',
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => '',
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 0,
  CURLOPT_FOLLOWLOCATION => true,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => 'POST',
  CURLOPT_POSTFIELDS => array('firstname' => 'John','lastname' => 'Doe','mobile_code' => '880','mobile' => '01988'),
  CURLOPT_HTTPHEADER => array(
    'client-id: YOUR-CLIENT-ID',
    'client-secret: YOUR-CLIENT-SECRET',
  ),
));

$response = curl_exec($curl);

curl_close($curl);
echo $response;

به‌روزرسانی مخاطب

این نقطه پایانی به شما امکان به‌روزرسانی یک مخاطب موجود را می‌دهد. فقط فیلدهایی که می‌خواهید تغییر دهید را ارسال کنید. هر فیلدی که در درخواست شامل نشود بدون تغییر باقی می‌ماند.

POST
/contact/update/{id}
بدنه درخواست

فیلدهای زیر برای به‌روزرسانی مخاطب قابل استفاده هستند. فقط فیلدهایی که می‌خواهید تغییر دهید را ارسال کنید.

فیلد اجباری پیش‌فرض
firstname خیر -
lastname خیر -
mobile_code خیر -
mobile خیر -
city خیر -
state خیر -
post_code خیر -
address خیر -
profile_image خیر -
نمونه کد
php 

$curl = curl_init();

curl_setopt_array($curl, array(
  CURLOPT_URL => 'https://balecrm.com/external-api/contact/delete/{contactId}',
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => '',
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 0,
  CURLOPT_FOLLOWLOCATION => true,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => 'DELETE',
  CURLOPT_POSTFIELDS => array('firstname' => 'John','lastname' => 'Doe','mobile_code' => '880','mobile' => '01988'),
  CURLOPT_HTTPHEADER => array(
    'client-id: YOUR-CLIENT-ID',
    'client-secret: YOUR-CLIENT-SECRET',
  ),
));

$response = curl_exec($curl);

curl_close($curl);
echo $response;

حذف مخاطب

این نقطه پایانی به شما امکان حذف یک مخاطب با شناسه منحصربه‌فرد آن را می‌دهد. حذف ممکن است در صورت داشتن پیام‌های مرتبط یا مسدود بودن محدود شود.

DELETE
/contact/delete/{id}
نمونه کد
php 

$curl = curl_init();

curl_setopt_array($curl, array(
  CURLOPT_URL => 'https://balecrm.com/external-api/inbox/conversation-list',
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => '',
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 0,
  CURLOPT_FOLLOWLOCATION => true,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => 'GET',
  CURLOPT_HTTPHEADER => array(
    'client-id: YOUR-CLIENT-ID',
    'client-secret: YOUR-CLIENT-SECRET',
  ),
));

$response = curl_exec($curl);

curl_close($curl);
echo $response;

لیست مکالمات

دریافت لیست صفحه‌بندی‌شده مکالمات برای کاربر احراز هویت‌شده، شامل اطلاعات مخاطب و وضعیت مکالمه.

GET
/inbox/conversation-list

پارامترهای کوئری

نام توضیحات پیش‌فرض
status فیلتر مکالمات بر اساس وضعیت. از مقادیر زیر برای فیلتر مکالمه بر اساس وضعیت استفاده کنید. Done = 1; Pending = 2; Important = 3; Unread = 4; همه
page شماره صفحه مورد نظر برای دریافت را مشخص می‌کند. 1
paginate تعداد آیتم‌های بازگشتی در هر صفحه را مشخص می‌کند. 20
نمونه کد
php 

$curl = curl_init();
curl_setopt_array($curl, array(
  CURLOPT_URL => 'https://balecrm.com/external-api/inbox/change-conversation-status/2',
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => '',
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 0,
  CURLOPT_FOLLOWLOCATION => true,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => 'POST',
  CURLOPT_POSTFIELDS => array('status' => '1'),
  CURLOPT_HTTPHEADER => array(
    'client-id: YOUR-CLIENT-ID',
    'client-secret: YOUR-CLIENT-SECRET',
  ),
));

$response = curl_exec($curl);

curl_close($curl);
echo $response;

تغییر وضعیت مکالمه

وضعیت یک مکالمه مانند در انتظار، انجام‌شده یا مهم را به‌روزرسانی کنید. در اینجا انجام‌شده = 1، در انتظار = 2، مهم = 3 و خوانده‌نشده = 4

POST
/inbox/change-conversation-status/{conversation_id}

پارامترهای URL

پارامتر نوع توضیحات
conversation_id integer شناسه منحصربه‌فرد مکالمه

بدنه درخواست

فیلد نوع اجباری
status integer YEs
نمونه کد
php 

$curl = curl_init();

curl_setopt_array($curl, array(
  CURLOPT_URL => 'https://balecrm.com/external-api/inbox/conversation-details/2',
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => '',
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 0,
  CURLOPT_FOLLOWLOCATION => true,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => 'GET',
  CURLOPT_POSTFIELDS => array('status' => '1'),
  CURLOPT_HTTPHEADER => array(
    'client-id: YOUR-CLIENT-ID',
    'client-secret: YOUR-CLIENT-SECRET',
  ),
));

$response = curl_exec($curl);

curl_close($curl);
echo $response;

جزئیات مکالمه

دریافت جزئیات کامل یک مکالمه شامل اطلاعات مخاطب، یادداشت‌ها، برچسب‌ها و ارتباطات لیست.

GET
/external-api/inbox/conversation-details/{conversation_id}

پارامترهای URL

پارامتر نوع توضیحات
conversation_id integer شناسه منحصربه‌فرد مکالمه
نمونه کد
php 

$curl = curl_init();

curl_setopt_array($curl, array(
  CURLOPT_URL => 'https://balecrm.com/external-api/inbox/send-message',
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => '',
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 0,
  CURLOPT_FOLLOWLOCATION => true,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => 'POST',
  CURLOPT_POSTFIELDS => array('mobile_code' => '880','mobile' => xxxxxxxxx','message' => 'Hello world'),
  CURLOPT_HTTPHEADER => array(
    'client-id: YOUR-CLIENT-ID',
    'client-secret: YOUR-CLIENT-SECRET',
  ),
));
$response = curl_exec($curl);
curl_close($curl);
echo $response;

ارسال پیام

ارسال پیام واتساپ به یک شماره موبایل. این نقطه پایانی از متن، رسانه، موقعیت مکانی، لیست‌های تعاملی، URLهای CTA و پیام‌های فروشگاه آنلاین پشتیبانی می‌کند. اگر مخاطب یا مکالمه‌ای برای شماره تلفن ارائه‌شده یافت نشود، یک مخاطب و مکالمه جدید به صورت خودکار ایجاد خواهد شد.

POST
/inbox/send-message

بدنه درخواست

فیلد نوع اجباری توضیحات
mobile_code string yes کد کشور موبایل. باید یک کد کشور عددی معتبر بدون علامت مثبت (+) باشد.
mobile string yes یک شماره موبایل معتبر مرتبط با کد کشور ارائه‌شده.
from_number string conditional یک شماره تلفن واتساپ بیزینس معتبر ثبت‌شده در حساب شما و داشبورد متا الزامی است. اگر شناسه‌ای ارائه نشود، پیام با استفاده از حساب واتساپ پیش‌فرض ثبت‌شده شما ارسال خواهد شد.
message string Conditional متن پیام. در صورتی که رسانه، موقعیت مکانی یا داده تعاملی ارائه نشده باشد الزامی است
image file No فایل تصویر (jpg، jpeg، png – حداکثر ۵ مگابایت)
document file No فایل سند (pdf، doc، docx – حداکثر ۱۰۰ مگابایت)
video file No فایل ویدیو (mp4 – حداکثر ۱۶ مگابایت)
audio file No فایل صوتی – حداکثر ۱۶ مگابایت
latitude decimal Conditional عرض جغرافیایی برای پیام موقعیت مکانی
longitude decimal Conditional طول جغرافیایی برای پیام موقعیت مکانی
cta_url_id integer No شناسه URL CTA برای پیام‌های دکمه تعاملی
interactive_list_id integer No شناسه لیست تعاملی

یادداشت‌ها

حداقل یک نوع پیام باید ارائه شود.

پیام‌های تعاملی نیاز به پلن فعال دارند.

مخاطبین مسدود نمی‌توانند پیام ارسال یا دریافت کنند.

نمونه کد
php 

$curl = curl_init();

curl_setopt_array($curl, array(
  CURLOPT_URL => 'https://balecrm.com/external-api/inbox/send-template-message',
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => '',
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 0,
  CURLOPT_FOLLOWLOCATION => true,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => 'POST',
  CURLOPT_POSTFIELDS => array('mobile_code' => '880','mobile' => 'xxxxxx','testmplate_id' => 'your template id'),
  CURLOPT_HTTPHEADER => array(
    'client-id: YOUR-CLIENT-ID',
    'client-secret: YOUR-CLIENT-SECRET',
  ),
));

$response = curl_exec($curl);

curl_close($curl);
echo $response;

ارسال پیام قالبی

ارسال یک پیام قالبی تأییدشده واتساپ به یک مکالمه موجود. پیام‌های قالبی معمولاً برای اعلان‌ها، هشدارها و ارتباطات آغازشده توسط کسب‌وکار استفاده می‌شوند.

POST
/external-api/inbox/send-template-message

بدنه درخواست

فیلد نوع اجباری توضیحات
mobile_code string yes کد کشور موبایل. باید یک کد کشور عددی معتبر بدون علامت مثبت (+) باشد.
mobile string yes یک شماره موبایل معتبر مرتبط با کد کشور ارائه‌شده.
from_number string conditional یک شماره تلفن واتساپ بیزینس معتبر ثبت‌شده در حساب شما و داشبورد متا الزامی است. اگر شناسه‌ای ارائه نشود، پیام با استفاده از حساب واتساپ پیش‌فرض ثبت‌شده شما ارسال خواهد شد.
template_id integer Yes شناسه قالب تأییدشده واتساپ

یادداشت‌ها

فقط قالب‌های تأییدشده واتساپ قابل ارسال هستند.

پیام‌های قالبی معمولاً برای مکالمات آغازشده توسط کسب‌وکار استفاده می‌شوند.

مخاطبین مسدود نمی‌توانند پیام‌های قالبی دریافت کنند.

حساب واتساپ باید قبل از ارسال پیام متصل باشد.

نمونه کد
php 

$curl = curl_init();

curl_setopt_array($curl, array(
  CURLOPT_URL => 'https://balecrm.com/external-api/inbox/template-list',
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => '',
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 0,
  CURLOPT_FOLLOWLOCATION => true,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => 'GET',
  CURLOPT_HTTPHEADER => array(
    'client-id: YOUR-CLIENT-ID',
    'client-secret: YOUR-CLIENT-SECRET',
  ),
));

$response = curl_exec($curl);

curl_close($curl);
echo $response;

دریافت لیست قالب‌ها

این نقطه پایانی به شما امکان دریافت تمام قالب‌های واتساپ مرتبط با حساب شما را می‌دهد.

POST
/inbox/template-list