دليل المطورين

البناء باستخدام shamz.ai

مرجع API كامل ومكتبات SDK وأدلة التكامل للمطورين

💻Widget Embedding 🔌REST API 🔔Webhooks 📦SDKs & Libraries ⚡Rate Limits & Best Practices

💻

Widget Embedding

Basic Widget Integration

Add the shamz.ai widget to your website by including our embed script. Replace YOUR_API_KEY with your actual API key from the dashboard.

html

<script src="https://widget.shamz.ai/embed.js"></script>
<script>
  ShamzWidget.init({
    apiKey: 'YOUR_API_KEY',
    position: 'bottom-right',
    theme: 'light'
  });
</script>

Configuration Options

Parameter	Type	Default	Description
`apiKey`	string	required	Your AI front desk API key
`position`	string	'bottom-right'	'bottom-right' \| 'bottom-left'
`theme`	string	'light'	'light' \| 'dark'
`language`	string	'auto'	'en' \| 'ar' \| 'auto'
`preChatSurvey`	boolean	false	Show survey before chat

🔌

REST API

Authentication

All API requests require authentication using your API key in the X-API-KEY header.

bash

curl https://api.shamz.ai/api/widget/chat \
  -H "X-API-KEY: your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "msg": {
      "type": "text",
      "content": "Hello"
    }
  }'

Send Message

POST /api/widget/chat - Send a message to the AI front desk

json

{
  "session_id": "sess_123",
  "msg": {
    "type": "text",
    "content": "I want to book an appointment"
  },
  "survey": {
    "name": "John Doe",
    "email": "john@example.com",
    "phone": "+97312345678"
  }
}

🔔

Webhooks

Webhook Events

Subscribe to webhooks to receive real-time notifications about events in your AI front desk.

Available Events

conversation.started - New conversation initiated
conversation.completed - Conversation ended
appointment.created - New appointment booked
appointment.cancelled - Appointment cancelled
ticket.created - New service desk ticket
ticket.updated - Ticket status changed
lead.captured - New lead captured
lead.qualified - Lead scored as hot/warm

Webhook Payload Example

json

{
  "event": "appointment.created",
  "timestamp": "2025-12-31T10:30:00Z",
  "data": {
    "appointment_id": "apt_123",
    "customer_name": "John Doe",
    "customer_phone": "+97312345678",
    "appointment_type": "Consultation",
    "scheduled_at": "2025-12-31T14:00:00Z",
    "agent_name": "Dr. Smith"
  }
}

Setting Up Webhooks

Go to your AI front desk settings in the dashboard
Navigate to Integrations → Webhooks
Enter your webhook URL and select events to subscribe to
Save and test your webhook

📦

SDKs & Libraries

Official SDKs

JavaScript / TypeScript

bash

npm install @shamz/sdk-js

Full-featured SDK for web applications with TypeScript support.

Python

bash

pip install shamz-sdk

Python SDK for backend integrations and automation.

React Component

bash

npm install @shamz/react-widget

Pre-built React component for seamless integration.

Example: React Integration

jsx

import { ShamzWidget } from '@shamz/react-widget';

function App() {
  return (
    <div>
      <ShamzWidget 
        apiKey="YOUR_API_KEY"
        position="bottom-right"
        theme="light"
        onMessageSent={(message) => {
          console.log('Message sent:', message);
        }}
        onAppointmentBooked={(appointment) => {
          console.log('Appointment booked:', appointment);
        }}
      />
    </div>
  );
}

⚡

Rate Limits & Best Practices

API Rate Limits

Plan	Requests/Minute	Concurrent Connections
Starter	60	10
Growth	300	50
Enterprise	Custom	Custom

Best Practices

Use Session IDs: Always include session_id to maintain conversation context
Handle Errors: Implement proper error handling and retry logic
Cache Responses: Cache static content like FAQs and service lists
Webhooks Over Polling: Use webhooks instead of polling for real-time updates
Secure Your Keys: Never expose API keys in client-side code
Monitor Usage: Track your API usage to avoid hitting rate limits

Error Handling

javascript

try {
  const response = await fetch('https://api.shamz.ai/api/widget/chat', {
    method: 'POST',
    headers: {
      'X-API-KEY': apiKey,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify(payload)
  });

  if (!response.ok) {
    if (response.status === 429) {
      // Rate limit hit, implement exponential backoff
      await sleep(1000);
      return retry();
    }
    throw new Error(`API error: ${response.status}`);
  }

  const data = await response.json();
  return data;
} catch (error) {
  console.error('Shamz API error:', error);
  // Fallback to error message
}

هل تحتاج إلى دعم تقني؟

هل لديك أسئلة حول تطبيق API أو تحتاج إلى مساعدة في التكامل؟ فريقنا التقني هنا للمساعدة.

تواصل مع الدعم التقني عرض على GitHub