API Reference

Base URL

تمام درخواست‌های API از این آدرس شروع می‌شن:

https://myshahoo.ir/api/v1/

احراز هویت

برای دسترسی به API، باید در هر درخواست یک هدر Authorization ارسال کنی:

Authorization: Bearer YOUR_API_KEY

دریافت کلید API

1. در پنل، برو به تنظیمات ← امنیت
2. در بخش کلیدهای API، روی ساخت کلید جدید کلیک کن
3. یک نام برای کلید انتخاب کن (مثلاً «وب‌سایت اصلی»)
4. دسترسی‌های موردنظر رو تعیین کن
5. تأیید کن

پاسخ‌های خطا

API شاهو از کدهای استاندارد HTTP استفاده می‌کنه:

کد	معنی
200	موفق
201	ایجاد موفق
400	درخواست نامعتبر
401	احراز هویت نشده
403	دسترسی ممنوع
404	یافت نشد
429	تعداد درخواست‌ها زیاد
500	خطای سرور

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

{
    "error": "invalid_api_key",
    "message": "کلید API نامعتبر است",
    "code": 401
}

Endpoint: مکالمه‌ها

لیست مکالمه‌ها

GET /api/v1/conversations/

پارامترهای Query:

پارامتر	نوع	توضیح
status	string	open / pending / closed
channel	string	whatsapp / instagram / telegram / website
page	int	شماره صفحه (پیش‌فرض ۱)
per_page	int	تعداد در هر صفحه (حداکثر ۱۰۰)

نمونه درخواست:

curl -X GET "https://myshahoo.ir/api/v1/conversations/?status=open&per_page=20" \
     -H "Authorization: Bearer YOUR_API_KEY"

نمونه پاسخ:

{
    "ok": true,
    "count": 42,
    "page": 1,
    "per_page": 20,
    "results": [
        {
            "id": "conv_abc123",
            "status": "open",
            "channel": "whatsapp",
            "customer": {
                "id": "cust_xyz789",
                "name": "مریم رضایی",
                "phone": "09123456789"
            },
            "unread_count": 3,
            "last_message_at": "2025-09-30T14:32:00Z",
            "created_at": "2025-09-28T10:15:00Z"
        }
    ]
}

دریافت یک مکالمه

GET /api/v1/conversations/{id}/

نمونه درخواست:

curl -X GET "https://myshahoo.ir/api/v1/conversations/conv_abc123/" \
     -H "Authorization: Bearer YOUR_API_KEY"

ارسال پیام در مکالمه

POST /api/v1/conversations/{id}/messages/

بدنه درخواست:

{
    "content": "سلام، چطور می‌تونم کمکتون کنم؟"
}

نمونه درخواست:

curl -X POST "https://myshahoo.ir/api/v1/conversations/conv_abc123/messages/" \
     -H "Authorization: Bearer YOUR_API_KEY" \
     -H "Content-Type: application/json" \
     -d '{"content":"سلام، چطور می‌تونم کمکتون کنم؟"}'

بستن مکالمه

POST /api/v1/conversations/{id}/close/

Endpoint: مشتریان

لیست مشتریان

GET /api/v1/customers/

پارامترهای Query:

پارامتر	نوع	توضیح
search	string	جستجو در نام، شماره، ایمیل
status	string	lead / regular / vip / lost
tag	string	فیلتر بر اساس تگ

ایجاد مشتری جدید

POST /api/v1/customers/

بدنه درخواست:

{
    "first_name": "مریم",
    "last_name": "رضایی",
    "phone": "09123456789",
    "email": "maryam@example.com",
    "status": "lead",
    "notes": "علاقه‌مند به پلن Growth"
}

به‌روزرسانی مشتری

PATCH /api/v1/customers/{id}/

حذف مشتری

DELETE /api/v1/customers/{id}/

Endpoint: پیام‌ها

ارسال پیام به مشتری

POST /api/v1/messages/send/

بدنه درخواست:

{
    "customer_id": "cust_xyz789",
    "channel": "whatsapp",
    "content": "سلام، سفارشتون آماده‌ست"
}

پاسخ موفق:

{
    "ok": true,
    "message_id": "msg_def456",
    "status": "sent",
    "sent_at": "2025-09-30T14:35:00Z"
}

Endpoint: گزارش‌ها

آمار کلی

GET /api/v1/analytics/overview/

پاسخ:

{
    "ok": true,
    "period": {
        "from": "2025-09-01",
        "to": "2025-09-30"
    },
    "metrics": {
        "conversations_count": 1248,
        "customers_count": 865,
        "messages_count": 45230,
        "avg_response_time_seconds": 42,
        "satisfaction_score": 96
    }
}

گزارش عملکرد اپراتورها

GET /api/v1/analytics/agents/

Webhooks

شاهو می‌تونه رویدادها رو به سیستم تو بفرسته. آدرس webhook رو در تنظیمات ← اتصال‌ها تنظیم کن.

رویدادها

رویداد	زمان ارسال
message.created	پیام جدیدی دریافت یا ارسال شد
conversation.created	مکالمه‌ی جدیدی شروع شد
conversation.closed	مکالمه بسته شد
customer.created	مشتری جدیدی اضافه شد
customer.updated	اطلاعات مشتری تغییر کرد

نمونه Payload

{
    "event": "message.created",
    "timestamp": "2025-09-30T14:32:00Z",
    "data": {
        "message_id": "msg_abc123",
        "conversation_id": "conv_xyz789",
        "sender_type": "customer",
        "content": "سلام، درباره پلن‌ها سوال داشتم",
        "customer": {
            "id": "cust_abc123",
            "name": "مریم رضایی",
            "phone": "09123456789"
        }
    }
}

احراز هویت Webhook

در هر درخواست webhook، یک هدر X-Shahoo-Signature ارسال می‌شه که با HMAC-SHA256 امضا شده. باید این امضا رو در سمت خودت تأیید کنی.

import hmac
import hashlib

def verify_webhook(payload, signature, secret):
    expected = hmac.new(
        secret.encode(),
        payload.encode(),
        hashlib.sha256
    ).hexdigest()
    return hmac.compare_digest(expected, signature)

محدودیت درخواست‌ها

پلن	درخواست در دقیقه	درخواست در روز
Growth	۶۰	۱۰٬۰۰۰
Business	۳۰۰	۱۰۰٬۰۰۰

در هر پاسخ، هدرهای زیر ارسال می‌شن:

X-RateLimit-Limit: 60
X-RateLimit-Remaining: 45
X-RateLimit-Reset: 1696080000

SDKهای رسمی

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

Python

pip install shahoo-python

from shahoo import ShahooClient

client = ShahooClient(api_key="YOUR_API_KEY")

conversations = client.conversations.list(status="open")
for conv in conversations:
    print(conv.customer.name)

JavaScript / Node.js

npm install @shahoo/sdk

import { ShahooClient } from '@shahoo/sdk';

const client = new ShahooClient({ apiKey: 'YOUR_API_KEY' });

const conversations = await client.conversations.list({ status: 'open' });
console.log(conversations);

PHP

composer require shahoo/php-sdk

use Shahoo\Client;

$client = new Client('YOUR_API_KEY');
$conversations = $client->conversations()->list(['status' => 'open']);

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

ارسال پیام خوش‌آمد به مشتری جدید

def welcome_new_customer(customer_id):
    response = requests.post(
        'https://myshahoo.ir/api/v1/messages/send/',
        headers={'Authorization': f'Bearer {API_KEY}'},
        json={
            'customer_id': customer_id,
            'channel': 'whatsapp',
            'content': 'سلام! به شاهو خوش آمدید 👋'
        }
    )
    return response.json()

دریافت مکالمات باز

def get_open_conversations():
    response = requests.get(
        'https://myshahoo.ir/api/v1/conversations/',
        headers={'Authorization': f'Bearer {API_KEY}'},
        params={'status': 'open', 'per_page': 50}
    )
    return response.json()['results']

خروجی CSV از مشتریان

import csv
import requests

def export_customers():
    response = requests.get(
        'https://myshahoo.ir/api/v1/customers/',
        headers={'Authorization': f'Bearer {API_KEY}'},
        params={'per_page': 100}
    )

    with open('customers.csv', 'w', encoding='utf-8') as f:
        writer = csv.writer(f)
        writer.writerow(['نام', 'شماره', 'ایمیل', 'وضعیت'])

        for cust in response.json()['results']:
            writer.writerow([
                cust['name'],
                cust['phone'],
                cust.get('email', ''),
                cust['status']
            ])

بهترین شیوه‌ها

• کلید API رو در کد hardcode نکن — از متغیر محیطی استفاده کن
• خطاها رو مدیریت کن — همیشه کد وضعیت رو چک کن
• از pagination استفاده کن — برای لیست‌های بزرگ
• از Webhook استفاده کن — به‌جای polling مکرر
• Rate limit رو رعایت کن — از backoff استفاده کن
• Webhook signature رو تأیید کن — برای امنیت

پشتیبانی توسعه‌دهندگان

• مستندات آنلاین: همین صفحه
• ایمیل: api@myshahoo.ir
• کانال تلگرام: برای اخبار و تغییرات
• Status Page: status.myshahoo.ir

Changelog

نسخه ۱.۲ — ۱۴۰۵/۰۷

• افزودن endpoint پیام‌های مستقیم
• بهبود pagination
• پشتیبانی از HMAC برای Webhook

نسخه ۱.۱ — ۱۴۰۵/۰۵

• افزودن گزارش‌های تحلیلی
• بهبود rate limiting

نسخه ۱.۰ — ۱۴۰۵/۰۳

• انتشار اولیه API

قدم‌های بعدی