راهنمای درخواست برقراری تک‌زنگ (Call API)

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

آدرس درخواست

با ایجاد درخواست POST به آدرس URL زیر، به شماره تلفنی که همراه بدنه درخواست ارسال می‌کنید، تک‌زنگ زده خواهد شد:

flash-call2.liara.run/services/call/call/

بدنه درخواست (Request Body)

در بدنه درخواست، شماره تلفن مقصد به همراه کلید دسترسی را به فرمت زیر قرار دهید.

{
"destination": "string",
"token": "string"
}

مقصد (destination):

شماره تلفن کاربری است که می‌خواهید به او تک‌زنگ زده شود

توکن (token) :

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

توجه: اگر چندین سرویس با کانفیگ های مختلف دارید مطمئن شوید کلید دسترسی که قرار می‌دهید، کلید ساخته شده از همان سرویسی باشد که می‌خواهید تماس با آن برقرار شود.

بدنه پاسخ (Response Body)

پاسخی که بعد از درخواست زدن دریافت خواهید کرد به فرمت زیر است:

{
"message": "string",
"code": "string",
"tracking_code": "string",
"head_number": "string"
}

پیام (message) :

اعلام می‌کند که وضعیت درخواست شما چگونه بوده است. اگر موفق باشد، پیغام "درخواست با موفقیت انجام شد" را دریافت خواهید کرد، در غیر این صورت خطایی در ارسال درخواست‌تان وجود دارد. برای دیدن شرح خطاهای مختلف، قسمت مدیریت خطاها را مشاهده کنید.

کد (code) :

کدی است که کاربر باید وارد کند (در اصل همان n رقم انتهایی شماره تلفنی است که به کاربر تک‌زنگ زده است)

کد پیگیری (tracking_code) :

جهت متمایز سازی درخواست های سرور و ضمنا پیگیری تماس‌ها در گزارش‌های آینده به کار می رود

سر‌شماره (head_number) :

ارقام ابتدایی شماره تلفنی که با کاربر تماس گرفته را نشان می‌دهد.

مدیریت خطاها

در صورت بروز خطا در فرایند درخواست تماس، شرح خطای ایجاد شده در فیلد message از پاسخ دریافتی قابل مشاهده است. این خطا می تواند به دلیل عواملی از سمت شما مثل اشتباه وارد کردن، منقضی بودن یا غیرفعال بودن کلید دسترسی باشد که در هر کدام از این حالات، پیام مناسب برای فهمیدن علت خطا گزارش می‌شود. همچنین خطا می‌تواند گاهی عامل سمت سرور داشته باشد که در اینگونه مواقع پیغام "درخواست دچار خطا شد" را دریافت خواهید کرد.

نمونه کد

در زیر یک نمونه کد ساده به زبان پایتون، گولنگ و nodejs برای مثال قرار داده شده است که در آن به api تماس فلش‌کال درخواست زده می‌شود. بسته به زبان برنامه نویسی و پلتفرمی که توسعه می‌دهید، سینتکس کد شما ممکن است متفاوت باشد اما منطق کلی آن از الگویی شبیه کد های زیر تبعیت خواهد کرد:

import requests

# URL of the Flash Call service
url = "https://flash-call.liara.run/services/call/call/"

# Request body payload
payload = {
    "destination": "0930xx16xxx",  # The phone number you want to call
    "token": "Ih.nMOjBa3WystRfdnnFzsmt.foqm0O7gFBAm"  # The access token for the service
}

# Send a POST request
response = requests.post(url, json=payload)

# Check the response
if response.status_code == 200:
    print("Call initiated successfully!")
    print("Server response:", response.json())  # Display the server response
else:
    print("Failed to initiate the call!")
    print("Status code:", response.status_code)
    print("Server response:", response.text)  # Display the error message