# Django Iran SMS
## Overview
A Django-based SMS integration system for simplifying in-country SMS usage in Iran, leveraging the `parsianwebco.ir`, `melipayamak.com`, and `kavenegar.com` services with JWT authentication. Developed by the Chelseru team, `drfiransms` is designed to support additional services in future releases.
## Features
- Integration with `parsianwebco.ir`, `melipayamak.com`, and `kavenegar.com`
- JWT-based authentication using `rest_framework_simplejwt`
- Scalable and extensible for other SMS providers
- Easy installation and configuration
## Installation
### Prerequisites
- Python 3.11
- Django 5.1 or higher
### Installation via pip
```bash
pip install django-iran-sms
```
### Configuration
In your Django project's `settings.py`, add the following parameters:
#### settings.py
```python
INSTALLED_APPS = [
...
'drfiransms', # When used in DRF.
]
```
```python
DJANGO_IRAN_SMS = {
'AUTHENTICATION': 'rest_framework_simplejwt', # Specify the authentication method
'SMS_BACKEND': 'PARSIAN_WEBCO_IR', # Set the SMS provider backend
'OTP_CODE': {
'LENGTH': 6, # Default length of OTP code
'EXPIRE_PER_MINUTES': 2, # Default expiration time in minutes
},
'PARSIAN_WEBCO_IR': {
'API_KEY': 'API_KEY obtained from sms.parsianwebco.ir', # API key from the SMS provider
'TEMPLATES': {
'OTP_CODE': 1, # Template ID for OTP code
}
},
'MELI_PAYAMAK_COM': {
'USERNAME': 'Username used to log in to the melipayamak.com website.',
'PASSWORD': 'API_KEY obtained from melipayamak.com',
'FROM': '50004001001516', # Sender number from the SMS provider
},
'KAVENEGAR_COM': {
'API_KEY': 'API_KEY obtained from kavenegar.com',
'FROM': '2000660110'
}
}
```
## Django Iran SMS Configuration
The configuration parameters for `DJANGO_IRAN_SMS` can be set as follows:
### Authentication
Currently, only `rest_framework_simplejwt` is supported for authentication.
### SMS Backend
Supported SMS providers:
- `PARSIAN_WEBCO_IR`
- `MELI_PAYAMAK_COM`
- `KAVENEGAR_COM`
### OTP Code
The `OTP_CODE` dictionary contains:
- **`LENGTH`**: OTP code length (3–10 digits). Default: **6**.
- **`EXPIRE_PER_MINUTES`**: Expiration time in minutes (> 0). Default: **2**.
---
## Usage
### URL Configuration
In your `urls.py`, include the following views:
```python
from drfiransms.views import OTPCodeSend, Authentication, MessageSend
urlpatterns += [
path('lur/send-code/', OTPCodeSend.as_view(), name='send_code'),
path('lur/authentication/', Authentication.as_view(), name='authentication'),
path('lur/send-message/', MessageSend.as_view(), name='send_message'),
]
```
---
## Sending Verification Code via API
```bash
curl -X POST https://djangoiransms.chelseru.com/lur/send-code/ -H "Content-Type: application/json" -d '{"mobile": "09123456789"}'
```
```bash
curl -X POST https://djangoiransms.chelseru.com/lur/authentication/ -H "Content-Type: application/json" -d '{"mobile": "09123456789", "code": "108117114", "group": "1"}'
```
- `group`: Optional segmentation attribute (e.g., a user can register as both driver and passenger). Default: **0**.
```bash
curl -X POST https://djangoiransms.chelseru.com/lur/send-message/ -H "Content-Type: application/json" -d '{"mobile_number": "09123456789", "message_text": "hello luristan."}'
```
---
## User Table
Automatically created with:
- **mobile**: User's mobile number.
- **user**: One-to-one relationship with Django's default `User` model.
- **group**: Optional segmentation attribute. Default: **0**.
---
## OTP Code Table
Automatically created with:
- **mobile**: User's mobile number.
- **code**: OTP code.
---
## Active User Sessions
From version **X.X.X**, a new `Session` model has been added to track and manage active user sessions.
This allows you to inspect the devices, browsers, and IPs from which users are currently logged in, and can be used to implement features like “log out from all devices.”
### Enabling Active Session Tracking
To enable this feature, add the following middleware to your `MIDDLEWARE` list in `settings.py`:
```python
MIDDLEWARE = [
...
'drfiransms.middlewares.TakeUserSessionMiddlaware',
...
]
```
### Session Model Fields
| Field | Description |
|---------------|-------------|
| `user` | ForeignKey to the user model (default_user), with `related_name='session'`. |
| `session_key` | Unique identifier for the session. |
| `user_agent` | Full User-Agent string of the browser/device. |
| `ip_address` | IP address of the client. |
| `device` | Device name or type. |
| `browser` | Browser name. |
| `last_seen` | Last time this session was active (`auto_now=True`). |
| `created_at` | Session creation timestamp (`auto_now_add=True`). |
### Example Use Cases
- Display all active sessions for a user in the admin panel or user profile.
- Identify suspicious logins based on IP/device.
- Allow users to terminate other active sessions.
---
## JWT Authentication
`drfiransms` supports JWT authentication via `rest_framework_simplejwt` for secure API communication.
Other authentication methods are under development.
---
## Future Plans
- Additional SMS provider support.
- Enhanced error handling.
- Rate limiting and monitoring.
- Contribution guidelines.
---
A Django package for seamless integration with Iranian SMS services like ParsianWebCo, Kavenegar, and Melipayamak.
Contributions are welcome! Submit pull requests or report issues on the GitHub repository.
## License
MIT License
Raw data
{
"_id": null,
"home_page": "https://djangoiransms.chelseru.com",
"name": "django-iran-sms",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.11",
"maintainer_email": null,
"keywords": "djangoiransms djangosms drfsms drfiransms chelseru lor lur bahman rashnu sobhan bahman bahman rashnu melipayamak parsianwebco sms \u062c\u0646\u06af\u0648 \u067e\u06cc\u0627\u0645\u06a9 \u0645\u0644\u06cc \u0627\u0627\u06cc\u0631\u0627\u0646 \u06a9\u0627\u0648\u0647 \u0646\u06af\u0627\u0631 python kavenegar kave negar meli payamak",
"author": "Sobhan Bahman | Rashnu",
"author_email": "bahmanrashnu@gmail.com",
"download_url": "https://files.pythonhosted.org/packages/59/ac/f7f84db7f4f759e3561925b208da339e16a5e68f7c86f672b05cd93d3927/django_iran_sms-1.3.8.tar.gz",
"platform": null,
"description": "# Django Iran SMS\n\n## Overview\n\nA Django-based SMS integration system for simplifying in-country SMS usage in Iran, leveraging the `parsianwebco.ir`, `melipayamak.com`, and `kavenegar.com` services with JWT authentication. Developed by the Chelseru team, `drfiransms` is designed to support additional services in future releases.\n\n## Features\n\n- Integration with `parsianwebco.ir`, `melipayamak.com`, and `kavenegar.com`\n- JWT-based authentication using `rest_framework_simplejwt`\n- Scalable and extensible for other SMS providers\n- Easy installation and configuration\n\n## Installation\n\n### Prerequisites\n\n- Python 3.11\n- Django 5.1 or higher\n\n### Installation via pip\n\n```bash\npip install django-iran-sms\n```\n\n### Configuration\nIn your Django project's `settings.py`, add the following parameters:\n\n#### settings.py\n\n```python\nINSTALLED_APPS = [\n ...\n 'drfiransms', # When used in DRF.\n]\n```\n\n```python\nDJANGO_IRAN_SMS = {\n 'AUTHENTICATION': 'rest_framework_simplejwt', # Specify the authentication method\n 'SMS_BACKEND': 'PARSIAN_WEBCO_IR', # Set the SMS provider backend\n 'OTP_CODE': {\n 'LENGTH': 6, # Default length of OTP code\n 'EXPIRE_PER_MINUTES': 2, # Default expiration time in minutes\n },\n 'PARSIAN_WEBCO_IR': {\n 'API_KEY': 'API_KEY obtained from sms.parsianwebco.ir', # API key from the SMS provider\n 'TEMPLATES': {\n 'OTP_CODE': 1, # Template ID for OTP code\n }\n },\n 'MELI_PAYAMAK_COM': {\n 'USERNAME': 'Username used to log in to the melipayamak.com website.',\n 'PASSWORD': 'API_KEY obtained from melipayamak.com',\n 'FROM': '50004001001516', # Sender number from the SMS provider\n },\n 'KAVENEGAR_COM': {\n 'API_KEY': 'API_KEY obtained from kavenegar.com',\n 'FROM': '2000660110'\n }\n}\n```\n\n## Django Iran SMS Configuration\n\nThe configuration parameters for `DJANGO_IRAN_SMS` can be set as follows:\n\n### Authentication\nCurrently, only `rest_framework_simplejwt` is supported for authentication.\n\n### SMS Backend\nSupported SMS providers:\n- `PARSIAN_WEBCO_IR`\n- `MELI_PAYAMAK_COM`\n- `KAVENEGAR_COM`\n\n### OTP Code\nThe `OTP_CODE` dictionary contains:\n\n- **`LENGTH`**: OTP code length (3\u201310 digits). Default: **6**.\n- **`EXPIRE_PER_MINUTES`**: Expiration time in minutes (> 0). Default: **2**.\n\n---\n\n## Usage\n\n### URL Configuration\nIn your `urls.py`, include the following views:\n\n```python\nfrom drfiransms.views import OTPCodeSend, Authentication, MessageSend\n\nurlpatterns += [\n path('lur/send-code/', OTPCodeSend.as_view(), name='send_code'),\n path('lur/authentication/', Authentication.as_view(), name='authentication'),\n path('lur/send-message/', MessageSend.as_view(), name='send_message'),\n]\n```\n\n---\n\n## Sending Verification Code via API\n\n```bash\ncurl -X POST https://djangoiransms.chelseru.com/lur/send-code/ -H \"Content-Type: application/json\" -d '{\"mobile\": \"09123456789\"}'\n```\n\n```bash\ncurl -X POST https://djangoiransms.chelseru.com/lur/authentication/ -H \"Content-Type: application/json\" -d '{\"mobile\": \"09123456789\", \"code\": \"108117114\", \"group\": \"1\"}'\n```\n\n- `group`: Optional segmentation attribute (e.g., a user can register as both driver and passenger). Default: **0**.\n\n```bash\ncurl -X POST https://djangoiransms.chelseru.com/lur/send-message/ -H \"Content-Type: application/json\" -d '{\"mobile_number\": \"09123456789\", \"message_text\": \"hello luristan.\"}'\n```\n\n---\n\n## User Table\nAutomatically created with:\n- **mobile**: User's mobile number.\n- **user**: One-to-one relationship with Django's default `User` model.\n- **group**: Optional segmentation attribute. Default: **0**.\n\n---\n\n## OTP Code Table\nAutomatically created with:\n- **mobile**: User's mobile number.\n- **code**: OTP code.\n\n---\n\n## Active User Sessions\n\nFrom version **X.X.X**, a new `Session` model has been added to track and manage active user sessions. \nThis allows you to inspect the devices, browsers, and IPs from which users are currently logged in, and can be used to implement features like \u201clog out from all devices.\u201d\n\n### Enabling Active Session Tracking\nTo enable this feature, add the following middleware to your `MIDDLEWARE` list in `settings.py`:\n\n```python\nMIDDLEWARE = [\n ...\n 'drfiransms.middlewares.TakeUserSessionMiddlaware',\n ...\n]\n```\n\n### Session Model Fields\n\n| Field | Description |\n|---------------|-------------|\n| `user` | ForeignKey to the user model (default_user), with `related_name='session'`. |\n| `session_key` | Unique identifier for the session. |\n| `user_agent` | Full User-Agent string of the browser/device. |\n| `ip_address` | IP address of the client. |\n| `device` | Device name or type. |\n| `browser` | Browser name. |\n| `last_seen` | Last time this session was active (`auto_now=True`). |\n| `created_at` | Session creation timestamp (`auto_now_add=True`). |\n\n### Example Use Cases\n- Display all active sessions for a user in the admin panel or user profile.\n- Identify suspicious logins based on IP/device.\n- Allow users to terminate other active sessions.\n\n---\n\n## JWT Authentication\n`drfiransms` supports JWT authentication via `rest_framework_simplejwt` for secure API communication. \nOther authentication methods are under development.\n\n---\n\n## Future Plans\n- Additional SMS provider support.\n- Enhanced error handling.\n- Rate limiting and monitoring.\n- Contribution guidelines.\n\n---\n\nA Django package for seamless integration with Iranian SMS services like ParsianWebCo, Kavenegar, and Melipayamak. \nContributions are welcome! Submit pull requests or report issues on the GitHub repository.\n\n## License\nMIT License\n",
"bugtrack_url": null,
"license": null,
"summary": "A Django package for seamless integration with Iranian SMS services like ParsianWebCo , Kavenegar and Melipayamak.",
"version": "1.3.8",
"project_urls": {
"Documentation": "https://github.com/Chelseru/django-iran-sms/",
"Homepage": "https://djangoiransms.chelseru.com",
"Telegram Channel": "https://t.me/djangoiransms",
"Telegram Group": "https://t.me/bahmanpy"
},
"split_keywords": [
"djangoiransms",
"djangosms",
"drfsms",
"drfiransms",
"chelseru",
"lor",
"lur",
"bahman",
"rashnu",
"sobhan",
"bahman",
"bahman",
"rashnu",
"melipayamak",
"parsianwebco",
"sms",
"\u062c\u0646\u06af\u0648",
"\u067e\u06cc\u0627\u0645\u06a9",
"\u0645\u0644\u06cc",
"\u0627\u0627\u06cc\u0631\u0627\u0646",
"\u06a9\u0627\u0648\u0647",
"\u0646\u06af\u0627\u0631",
"python",
"kavenegar",
"kave",
"negar",
"meli",
"payamak"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "3e1d741c05aff8ea72314b102827063e776faeff55e52c3aae4a4f3b3ae11e12",
"md5": "09a8addb89e9334bfde878629709c083",
"sha256": "f44edd8ba9826c6c223208cc9f9e0866503bf05dea07ed6c39b02e5491734683"
},
"downloads": -1,
"filename": "django_iran_sms-1.3.8-py3-none-any.whl",
"has_sig": false,
"md5_digest": "09a8addb89e9334bfde878629709c083",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.11",
"size": 18183,
"upload_time": "2025-08-09T09:53:31",
"upload_time_iso_8601": "2025-08-09T09:53:31.688797Z",
"url": "https://files.pythonhosted.org/packages/3e/1d/741c05aff8ea72314b102827063e776faeff55e52c3aae4a4f3b3ae11e12/django_iran_sms-1.3.8-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "59acf7f84db7f4f759e3561925b208da339e16a5e68f7c86f672b05cd93d3927",
"md5": "498d1aaa74d5143374b8899c9049700f",
"sha256": "0d34c3e8299fea0af02ff9360caa0e0d64d40a63a015c6202e3226617f677b2f"
},
"downloads": -1,
"filename": "django_iran_sms-1.3.8.tar.gz",
"has_sig": false,
"md5_digest": "498d1aaa74d5143374b8899c9049700f",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.11",
"size": 13958,
"upload_time": "2025-08-09T09:53:33",
"upload_time_iso_8601": "2025-08-09T09:53:33.320308Z",
"url": "https://files.pythonhosted.org/packages/59/ac/f7f84db7f4f759e3561925b208da339e16a5e68f7c86f672b05cd93d3927/django_iran_sms-1.3.8.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-08-09 09:53:33",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "Chelseru",
"github_project": "django-iran-sms",
"travis_ci": false,
"coveralls": false,
"github_actions": false,
"requirements": [
{
"name": "asgiref",
"specs": [
[
"==",
"3.8.1"
]
]
},
{
"name": "certifi",
"specs": [
[
"==",
"2025.1.31"
]
]
},
{
"name": "charset-normalizer",
"specs": [
[
"==",
"3.4.1"
]
]
},
{
"name": "Django",
"specs": [
[
"==",
"5.1.6"
]
]
},
{
"name": "djangorestframework",
"specs": [
[
"==",
"3.15.2"
]
]
},
{
"name": "idna",
"specs": [
[
"==",
"3.10"
]
]
},
{
"name": "requests",
"specs": [
[
"==",
"2.32.3"
]
]
},
{
"name": "sqlparse",
"specs": [
[
"==",
"0.5.3"
]
]
},
{
"name": "typing_extensions",
"specs": [
[
"==",
"4.12.2"
]
]
},
{
"name": "urllib3",
"specs": [
[
"==",
"2.3.0"
]
]
}
],
"lcname": "django-iran-sms"
}
JSON
