Introduction

The BaleCRM API follows RESTful architecture standards, offering clear and consistent resource-based endpoints. All requests and responses are transmitted in JSON format, leveraging standard HTTP verbs, status codes, and authentication protocols to enable secure, efficient, and scalable integrations.

API Base URL

Please note that BaleCRM does not provide a sandbox or test environment. All API requests are processed in the live environment, so ensure that all request data and parameters are accurate before making any calls.

https://balecrm.com/external-api

Authentication

All requests to the BaleCRM API require authentication. Each API request must include a valid client-id and client-secret to the request header, which can be obtained from your BaleCRM Dashboard under Developer Tools.

In addition to credentials, BaleCRM enforces IP-based security. You must register and enable your server’s public IP address in the IP Whitelist section of the dashboard. Requests originating from non-whitelisted IP addresses will be automatically rejected.

Both valid API credentials and an approved IP address are mandatory. Without completing these two steps, authentication will fail and API access will not be granted.

Response Format

All responses from the BaleCRM API are returned in JSON format. Each response follows a consistent structure and includes a status indicator, message, and relevant data payload when applicable. Standard HTTP status codes are used to represent the outcome of each request.

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

{
"status": "success",
"remark": "contact_list",
"message":[
    "Contact list fetched successfully"
],
"data": {
   ...you get all data here
    }
}

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

{
    "remark": "Unauthorized",
    "status": "error",
    "message": [
        "The client secret is required"
    ]
}

 {
    "remark": "Unauthorized",
    "status": "error",
    "message": [
        "Access to this API endpoint is restricted to IP addresses that have been explicitly whitelisted.",
        "In order to access this API endpoint, please add your IP address (::1) to the white list from the user dashboard."
    ]
}


$curl = curl_init();

curl_setopt_array($curl, array(
  CURLOPT_URL => 'https://balecrm.com/extern-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;

Get Contact List

This endpoint allows you to retrieve a complete list of contacts associated with your BaleCRM account.

GET

contact/list

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

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

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


$curl = curl_init();

curl_setopt_array($curl, array(
  CURLOPT_URL => 'https://balecrm.com/extern-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;

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

This endpoint allows you to add a new contact to your BaleCRM account. Provide the necessary contact details, and upon successful request, the API returns the created contact’s information in JSON format for easy integration.

POST

/contact/store

فیلدهای الزامی

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

نام	الزامی	پیش‌فرض
`نام`	بله	-
`نام خانوادگی`	بله	-
`کد موبایل`	بله	-
`موبایل`	بله	-
`شهر`	خیر	-
`استان`	خیر	-
`کد پستی`	خیر	-
`آدرس`	خیر	-
`تصویر پروفایل`	خیر	-


$curl = curl_init();

curl_setopt_array($curl, array(
  CURLOPT_URL => 'https://balecrm.com/extern-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}

فیلدهای الزامی

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

نام	الزامی	پیش‌فرض
`نام`	بله	-
`نام خانوادگی`	بله	-
`کد موبایل`	بله	-
`موبایل`	بله	-
`شهر`	خیر	-
`استان`	خیر	-
`کد پستی`	خیر	-
`آدرس`	خیر	-
`تصویر پروفایل`	خیر	-


$curl = curl_init();

curl_setopt_array($curl, array(
  CURLOPT_URL => 'https://balecrm.com/extern-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}


$curl = curl_init();

curl_setopt_array($curl, array(
  CURLOPT_URL => 'https://balecrm.com/extern-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;	همه
`صفحه`	شماره صفحه مورد نظر برای دریافت را مشخص می‌کند.	1
`صفحه‌بندی`	تعداد آیتم‌های بازگشتی در هر صفحه را مشخص می‌کند.	20


$curl = curl_init();
curl_setopt_array($curl, array(
  CURLOPT_URL => 'https://balecrm.com/extern-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


$curl = curl_init();

curl_setopt_array($curl, array(
  CURLOPT_URL => 'https://balecrm.com/extern-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	شناسه منحصربه‌فرد مکالمه


$curl = curl_init();

curl_setopt_array($curl, array(
  CURLOPT_URL => 'https://balecrm.com/extern-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	شناسه لیست تعاملی

یادداشت‌ها

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

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

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


$curl = curl_init();

curl_setopt_array($curl, array(
  CURLOPT_URL => 'https://balecrm.com/extern-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	شناسه قالب تأییدشده واتساپ

یادداشت‌ها

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

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

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

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


$curl = curl_init();

curl_setopt_array($curl, array(
  CURLOPT_URL => 'https://balecrm.com/extern-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