سامانه ارسال پیام در بله (سفیر)

سرویس سفیر، سرویس ارسال پیام در بازوهای بله است که به صورت RESTFUL پیاده‌سازی شده است. با استفاده از این سرویس میتوانید انواع مختلفی از پیامها را برای کاربران موردنظر خود ارسال کنید. برای استفاده api های این سرویس، الزم است Key Access Api سازمان خود را در هر فراخوانی API از سرویس ارسال کنید.

سرویس ارسال پیام

از این سرویس به منظور ارسال پیام به شماره تماس مشخص شده استفاده می شود:

آدرس سرویس ارسال پیام

Protocol: https
Method: POST
Type: JSON
Url: https://safir.bale.ai/api/v3/send_message

ساختار ورودی ارسال پیام

ساختار MessageData

ساختار Message

ساختار شماره تماس‌های ارسالی

برای استفاده از سرویس ارسال پیام، شماره‌های ارسالی باید با پیش شمارٔه ،۹۸ ۹۸+ شروع شود و شامل ده رقم بعد از پیش شماره باشد. هرگونه کاراکترهای اضافی مانند خط، فاصله و نیمخط و ... در شماره تلفن باعث دریافت خطای شماره تماس نامعتبر خواهد شد

✅ نمونه صحیح:

• 989196111003
• +98919611003

❌ نمونه ناصحیح:

• 09196111003
• 0919-611-1003
• 9196111003

ساختار خروجی ارسال پیام

ساختار ErrorInfo

مقادیر Error Code

نحوه استفاده از سرویس ارسال پیام

این api به شما اجازه میدهد که انواع مختلفی از پیامها را تنها با تغییر در مقادیر درخواست، ارسال کنید. در ادامه نحوه ارسال انواع پیامهای مختلف توضیح داده میشود.

ارسال پیام متنی

برای ارسال پیام متنی کافیست Body ریکوئست را به صورت زیر مقداردهی کنید. دقت کنید text را میتوانید به صورت دلخواه تعیین کنید. به جای >message-text-your >متن مورد نظر خود برای ارسال پیام را قرار دهید

نمونه JSON

{
  "request_id": "<random-generated-string>",
  "bot_id": <your-sender-bot-id>,
  "phone_number": "<destination-phone-number>",
  "message_data": {
    "message": {
      "text": "<your-text-message>"
    }
  }
}

نمونه Curl

curl --location 'https://safir.bale.ai/api/v3/send_message' --header 'api-access-key: <user-api-access-key>' --header 'Content-Type: application/json' --data '{
  "request_id": "absdfgesjgo",
  "bot_id": 123456789,
  "phone_number": "989123456789",
  "message_data": {
    "message": {
      "text": "test text message"
    }
  }
}'

✅ پاسخ:

{
  "request_id": "523e6875-7c41-491b-8460-04b33039d7fc",
  "error_data": null
}

ارسال پیام چندرسانه‌ای

برای ارسال پیام چندرسانه‌ای از قبیل عکس یا ویدیو، ابتدا باید با استفاده از سرویس upload file، فایل مورد نظر خود را آپلود کنید و شناسٔه یکتای فایل خود را دریافت کنید. سپس با مقداردهی آن به صورتی که در زیر توضیح داده شده است می‌توانید پیام خود را ارسال کنید.

نمونه JSON

{
  "request_id": "<random-generated-string>",
  "bot_id": <your-sender-bot-id>,
  "phone_number": "<destination-phone-number>",
  "message_data": {
    "message": {
      "text": "<your-message-caption>",
      "file_id": "<your-file-id>"
    }
  }
}

نمونه Curl

curl --location 'https://safir.bale.ai/api/v3/send_message' --header 'api-access-key: <user-api-access-key>' --header 'Content-Type: application/json' --data '{
  "request_id": "absdfgesjgo",
  "bot_id": 123456789,
  "phone_number": "989123456789",
  "message_data": {
    "message": {
      "text": "test caption",
      "file_id": "987141dd2672149..."
    }
  }
}'

✅ پاسخ:

{
  "request_id": "523e6875-7c41-491b-8460-04b33039d7fc",
  "error_data": null
}

ارسال پیام رمزدار

پیام رمزدار قابلیتی‌ست که از آن می‌توان برای ارسال پیام‌های محرمانه توسط بازوها استفاده کرد. این نوع پیام، لایه‌ای از امنیت و حریم خصوصی را برای محتوای ارسالی فراهم می‌کند. برای مشاهدٔه محتوای یک پیام رمزدار، کاربر باید یک رمز عبور صحیح را وارد کند. این ویژگی برای پیام‌هایی که در آن اطلاعات حساس، محرمانه یا شخصی ارسال می‌شوند، بسیار مفید است. برای استفاده از این قابلیت، فارغ از نوع پیامی که قصد ارسال آن را دارید، کافیست فیلد مخصوص آن را فعال کنید تا پیام شما با این قابلیت ارسال شود.

نمونه JSON پیام متنی

{
  "request_id": "<random-generated-string>",
  "bot_id": <your-sender-bot-id>,
  "phone_number": "<destination-phone-number>",
  "message_data": {
    "is_secure": true,
    "message": {
      "text": "<your-text-message>"
    }
  }
}

نمونه JSON پیام چندرسانه‌ای

{
  "request_id": "<random-generated-string>",
  "bot_id": <your-sender-bot-id>,
  "phone_number": "<destination-phone-number>",
  "message_data": {
    "is_secure": true,
    "message": {
      "text": "<your-message-caption>",
      "file_id": "<your-file-id>"
    }
  }
}

نمونه Curl پیام متنی

curl --location 'https://safir.bale.ai/api/v3/send_message' --header 'api-access-key: <user-access-token>' --header 'Content-Type: application/json' --data '{
  "request_id": "absdfgesjgo",
  "bot_id": 123456789,
  "phone_number": "989123456789",
  "message_data": {
    "is_secure": true,
    "message": {
      "text": "test text message"
    }
  }
}'

✅ پاسخ:

{
  "request_id": "523e6875-7c41-491b-8460-04b33039d7fc",
  "error_data": null
}

سرویس بارگذاری فایل

برای مشخص کردن یک فایل در apiهای مختلف لازم است که ابتدا این فایل بارگذاری شود و سپس از آیدی فایل آپلود شده، در دیگر apiها استفاده شود. به این منظور api زیر مورد استفاده قرار می‌گیرد

آدرس سرویس

Protocol: https
Method: POST
Type: FormData
Url: https://safir.bale.ai/api/v3/upload_file

ساختار ورودی

ساختار خروجی

نمونه Curl

curl --location 'https://safir.bale.ai/api/v3/upload_file' /
 --header 'api-access-key:<user-access-token>' /
 --form 'file=@"<file-path>"'

✅ پاسخ:

{
  "file_id": "987141dd2672149..."
}

مدیریت انواع خطا در سرویس ارسال پیام

• تمام سرویس‌ها دارای فیلد error_data هستند.
• ساختار آن برابر با ErrorInfo تعریف‌شده در بخش 1.3.1 است.
• در برخی سرویس‌ها ممکن است فقط یک خطا برگردد، ولی در سرویس ارسال پیام برای هر شماره می‌تواند خطای جداگانه وجود داشته باشد.

مدیریت اثر یکسان ارسال پیام (Idempotency)

• برای جلوگیری از ارسال تکراری پیام از فیلد request_id استفاده کنید.
• در صورتی که همان request_id دوباره ارسال شود → پیام تکراری ارسال نمی‌شود.
• این فیلد اختیاری است، ولی توصیه می‌شود همیشه استفاده شود.