HAMAVA

راهنمای API و وب‌هوک هماوا

با API هماوا تماس‌ها، رونویسی‌ها، درخواست‌های تماس، گفتگوها و آمار را بخوانید؛ با وب‌هوک، رویدادها لحظه‌ای به سرور شما ارسال می‌شوند.

احراز هویت

کلید را مدیر کسب‌وکار در پنل، بخش «اتصال به CRM» (/manager/integrations) می‌سازد. کلید فقط یک بار نمایش داده می‌شود و با hm_live_ شروع می‌شود. هر کلید فقط به دادهٔ همان کسب‌وکار دسترسی دارد و هر وقت بخواهید قابل ابطال است.

curl https://hamavai.ir/api/v1/me \
  -H "Authorization: Bearer hm_live_xxxxxxxx"

کلید نامعتبر یا ارسال‌نشده پاسخ 401 می‌گیرد. خطاها به شکل {"error": "..."} برمی‌گردند.

صفحه‌بندی

فهرست‌ها جدیدترین را اول برمی‌گردانند. پارامتر limit (حداکثر ۲۰۰) و before_id را بفرستید؛ مقدار next_before_id در پاسخ را برای صفحهٔ بعد استفاده کنید (اگر null بود، صفحهٔ دیگری نیست).

نقاط دسترسی

روش و مسیر	کاربرد
`GET /api/v1/me`	نام و شناسهٔ کسب‌وکار؛ برای آزمایش کلید
`GET /api/v1/calls?limit=&before_id=&status=`	فهرست تماس‌ها
`GET /api/v1/calls/<id>`	جزئیات یک تماس همراه با متن رونویسی
`GET /api/v1/callbacks?status=`	درخواست‌های تماس بازگشتی و پیام‌های صوتی
`POST /api/v1/callbacks`	ثبت درخواست تماس از سیستم شما (بدنهٔ JSON)
`POST /api/v1/callbacks/<id>/done`	بستن درخواست تماس
`GET /api/v1/departments`	بخش‌ها
`GET /api/v1/agents`	کارشناسان
`GET /api/v1/conversations`	گفتگوهای متنی
`GET /api/v1/stats?days=7`	آمار تماس‌ها بر اساس وضعیت

ثبت درخواست تماس

curl -X POST https://hamavai.ir/api/v1/callbacks \
  -H "Authorization: Bearer hm_live_xxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{"phone":"09120000000","name":"علی","message":"پیگیری سفارش","department":"sales","priority":"high"}'

phone الزامی است. department کلید بخش است (از /api/v1/departments) و priority می‌تواند high یا normal باشد. پاسخ موفق 201 است.

وب‌هوک‌ها

در همان صفحهٔ «اتصال به CRM» آدرس HTTPS سرور خود را ثبت کنید و رویدادها را انتخاب کنید:

call.ended — پایان تماس
callback.created — درخواست تماس یا پیام صوتی جدید (پیام صوتی با voicemail: true)
conversation.created — گفتگوی متنی جدید
test.ping — آزمایش اتصال از پنل

هر رویداد با POST و بدنهٔ JSON ارسال می‌شود و این سرآیندها را دارد: X-Hamava-Event، X-Hamava-Delivery و X-Hamava-Signature. اگر سرور شما پاسخ موفق ندهد، ارسال پس از ۱ دقیقه، ۵ دقیقه، ۳۰ دقیقه، ۲ ساعت و ۱۲ ساعت تکرار می‌شود و بعد ناموفق ثبت می‌شود. تاریخچهٔ ارسال‌ها در پنل دیده می‌شود.

بررسی امضای وب‌هوک

امضا برابر sha256= به‌علاوهٔ HMAC-SHA256 بدنهٔ خام درخواست با کلید امضای همان وب‌هوک است. نمونه در پایتون:

import hmac, hashlib

def valid(secret: str, body: bytes, header: str) -> bool:
    expected = "sha256=" + hmac.new(secret.encode(), body, hashlib.sha256).hexdigest()
    return hmac.compare_digest(expected, header or "")