API Reference

API Reference

Complete API documentation with examples

Authentication

All API requests require authentication using your API key. Include it in the Authorization header: 

Authorization: Bearer YOUR_API_KEY
Get your API key from Settings → API Keys in your dashboard.

Base URL

https://tawasol.site/api

Endpoints

POST إرسال الرسالة

/api/send-message

Send a text or media message to a WhatsApp number.

Request Body
{
  "device_id": "string (required)",
  "to": "string (required)",
  "message": "string (required)",
  "type": "text|image|video|document|audio"
}
مثال
curl -X POST https://tawasol.site/api/send-message \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "device_id": "device_123",
    "to": "1234567890",
    "message": "Hello from API!"
  }'

GET List Devices

/api/devices

Get a list of all connected devices.

مثال
curl -X GET https://tawasol.site/api/devices \
  -H "Authorization: Bearer YOUR_API_KEY"

GET Get Device Status

/api/devices/{device_id}

Get the status and information of a specific device.

GET Message History

/api/messages

Retrieve message history with optional filters.

Query Parameters
  • device_id - Filter by device
  • to - Filter by recipient
  • limit - Number of results (default: 50)
  • page - Page number

POST Set Webhook

/api/webhook

Configure webhook URL for receiving events.

Request Body
{
  "device_id": "string (required)",
  "url": "string (required)",
  "events": ["message", "status", "device"]
}

POST Create Contact

/api/contacts

Add a new contact to your phonebook.

Response Format

All API responses follow a consistent format:

Success Response
{
  "success": true,
  "data": { ... },
  "message": "Operation successful"
}
Error Response
{
  "success": false,
  "error": {
    "code": "ERROR_CODE",
    "message": "Error description"
  }
}

Rate Limits

API requests are rate-limited to ensure fair usage:

  • 100 requests per minute per API key
  • 1000 requests per hour per API key
  • Rate limit headers are included in responses
Exceeding rate limits will result in HTTP 429 responses. Implement exponential backoff in your application.

Error Codes

Code الوصف
400 Bad Request - Invalid parameters
401 Unauthorized - Invalid or missing API key
404 Not Found - Resource does not exist
429 Too Many Requests - Rate limit exceeded
500 Internal Server Error