Skip to content

m-hamza/IPPANEL-Edge-Document

BranchesTags
 
 

Folders and files

NameName
Last commit message
Last commit date

Latest commit

 

History

9 Commits
README.md
README.md
 
 

Repository files navigation

📌 API Documentation

👋 Hey there! If you've got an account with IPPanel, you're in the right place. This documentation covers everything you need to know about using our API – from sending messages to managing your account and beyond.

📚 Table of Contents

Base URL: http://edge.ippanel.com/v1

Please replace {base_url} with the actual base URL of the server.

📚 Table of Contents

Base URL: {base_url}
(لطفاً {base_url} را با آدرس اصلی سرور جایگزین کنید.)

🔐 Auth

Login API

Authenticates the user and initiates the login process.

📍 Endpoint

POST {base_url}/api/acl/auth/login

🧾 Headers

Key Value
Content-Type application/json

📤 Request Body

{
  "username": "your-username",
  "password": "your-password"
}

✅ Success Response

{
  "data": {
    "method": "ga", // or "sms" or "login"
    "token": "84cd3ef65b0700dea4ac7942e61df4a5"
  },
  "meta": {
    "status": true,
    "message": "انجام شد",
    "message_parameters": [],
    "message_code": "200-1"
  }
}

📌 Method Values

🔄 method Meaning (Login Flow Explanation)

Depending on the user's 2FA (Two-Factor Authentication) settings, one of the following scenarios will occur after a successful login:

1- Google Authenticator (ga) If the user has enabled Google Authenticator in their profile settings, the response will contain:

{
  "method": "ga"
}

✅ The user must call the Confirm OTP Login API with the 6-digit code generated by the Google Authenticator app.

2- SMS OTP (sms) If Google Authenticator is not enabled, the system will automatically send an OTP via SMS and the response will contain:

{
  "method": "sms"
}

✅ The user must call the Confirm OTP Login API with the OTP code received via SMS.

⚠️ If the user does not receive the SMS, they can call the Send SMS OTP API to resend the OTP.

3- No 2FA (login) If 2FA is not required for the user, the response will contain:

{
  "method": "login"
}

✅ The returned token is final and can be used directly for authenticated API requests. No further action is needed.

⚠️ The temporary token received in the login response:

  • is valid for 6 minutes if method is ga or sms.
  • is valid for 10 hours if method is login.

❌ Error Response — Invalid Credentials (401)

{
  "data": null,
  "meta": {
    "status": false,
    "message": "اطلاعات وارد شده صحیح نمی باشد",
    "message_parameters": [],
    "message_code": "400-1",
    "errors": {}
  }
}

❌ Error Response — Validation Error (422)

{
  "data": null,
  "meta": {
    "status": false,
    "message": "تکمیل گزینه گذرواژه الزامی است",
    "message_parameters": [],
    "message_code": "400-2",
    "errors": {
      "password": [
        "تکمیل گزینه گذرواژه الزامی است"
      ]
    }
  }
}

🧪 Example using curl

curl --location '{base_url}/api/acl/auth/login' \
--header 'Content-Type: application/json' \
--data-raw '{
  "username": "your-username",
  "password": "your-password"
}'

Send SMS OTP

This endpoint allows the user to request an OTP (One-Time Password) via SMS, using the token received in the login step.

📍 Endpoint

POST {base_url}/api/acl/auth/send_sms_otp

🧾 Headers

Key Value
Content-Type application/json

📤 Request Body

{
  "token": "your-login-step-token"
}

✅ Success Response

{
  "data": {
    "method": "sms",
    "token": "e7aff6e9136cc43e9a7c3c3eae5678ac"
  },
  "meta": {
    "status": true,
    "message": "انجام شد",
    "message_parameters": [],
    "message_code": "200-1"
  }
}

⚠️ The token used here must be a temporary login token received from the login API. If valid and not expired, an OTP will be sent via SMS.

❌ Error Response — Invalid or Expired Token (401)

{
  "data": null,
  "meta": {
    "status": false,
    "message": "اطلاعات وارد شده صحیح نمی باشد",
    "message_parameters": [],
    "message_code": "400-1",
    "errors": {}
  }
}

🧪 Example using curl

curl --location '{base_url}/api/acl/auth/send_sms_otp' \
--header 'Content-Type: application/json' \
--data '{
  "token": "your-login-step-token"
}'

Confirm OTP Login

This endpoint is used to confirm the login process by verifying the OTP (from SMS or Google Authenticator).

📍 Endpoint

POST {base_url}/api/acl/auth/confirm_otp

🧾 Headers

Key Value
Content-Type application/json

📤 Request Body

{
  "token": "your-temporary-token",
  "otp": "otp-code"
}

token: The temporary token received from the Login API

otp: The OTP received via SMS or generated from Google Authenticator

✅ Success Response

{
  "data": {
    "token": "22c392ffebe7286ee8021cfef7d7cad5",
    "method": "login"
  },
  "meta": {
    "status": true,
    "message": "انجام شد",
    "message_parameters": [],
    "message_code": "200-1"
  }
}

🎉 The returned token is the final token that can be used to access authorized APIs.

⏱ Valid for: 10 hours

❌ Error Response — Invalid or Expired Token or OTP (401)

{
  "data": null,
  "meta": {
    "status": false,
    "message": "اطلاعات وارد شده صحیح نمی باشد",
    "message_parameters": [],
    "message_code": "400-1",
    "errors": {}
  }
}

❌ Error Response — Validation Error (422)

{
  "data": null,
  "meta": {
    "status": false,
    "message": "تکمیل گزینه otp الزامی است",
    "message_parameters": [],
    "message_code": "400-2",
    "errors": {
      "otp": [
        "تکمیل گزینه otp الزامی است"
      ]
    }
  }
}

🧪 Example using curl

curl --location '{base_url}/api/acl/auth/confirm_otp' \
--header 'Content-Type: application/json' \
--data '{
  "token": "your-login-step-token",
  "otp": "otp-code"
}'

Forgot Password

Request Otp For Change Password

This endpoint is used to request an OTP (One-Time Password) for changing the password.

📍 Endpoint

POST {base_url}/api/acl/auth/forgot_password

🧾 Headers

Key Value
Content-Type application/json

📤 Request Body

{
  "username": "your-username", 
  "mobile": "your-mobile-number"
}

✅ Success Response

{
    "data": {
        "token": "6b1059f512b4fe9acd8bdb22351b0b51"
    },
    "meta": {
        "status": true,
        "message": "انجام شد",
        "message_parameters": [],
        "message_code": "200-1"
    }
}

❌ Error Response — Invalid or Expired Token (401)

{
    "data": null,
    "meta": {
        "status": false,
        "message": "اطلاعات وارد شده صحیح نمی باشد",
        "message_parameters": [],
        "message_code": "400-1",
        "errors": {}
    }
}

❌ Error Response — Validation Error (422)

{
    "data": null,
    "meta": {
        "status": false,
        "message": "تکمیل گزینه نام کاربری الزامی است",
        "message_parameters": [],
        "message_code": "400-2",
        "errors": {
            "username": [
                "تکمیل گزینه نام کاربری الزامی است"
            ]
        }
    }
}

🧪 Example using curl

curl --location '{base_url}/api/acl/auth/forgot_password' \
--header 'Content-Type: application/json' \
--data '{
    "username":"your-username",
    "mobile":"your-mobile-number"
}'

Change Password By Token

This endpoint is used to change the password using the OTP received in the previous step.

📍 Endpoint

POST {base_url}/api/acl/auth/change_password_by_token

🧾 Headers

Key Value
Content-Type application/json

📤 Request Body

{
    "token":"token-from-forgot-password",
    "otp":"otp-code",
    "password":"new-password"
}

✅ Success Response

{
    "data": null,
    "meta": {
        "status": true,
        "message": "انجام شد",
        "message_parameters": [],
        "message_code": "200-1"
    }
}

❌ Error Response — Invalid or Expired Token (401)

{
    "data": null,
    "meta": {
        "status": false,
        "message": "اطلاعات وارد شده صحیح نمی باشد",
        "message_parameters": [],
        "message_code": "400-1",
        "errors": {}
    }
}

❌ Error Response — Validation Error (422)

{
    "data": null,
    "meta": {
        "status": false,
        "message": "تکمیل گزینه گذرواژه الزامی است",
        "message_parameters": [],
        "message_code": "400-2",
        "errors": {
            "password": [
                "تکمیل گزینه گذرواژه الزامی است"
            ]
        }
    }
}

🧪 Example using curl

curl --location '{base_url}/api/acl/auth/change_password_by_token' \
--header 'Content-Type: application/json' \
--data '{
    "token":"token-from-forgot-password",
    "otp":"otp-code",
    "password":"new-password"
}'

Logout

This endpoint is used to log out the user from the system.

📍 Endpoint

POST {base_url}/api/acl/auth/logout

🧾 Headers

Key Value
Content-Type application/json
Authorization your-token

✅ Success Response

{
    "data": null,
    "meta": {
        "status": true,
        "message": "انجام شد",
        "message_parameters": [],
        "message_code": "200-1"
    }
}

❌ Error Response — Invalid or Expired Token (401)

{
    "data": null,
    "meta": {
        "status": false,
        "message": "اطلاعات وارد شده صحیح نمی باشد",
        "message_parameters": [],
        "message_code": "400-1",
        "errors": {}
    }
}

🧪 Example using curl

curl --location '{base_url}/api/acl/auth/logout' \
--header 'Content-Type: application/json' \
--header 'Authorization: your-token'

Check Token

This endpoint is used to check the validity of the token.

📍 Endpoint

POST {base_url}/api/acl/auth/check_token

🧾 Headers

Key Value
Content-Type application/json
Authorization your-token

✅ Success Response

{
    "data": {
        "user_name": "ippanel",
        "user_id": 58745,
        "document_block": false,
        "is_reseller": true,
        "send_block": false,
        "name": "test"
    },
    "meta": {
        "status": true,
        "message": "انجام شد",
        "message_parameters": [],
        "message_code": "200-1"
    }
}

❌ Error Response — Invalid or Expired Token (401)

{
    "data": null,
    "meta": {
        "status": false,
        "message": "اطلاعات وارد شده صحیح نمی باشد",
        "message_parameters": [],
        "message_code": "400-1",
        "errors": {}
    }
}

🧪 Example using curl

curl --location '{base_url}/api/acl/auth/check_token' \
--header 'Content-Type: application/json' \
--header 'Authorization: your-token'

📨 Send Sms

You can send SMS using the following endpoints. The main endpoint is /api/send, for changing the sending method, you can use the sending type parameter in the request body.

Send Sms Normal

This endpoint is used to quickly send SMS messages.

📍 Endpoint

POST {base_url}/api/send

🧾 Headers

Key Value
Content-Type application/json
Authorization your-token

📤 Request Body

{
    "sending_type": "normal",
    "from_number": "+983000505",
    "message": "متن پیام",
    "params": {
        "recipients": [
            "+989120000000",
            "+989350000000"
        ]
    },
    "send_time": "2025-03-12 21:20:02"
}

in the above request and all another sending types, the send_time field is optional and if not provided, the system will use the current time.if you want to send the message in the future, you can set the send_time field to the desired time in the format YYYY-MM-DD HH:MM:SS.timezone is UTC.

✅ Success Response

{
    "data": {
        "message_outbox_ids": [
            1123544244
        ]
    },
    "meta": {
        "status": true,
        "message": "انجام شد",
        "message_parameters": [],
        "message_code": "200-1"
    }
}

❌ Error Response — Invalid or Expired Token (401)

{
    "data": null,
    "meta": {
        "status": false,
        "message": "اطلاعات وارد شده صحیح نمی باشد",
        "message_parameters": [],
        "message_code": "400-1",
        "errors": {}
    }
}

❌ Error Response — Validation Error (422)

{
    "data": null,
    "meta": {
        "status": false,
        "message": "تکمیل گزینه پیام الزامی است",
        "message_parameters": [],
        "message_code": "400-2",
        "errors": {
            "message": [
                "تکمیل گزینه پیام الزامی است"
            ]
        }
    }
}

🧪 Example using curl

curl --location '{base_url}/api/send' \
--header 'Content-Type: application/json' \
--header 'Authorization: API TOKEN' \
--data '{
    "sending_type": "normal",
    "from_number": "+983000505",
    "message": "متن پیام",
    "params": {
        "recipients": [
            "+989120000000",
            "+989350000000"
        ]
    },
    "send_time": "2025-03-12 21:20:02"
}'

Send Webservice

This endpoint is used to send SMS messages using a web service.

📍 Endpoint

POST {base_url}/api/send

🧾 Headers

Key Value
Content-Type application/json
Authorization your-token

📤 Request Body

{
    "sending_type": "webservice",
    "from_number": "+983000505",
    "message": "متن پیام",
    "params": {
        "recipients": [
            "+989120000000",
            "+989350000000"
        ]
    },
    "send_time": "2025-03-12 21:20:02"
}

in the above request and all another sending types, the send_time field is optional and if not provided, the system will use the current time.if you want to send the message in the future, you can set the send_time field to the desired time in the format YYYY-MM-DD HH:MM:SS.timezone is UTC.

✅ Success Response

{
    "data": {
        "message_outbox_ids": [
            1123544244
        ]
    },
    "meta": {
        "status": true,
        "message": "انجام شد",
        "message_parameters": [],
        "message_code": "200-1"
    }
}

❌ Error Response — Invalid or Expired Token (401)

{
    "data": null,
    "meta": {
        "status": false,
        "message": "اطلاعات وارد شده صحیح نمی باشد",
        "message_parameters": [],
        "message_code": "400-1",
        "errors": {}
    }
}

❌ Error Response — Validation Error (422)

{
    "data": null,
    "meta": {
        "status": false,
        "message": "تکمیل گزینه پیام الزامی است",
        "message_parameters": [],
        "message_code": "400-2",
        "errors": {
            "message": [
                "تکمیل گزینه پیام الزامی است"
            ]
        }
    }
}

🧪 Example using curl

curl --location '{base_url}/api/send' \
--header 'Content-Type: application/json' \
--header 'Authorization: API TOKEN' \
--data '{
    "sending_type": "webservice",
    "from_number": "+983000505",
    "message": "متن پیام",
    "params": {
        "recipients": [
            "+989120000000",
            "+989350000000"
        ]
    },
    "send_time": "2025-03-12 21:20:02"
}'

Send Peer To Peer

This API allows you to send multiple messages to multiple recipients in a peer-to-peer format. Each message can have its own set of recipients.

📍 Endpoint

POST {base_url}/api/send

🧾 Headers

Key Value
Content-Type application/json
Authorization your-token

📤 Request Body

{
    "sending_type": "peer_to_peer",
    "from_number": "+983000505",
    "params": [
        {
            "recipients": [
                "+989120000000",
                "+989350000000"
            ],
            "message": "پیام اول"
        },
        {
            "recipients": [
                "+989130000000"
            ],
            "message": "پیام دوم"
        }
    ]
}

Each item in the params array represents a message and its recipients.

✅ Success Response

{
    "data": {
        "message_outbox_ids": [
            1123594208,
            1123594210
        ]
    },
    "meta": {
        "status": true,
        "message": "انجام شد",
        "message_parameters": [],
        "message_code": "200-1"
    }
}

The response returns an array of message_outbox_ids – one ID per message sent (regardless of how many recipients it had).

❌ Error Response — Invalid or Expired Token (401)

{
    "data": null,
    "meta": {
        "status": false,
        "message": "اطلاعات وارد شده صحیح نمی باشد",
        "message_parameters": [],
        "message_code": "400-1",
        "errors": {}
    }
}

❌ Error Response — Validation Error (422)

{
    "data": null,
    "meta": {
        "status": false,
        "message": "تکمیل گزینه پیام الزامی است",
        "message_parameters": [],
        "message_code": "400-2",
        "errors": {
            "message": [
                "تکمیل گزینه پیام الزامی است"
            ]
        }
    }
}

🧪 Example using curl

curl --location '{base_url}/api/send' \
--header 'Content-Type: application/json' \
--header 'Authorization: API TOKEN' \
--data '{
    "sending_type": "peer_to_peer",
    "from_number": "+983000505",
    "params": [
        {
            "recipients": [
                "+989120000000",
                "+989350000000"
            ],
            "message": "پیام اول"
        },
        {
            "recipients": [
                "+989130000000"
            ],
            "message": "پیام دوم"
        }
    ]
}'

Send Peer To Peer By File

This API allows you to send multiple messages to multiple recipients in a peer-to-peer format using a file. Each message can have its own set of recipients.

📍 Endpoint

POST {base_url}/api/send

🧾 Headers

Key Value
Content-Type multipart/form-data
Authorization your-token

📤 Request Body

{
    "sending_type": "peer_to_peer_file",
    "from_number": "+983000505",
    "send_time": "2025-03-12 21:20:02",
    "files[]": "file.csv"
}

in the above request and all another sending types, the send_time field is optional and if not provided, the system will use the current time.if you want to send the message in the future, you can set the send_time field to the desired time in the format YYYY-MM-DD HH:MM:SS.timezone is UTC.

✅ Success Response

{
    "data": {
        "message_outbox_ids": [
            1123594208,
            1123594210
        ]
    },
    "meta": {
        "status": true,
        "message": "انجام شد",
        "message_parameters": [],
        "message_code": "200-1"
    }
}

The response returns an array of message_outbox_ids – one ID per message sent (regardless of how many recipients it had).

❌ Error Response — Invalid or Expired Token (401)

{
    "data": null,
    "meta": {
        "status": false,
        "message": "اطلاعات وارد شده صحیح نمی باشد",
        "message_parameters": [],
        "message_code": "400-1",
        "errors": {}
    }
}

❌ Error Response — Validation Error (422)

{
    "data": null,
    "meta": {
        "status": false,
        "message": "تکمیل گزینه فایل ها الزامی است",
        "message_parameters": [],
        "message_code": "400-2",
        "errors": {
            "files": [
                "تکمیل گزینه فایل ها الزامی است"
            ]
        }
    }
}

🧪 Example using curl

curl --location '{base_url}/api/send' \
--header 'Content-Type: multipart/form-data' \
--header 'Accept: application/json' \
--form 'sending_type="peer_to_peer_file"' \
--form 'from_number="+983000505"' \
--form 'send_time="2025-04-25 10:10:10"' \
--form 'files[]=@"/path/to/your/file.csv"' \

Send PostalCode

This API allows you to send messages using postal codes.

📍 Endpoint

POST {base_url}/api/send

🧾 Headers

Key Value
Content-Type application/json
Authorization your-token

📤 Request Body

{
    "sending_type": "postal_code",
    "from_number": "+98BANK",
    "message": "متن پیام",
    "params": [
        {
            "bank": "all",
            "postal_code": 131,
            "gender": 0,
            "age_from": 1330,
            "age_to": 1402,
            "mci": {
                "start": 0,
                "size": 1
            },
            "irancell": {
                "start": 0,
                "size": 0
            },
            "other": {
                "start": 0,
                "size": 0
            }
        },
        {
            "bank": "all",
            "postal_code": 141,
            "gender": 0,
            "age_from": 1330,
            "age_to": 1402,
            "mci": {
                "start": 0,
                "size": 1
            },
            "irancell": {
                "start": 0,
                "size": 0
            },
            "other": {
                "start": 0,
                "size": 0
            }
        }
    ],
    "other_recipients": [
        "+989120000000",
        "+989350000000"
    ],
    "send_time": "2025-02-28 10:52:02"
}

in the above request and all another sending types, the send_time field is optional and if not provided, the system will use the current time.if you want to send the message in the future, you can set the send_time field to the desired time in the format YYYY-MM-DD HH:MM:SS.timezone is UTC. in the above request, the params field is an array of objects, each representing a postal code and its associated parameters. The other_recipients field is optional and an array of phone numbers that will receive the message in addition to the postal code recipients.

✅ Success Response

{
    "data": {
        "message_outbox_ids": [
            1123594208
        ]
    },
    "meta": {
        "status": true,
        "message": "انجام شد",
        "message_parameters": [],
        "message_code": "200-1"
    }
}

❌ Error Response — Invalid or Expired Token (401)

{
    "data": null,
    "meta": {
        "status": false,
        "message": "اطلاعات وارد شده صحیح نمی باشد",
        "message_parameters": [],
        "message_code": "400-1",
        "errors": {}
    }
}

❌ Error Response — Validation Error (422)

{
    "data": null,
    "meta": {
        "status": false,
        "message": "تکمیل گزینه پیام الزامی است",
        "message_parameters": [],
        "message_code": "400-2",
        "errors": {
            "message": [
                "تکمیل گزینه پیام الزامی است"
            ]
        }
    }
}

🧪 Example using curl

curl --location '{base_url}/api/send' \
--header 'Content-Type: application/json' \
--header 'Authorization: API TOKEN' \
--data '{
    "sending_type": "postal_code",
    "from_number": "+98BANK",
    "message": "متن پیام",
    "params": [
        {
            "bank": "all",
            "postal_code": 131,
            "gender": 0,
            "age_from": 1330,
            "age_to": 1402,
            "mci": {
                "start": 0,
                "size": 1
            },
            "irancell": {
                "start": 0,
                "size": 0
            },
            "other": {
                "start": 0,
                "size": 0
            }
        },
        {
            "bank": "all",
            "postal_code": 141,
            "gender": 0,
            "age_from": 1330,
            "age_to": 1402,
            "mci": {
                "start": 0,
                "size": 1
            },
            "irancell": {
                "start": 0,
                "size": 0
            },
            "other": {
                "start": 0,
                "size": 0
            }
        }
    ],
    "other_recipients": [
        "+989120000000",
        "+989350000000"
    ],
    "send_time": "2025-02-28 10:52:02"
}'

Send Pattern

This API allows you to send messages using a pattern.

📍 Endpoint

POST {base_url}/api/send

🧾 Headers

Key Value
Content-Type application/json
Authorization your-token

📤 Request Body

{
    "sending_type": "pattern",
    "from_number": "+983000505",
    "code": "xxxxxxxxxxxxxxx",
    "recipients": [
        "+989120000000"
    ],
    "params": {
        "code": "متن جایگذاری"
    }
}

in the above request, the params field is an object representing the pattern and its associated parameters.

✅ Success Response

{
    "data": {
        "message_outbox_ids": [
            1123594208
        ]
    },
    "meta": {
        "status": true,
        "message": "انجام شد",
        "message_parameters": [],
        "message_code": "200-1"
    }
}

❌ Error Response — Invalid or Expired Token (401)

{
    "data": null,
    "meta": {
        "status": false,
        "message": "اطلاعات وارد شده صحیح نمی باشد",
        "message_parameters": [],
        "message_code": "400-1",
        "errors": {}
    }
}

❌ Error Response — Validation Error (422)

{
    "data": null,
    "meta": {
        "status": false,
        "message": "تکمیل گزینه code الزامی است",
        "message_parameters": [],
        "message_code": "400-2",
        "errors": {
            "code": [
                "تکمیل گزینه code الزامی است"
            ]
        }
    }
}

🧪 Example using curl

curl --location '{base_url}/api/send' \
--header 'Content-Type: application/json' \
--header 'Authorization: API TOKEN' \
--data '{
    "sending_type": "pattern",
    "from_number": "+983000505",
    "code": "xxxxxxxxxxxxxxx",
    "recipients": [
        "+989120000000"
    ],
    "params": {
        "code": "متن جایگذاری"
    }
}'

Send VOTP

This API allows you to send a VOTP (Voice One-Time Password) message.

📍 Endpoint

POST {base_url}/api/send

🧾 Headers

Key Value
Content-Type application/json
Authorization your-token

📤 Request Body

{
    "sending_type": "votp",
    "message": "45852",
    "params": {
        "recipients": [
            "+989120000000"
        ]
    }
}

✅ Success Response

{
    "data": {
        "message_outbox_ids": [
            1123594208
        ]
    },
    "meta": {
        "status": true,
        "message": "انجام شد",
        "message_parameters": [],
        "message_code": "200-1"
    }
}

❌ Error Response — Invalid or Expired Token (401)

{
    "data": null,
    "meta": {
        "status": false,
        "message": "اطلاعات وارد شده صحیح نمی باشد",
        "message_parameters": [],
        "message_code": "400-1",
        "errors": {}
    }
}

❌ Error Response — Validation Error (422)

{
    "data": null,
    "meta": {
        "status": false,
        "message": "تکمیل گزینه پیام الزامی است",
        "message_parameters": [],
        "message_code": "400-2",
        "errors": {
            "message": [
                "تکمیل گزینه پیام الزامی است"
            ]
        }
    }
}

🧪 Example using curl

curl --location '{base_url}/api/send' \
--header 'Content-Type: application/json' \
--header 'Authorization: API TOKEN' \
--data '{
    "sending_type": "votp",
    "message": "45852",
    "params": {
        "recipients": [
            "+989120000000"
        ]
    }
}'

Cancel Scheduled Message

Use this API to cancel a message scheduled for future delivery. Note: You can only cancel messages at least 5 minutes before their scheduled send time.

📍 Endpoint

POST {base_url}/api/send/cancel

🧾 Headers

Key Value
Content-Type application/json
Authorization your-token

📤 Request Body

{
    "message_outbox_id":1148303263
}

✅ Success Response

{
    "data": null,
    "meta": {
        "status": true,
        "message": "انجام شد",
        "message_parameters": [],
        "message_code": "200-1"
    }
}

❌ Error Response — Invalid or Expired Token (401)

{
    "data": null,
    "meta": {
        "status": false,
        "message": "اطلاعات وارد شده صحیح نمی باشد",
        "message_parameters": [],
        "message_code": "400-1",
        "errors": {}
    }
}

❌ Error Response — Validation Error (404)

{
    "data": null,
    "meta": {
        "status": false,
        "message": "پیام مورد نظر یافت نشد",
        "message_parameters": [],
        "message_code": "400-1",
        "errors": {}
    }
}

❌ Error Response — Validation Error (422)

{
    "data": null,
    "meta": {
        "status": false,
        "message": "تکمیل گزینه message outbox id الزامی است",
        "message_parameters": [],
        "message_code": "400-2",
        "errors": {
            "message_outbox_id": [
                "تکمیل گزینه message outbox id الزامی است"
            ]
        }
    }
}

🧪 Example using curl

curl --location '{base_url}/api/send/cancel' \
--header 'Content-Type: application/json' \
--header 'Authorization: API TOKEN' \
--data '{
    "message_outbox_id":1148303263
}'

📊 Report

This API allows you to get various reports related to your activities.

Outbox Report

This API allows you to get reports of sent messages.

Get Outbox Report

With this API, you can retrieve a general report of your SMS sending requests. It provides information about sent bulk messages but does not include individual message details. To access message-level data, please refer to the detailed APIs described later in this documentation.You can use the page and limit parameters to paginate through the results.

📍 Endpoint

POST {base_url}/api/report/new_list

🧾 Headers

Key Value
Content-Type application/json
Authorization your-token

📤 Request Body

{
    "page": 1,
    "limit": 10,
    "filters": {
        "username": "*",
        "number": "+98217000070",
        "messages_outbox_id": "1100972179",
        "create_from_date": "1744102007",
        "create_to_date": "1744102007",
        "send_from_date": "1744102007",
        "send_to_date": "1744102007",
        "from_exit_count": 1,
        "to_exit_count": 100,
        "message": "تست",
        "state_id":"6"
    }
}

All fields in the filters object are optional. You can use any combination of them to filter your results. Some filter fields only accept specific predefined values. Below, you’ll find the list of allowed values for each field, along with a brief explanation of what each value means.

  • state_id:
    • 0: The message is in the process of create.
    • 1: The message create successfully and is in the monitoring queue.
    • 2: The message is in the process of sending.
    • 3: The message rejected by the monitoring system.
    • 4: The recipients of this message were either entered incorrectly or are not valid.
    • 5: The message is in send queue.
    • 6: The message was sent successfully.
    • 7: The message sending has been canceled.
    • 8: Insufficient credit for sending.
    • 9: The message was not sent due to a system error.

✅ Success Response

{
    "data": [
        {
            "username": "*****",
            "number_color": "#95E871",
            "number": "+981000",
            "number_id": "123654",
            "messages_outbox_id": "12545856",
            "state": "finish",
            "type": "pattern_transactional",
            "time_send": "1745409418",
            "time": "1745409418",
            "rcpts_count": "1",
            "exit_count": "1",
            "status": "پایان یافته",
            "partner_id": null,
            "in_delivery_line": 0,
            "valid": "approve",
            "message": "متن پیام",
            "part": null,
            "cost": 3990.2,
            "summary": null,
            "user_ip": null,
            "user_id": null,
            "files_path": null,
            "parent_id": null,
            "state_id": 6
        },
        {
            "username": "******",
            "number_color": "#95E871",
            "number": "+981000",
            "number_id": "1236587",
            "messages_outbox_id": "588459562",
            "state": "finish",
            "type": "pattern",
            "time_send": "1745409418",
            "time": "1745409418",
            "rcpts_count": "1",
            "exit_count": "1",
            "status": "پایان یافته",
            "partner_id": null,
            "in_delivery_line": 0,
            "valid": "approve",
            "message": "متن پیام",
            "part": null,
            "cost": 6144.9,
            "summary": null,
            "user_ip": null,
            "user_id": null,
            "files_path": null,
            "parent_id": null,
            "state_id": 6
        }
    ],
    "meta": {
        "current_page": 1,
        "from": 1,
        "last_page": 32282040,
        "path": "/api/report/new_list",
        "per_page": 2,
        "to": 2,
        "total": 64564080,
        "status": true,
        "message": "انجام شد",
        "message_code": "200-1"
    }
}

❌ Error Response — Invalid or Expired Token (401)

{
    "data": null,
    "meta": {
        "status": false,
        "message": "اطلاعات وارد شده صحیح نمی باشد",
        "message_parameters": [],
        "message_code": "400-1",
        "errors": {}
    }
}

❌ Error Response — Validation Error (422)

{
    "data": null,
    "meta": {
        "status": false,
        "message": "invalid state",
        "message_parameters": [],
        "message_code": "400-31",
        "errors": {}
    }
}

🧪 Example using curl

curl --location '{base_url}/api/report/new_list' \
--header 'Content-Type: application/json' \
--header 'Authorization: Your Apikey/Token' \
--data '{
    "page": 1,
    "limit": 10,
    "filters": {
        "username": "*",
        "number": "+98217000070",
        "messages_outbox_id": "1100972179",
        "create_from_date": "1744102007",
        "create_to_date": "1744102007",
        "send_from_date": "1744102007",
        "send_to_date": "1744102007",
        "from_exit_count": 1,
        "to_exit_count": 100,
        "message": "تست",
        "state_id":"6"
    }
}'

Get Outbox Report By ID

This API allows you to get a detailed report of a specific sent message using its ID.

📍 Endpoint

POST {base_url}/api/report/by_bulk/{messages_outbox_id}

🧾 Headers

Key Value
Content-Type application/json
Authorization your-token

📤 Request Body

{
    "page": 1,
    "limit": 10
}

✅ Success Response

{
    "data": {
        "username": "*****",
        "number_color": null,
        "number": "+98votp",
        "number_id": "154845",
        "messages_outbox_id": "5544778899",
        "state": "finish",
        "type": "sendvoice",
        "time_send": "1744121368",
        "time": "1744121368",
        "rcpts_count": "1",
        "exit_count": "1",
        "status": "پایان یافته",
        "return": 0,
        "partner_id": null,
        "in_delivery_line": 0,
        "valid": null,
        "message": "1234",
        "part": "1",
        "cost": 1064,
        "summary": "ارسال کد فعالسازی صوتی : 1234",
        "user_ip": "1.1.0.1",
        "user_id": "99885544",
        "reject_comment": null,
        "files_path": "1/send/SZiasdasdasdgghgf.wav",
        "parent_id": "98554",
        "state_id": 6
    },
    "meta": {
        "status": true,
        "message": "انجام شد",
        "message_code": "200-1"
    }
}

❌ Error Response — Invalid or Expired Token (401)

{
    "data": null,
    "meta": {
        "status": false,
        "message": "اطلاعات وارد شده صحیح نمی باشد",
        "message_parameters": [],
        "message_code": "400-1",
        "errors": {}
    }
}

🧪 Example using curl

curl --location '{base_url}/api/report/by_bulk/{messages_outbox_id}' \
--header 'Content-Type: application/json' \
--header 'Authorization: Your Apikey/Token'

Get Bulk Stats

This API allows you to get statistics about your sent messages.

📍 Endpoint

GET {base_url}/api/report/bulk_stats?bulk_id={messages_outbox_id}

🧾 Headers

Key Value
Content-Type application/json
Authorization your-token

✅ Success Response

{
    "data": {
        "operators_blacklist": {
            "irancell": {
                "en": 0,
                "fa": 0
            },
            "mci": {
                "en": 0,
                "fa": 0
            }
        },
        "operators_failed": {
            "irancell": {
                "en": 0,
                "fa": 0
            },
            "mci": {
                "en": 0,
                "fa": 0
            }
        },
        "operators_pending": {
            "irancell": {
                "en": 0,
                "fa": 0
            },
            "mci": {
                "en": 0,
                "fa": 0
            }
        },
        "operators_sent": {
            "irancell": {
                "en": 0,
                "fa": 0
            },
            "mci": {
                "en": 0,
                "fa": 0
            }
        },
        "operators_delivered": {
            "irancell": {
                "en": 0,
                "fa": "1"
            },
            "mci": {
                "en": 0,
                "fa": 0
            }
        }
    },
    "meta": {
        "status": true,
        "message": "انجام شد",
        "message_parameters": [],
        "message_code": "200-1"
    }
}

❌ Error Response — Invalid or Expired Token (401)

{
    "data": null,
    "meta": {
        "status": false,
        "message": "اطلاعات وارد شده صحیح نمی باشد",
        "message_parameters": [],
        "message_code": "400-1",
        "errors": {}
    }
}

❌ Error Response — Validation Error (422)

{
    "data": null,
    "meta": {
        "status": false,
        "message": "تکمیل گزینه bulk_id الزامی است",
        "message_parameters": [],
        "message_code": "400-2",
        "errors": {
            "bulk_id": [
                "تکمیل گزینه bulk_id الزامی است"
            ]
        }
    }
}

🧪 Example using curl

curl --location '{base_url}/api/report/bulk_stats?bulk_id={messages_outbox_id}' \
--header 'Content-Type: application/json' \
--header 'Authorization: Your Apikey/Token'

Get Bulk Recipients

This API allows you to get the recipients of a specific sent message using its ID. If the message status is finalized, the delivery status for each recipient will also be returned.

📍 Endpoint

GET {base_url}/api/report/recipients?page=1&per_page=10&bulk_id={messages_outbox_id}

🧾 Headers

Key Value
Content-Type application/json
Authorization your-token

✅ Success Response

{
    "data": [
        {
            "recipient": "+989190000000",
            "message": "متن پیام",
            "is_readable": true,
            "msg_parts": "1",
            "message_status": "1"
        },
        {
            "recipient": "+989120000000",
            "message": "با سلام",
            "is_readable": true,
            "msg_parts": "1",
            "message_status": "1"
        }
    ],
    "meta": {
        "current_page": 1,
        "from": 1,
        "last_page": 1,
        "path": "/api/report/recipients",
        "per_page": 10,
        "to": 2,
        "total": 2,
        "status": true,
        "message": "انجام شد",
        "message_code": "200-1"
    }
}

message_status field can have the following values:

  • 0: Sent to the operator
  • 1: Operator received the message
  • 2: Message delivered to the recipient
  • 3: Message not delivered to the recipient
  • 4: Blacklisted number

❌ Error Response — Invalid or Expired Token (401)

{
    "data": null,
    "meta": {
        "status": false,
        "message": "اطلاعات وارد شده صحیح نمی باشد",
        "message_parameters": [],
        "message_code": "400-1",
        "errors": {}
    }
}

❌ Error Response — Validation Error (422)

{
    "data": null,
    "meta": {
        "status": false,
        "message": "تکمیل گزینه bulk_id الزامی است",
        "message_parameters": [],
        "message_code": "400-2",
        "errors": {
            "bulk_id": [
                "تکمیل گزینه bulk_id الزامی است"
            ]
        }
    }
}

🧪 Example using curl

curl --location '{base_url}/api/report/recipients?page=1&per_page=10&bulk_id={messages_outbox_id}' \
--header 'Content-Type: application/json' \
--header 'Authorization: Your Apikey/Token'

📞 Numbers

With these endpoints, you can view and manage the lines that belong to you. If you are a reseller, you can also use these endpoints to manage the lines of your users, such as assigning a line to a user or reclaiming a line from a user.

Assign Number

This API allows you to assign a number to a user.

📍 Endpoint

POST {base_url}/api/numbers/assign

🧾 Headers

Key Value
Content-Type application/json
Authorization your-token

📤 Request Body

{
    "number_id": 10,
    "target_user_id": 123,
    "number": "+983000505",
    "target_user": "testuser",
    "send": true,
    "gets": false
}

API Request Parameters

number_id integer Conditional, ID of the phone number to assign to the user. Required if number is not provided.

target_user_id integer Conditional, ID of the target user. Required if target_user is not provided.

number string Conditional, The phone number to assign. Required if number_id is not provided.

target_user string Conditional, Username of the target user. Required if target_user_id is not provided.

send boolean Required, If true, the user will be allowed to send messages using this number.

gets boolean Required, If true, the user will be able to receive/view incoming messages for this number. Typically true for dedicated numbers.

✅ Note: You must provide at least one of each of the following pairs:

number_id or number

target_user_id or target_user

✅ Success Response

{
    "data": null,
    "meta": {
        "status": true,
        "message": "انجام شد",
        "message_parameters": [],
        "message_code": "200-1"
    }
}

❌ Error Response — Invalid or Expired Token (401)

{
    "data": null,
    "meta": {
        "status": false,
        "message": "اطلاعات وارد شده صحیح نمی باشد",
        "message_parameters": [],
        "message_code": "400-1",
        "errors": {}
    }
}

❌ Error Response — Validation Error (400)

{
    "data": null,
    "meta": {
        "status": false,
        "message": "number already assigned to user",
        "message_parameters": [],
        "message_code": "400-1",
        "errors": {}
    }
}

❌ Error Response — Validation Error (422)

{
    "data": null,
    "meta": {
        "status": false,
        "message": "تکمیل گزینه number id الزامی است (و 1 خطای دیگر)",
        "message_parameters": [],
        "message_code": "400-2",
        "errors": {
            "number_id": [
                "تکمیل گزینه number id الزامی است"
            ],
            "number": [
                "تکمیل گزینه number الزامی است"
            ]
        }
    }
}

🧪 Example using curl

curl --location '{base_url}/api/numbers/assign' \
--header 'Content-Type: application/json' \
--header 'Authorization: Your Apikey/Token' \
--data '{
    "number_id": 10,
    "target_user_id": 123,
    "number": "+983000505",
    "target_user": "testuser",
    "send": true,
    "gets": false
}'

Unassign Number

This API allows you to unassign a number from a user.

📍 Endpoint

POST {base_url}/api/numbers/unassign

🧾 Headers

Key Value
Content-Type application/json
Authorization your-token

📤 Request Body

{
    "number_id": 10,
    "target_user_id": 123,
    "number": "+983000505",
    "target_user": "testuser"
}

API Request Parameters

number_id integer Conditional, ID of the phone number to unassign from the user. Required if number is not provided.

target_user_id integer Conditional, ID of the target user. Required if target_user is not provided.

number string Conditional, The phone number to unassign. Required if number_id is not provided.

target_user string Conditional, Username of the target user. Required if target_user_id is not provided.

✅ Note: You must provide at least one of each of the following pairs:

number_id or number

target_user_id or target_user

✅ Success Response

{
    "data": null,
    "meta": {
        "status": true,
        "message": "انجام شد",
        "message_parameters": [],
        "message_code": "200-1"
    }
}

❌ Error Response — Invalid or Expired Token (401)

{
    "data": null,
    "meta": {
        "status": false,
        "message": "اطلاعات وارد شده صحیح نمی باشد",
        "message_parameters": [],
        "message_code": "400-1",
        "errors": {}
    }
}

❌ Error Response — Validation Error (400)

{
    "data": null,
    "meta": {
        "status": false,
        "message": "number not assigned to user",
        "message_parameters": [],
        "message_code": "400-1",
        "errors": {}
    }
}

❌ Error Response — Validation Error (422)

{
    "data": null,
    "meta": {
        "status": false,
        "message": "تکمیل گزینه number id الزامی است (و 1 خطای دیگر)",
        "message_parameters": [],
        "message_code": "400-2",
        "errors": {
            "number_id": [
                "تکمیل گزینه number id الزامی است"
            ],
            "number": [
                "تکمیل گزینه number الزامی است"
            ]
        }
    }
}

🧪 Example using curl

curl --location '{base_url}/api/numbers/unassign' \
--header 'Content-Type: application/json' \
--header 'Authorization: Your Apikey/Token' \
--data '{
    "number_id": 10,
    "target_user_id": 123,
    "number": "+983000505",
    "target_user": "testuser"
}'

About

IPPANEL Edge Document

Resources

Readme
Activity

Stars

0 stars

Watchers

0 watching

Forks

0 forks
Report repository

Releases

No releases published

Packages

No packages published