Messaging API
Send SMS messages, check credit balance, and view message reports.
Send Message
Send a single SMS message to one recipient. The server resolves the operator line from senderId and/or referenceId; see the table below.
Request Body
| Field | Type | Required | Valid values / constraints | Description |
|---|---|---|---|---|
recipient | string | Yes | Normalizes to 09XXXXXXXXX (11 digits). Also accepts forms like 98912…, +98912…, 00989…. | Destination mobile. |
message | string | Yes | Max 600 characters (API enforced). | SMS text. |
senderId | number or string | No | Line reference: one of your portal's active lines, either its ID from GET /messaging/numbers (e.g. 42) or the line number itself (e.g. 9890003259; 98…, +98… and 0098… forms are accepted).Black List: -11, or 99, or 100 (mapped to Black List).A value that matches one of your lines is always sent from that line. Otherwise the message still goes out — through the Black List path if the value looks like an Iranian mobile or is not a valid ID, or from your portal's default line for an unknown ID — and the response carries senderWarning. | Preferred way to choose the sending line. If set to a positive integer, referenceId in the body is ignored. |
referenceId | number | No | Integer > 0 (e.g. 5001) = same meaning as a positive senderId line ref. -11 = Black List. Omit or use Black List only if WhoIS for the portal is approved. | Use when you do not send a usable senderId. Ignored if senderId is a positive integer. |
serverType | number | No | Default 1 (typical dedicated-line send). If the request ends up on the Black List path (no valid line ref), the API sets serverType to 99 internally regardless of this field. | Operator / route hint passed to the SMS service for non–Black-List sends. |
otp_domain | string | No | Your site's hostname (e.g. shop.example.com). A one-time-code text (exactly one 4–8 digit number plus «کد», «رمز», code or OTP) gets a last line @domain #code after «لغو11», so iPhone and Android Chrome suggest the code. Omitted ⇒ taken from the default WordPress User-Agent (WordPress/x.y; https://www.site.tld ⇒ site.tld); neither ⇒ text unchanged. An existing line of that shape is not duplicated. | Adds about 20 characters; a text near 70 characters becomes two pages. |
Default behaviour: If both senderId and referenceId are missing or do not resolve to a positive line ID (and not Black List), the request uses the Black List path (serverType forced to 99), which requires an approved WhoIS profile for the portal.
Example — send via a dedicated line (from /messaging/numbers)
curl -X POST "https://www.HomaCRM.com/api/v1/external/messaging/send" \
-H "Authorization: a1B2c3D4e5F6g7H8-i9J0k1L2m3N4o5P6-q7R8s9T0u1V2w3X4" \
-H "Content-Type: application/json" \
-d '{
"recipient": "09129876543",
"message": "کد تأیید شما: 847291. اعتبار ۵ دقیقه.",
"senderId": 42,
"serverType": 1
}'
Example — same line using referenceId only (no senderId)
curl -X POST "https://www.HomaCRM.com/api/v1/external/messaging/send" \
-H "Authorization: a1B2c3D4e5F6g7H8-i9J0k1L2m3N4o5P6-q7R8s9T0u1V2w3X4" \
-H "Content-Type: application/json" \
-d '{
"recipient": "09129876543",
"message": "کد تأیید شما: 847291. اعتبار ۵ دقیقه.",
"referenceId": 42,
"serverType": 1
}'
Response
{
"success": true,
"data": {
"messageId": 184920315,
"recipient": "09129876543",
"status": "queued",
"deliveryCode": 0,
"creditUsed": 1
},
"meta": {
"requestId": "req_7f3a9c21b4e8"
}
}
Get Credit Balance
Get your current SMS credit balance.
Example
curl -X GET "https://www.HomaCRM.com/api/v1/external/messaging/credit" \
-H "Authorization: a1B2c3D4e5F6g7H8-i9J0k1L2m3N4o5P6-q7R8s9T0u1V2w3X4" \
-H "Accept: application/json"
Response
{
"success": true,
"data": {
"balance": 1250000,
"balanceToman": 125000,
"currency": "Rial",
"estimatedMessages": 62500,
"lastUpdated": "2026-05-09T12:34:56.789Z"
}
}
Get Sender Numbers
Get list of available sender numbers for your portal.
Example
curl -X GET "https://www.HomaCRM.com/api/v1/external/messaging/numbers" \
-H "Authorization: a1B2c3D4e5F6g7H8-i9J0k1L2m3N4o5P6-q7R8s9T0u1V2w3X4" \
-H "Accept: application/json"
Outbox Report
Get sent messages report with pagination.
Query Parameters
| Parameter | Type | Constraints | Description |
|---|---|---|---|
page | number | Integer ≥ 1 (default 1) | Page index. |
pageSize | number | Integer 1–100 (default 20) | Rows per page. |
dateFrom | string | Parseable date, e.g. 2026-05-01 | Filter sent at ≥ start of day. |
dateTo | string | Parseable date (end of day applied) | Filter sent at ≤ end of day. |
Example
curl -G "https://www.HomaCRM.com/api/v1/external/messaging/reports/outbox" \
-H "Authorization: a1B2c3D4e5F6g7H8-i9J0k1L2m3N4o5P6-q7R8s9T0u1V2w3X4" \
-H "Accept: application/json" \
--data-urlencode "page=1" \
--data-urlencode "pageSize=25" \
--data-urlencode "dateFrom=2026-05-01" \
--data-urlencode "dateTo=2026-05-09"
Get One Sent Message
Look up one sent SMS by the messageId that POST /messaging/send returned. Read-only; scope messaging:reports:read. Only messages of the token's portal are visible: an id that is not in this portal returns 404 (E3001), never another portal's data.
Path & Query Parameters
| Parameter | Type | Constraints | Description |
|---|---|---|---|
messageId | string (path) | Positive integer, up to 19 digits | The messageId from the send response. |
by | string | messageId (default) or id | Use id to look up by the row id that reports/delivery-log returns. |
Status: sent means the operator accepted the message. delivered appears only after the operator sends a delivery report; delivery reports are not guaranteed (some operators or handsets never send one), so a message can stay sent even when it arrived. failed means the operator reported it as not delivered. statusCode is the raw operator code. sentAt is server local time (Tehran), without a zone suffix.
Limits: a messageId lookup searches the portal's newest 200,000 sent messages (older ones: use reports/delivery-log and ?by=id), and at most 60 messageId lookups per minute per portal are answered (?by=id is not limited). A messageId of the form unverified-… (send accepted without an operator record id) is not a record id and always returns 404.
Errors: 400 E2003 invalid id or by; 404 E3001 not found in this portal (or not a record id); 409 E3003 portal moved to the new SMS node (report not available yet); 429 E1004 too many messageId lookups this minute.
Example
curl "https://www.HomaCRM.com/api/v1/external/messaging/reports/outbox/7739012845" \
-H "Authorization: a1B2c3D4e5F6g7H8-i9J0k1L2m3N4o5P6-q7R8s9T0u1V2w3X4" \
-H "Accept: application/json"
{
"success": true,
"data": {
"id": "48211903",
"messageId": "7739012845",
"recipient": "09121234567",
"message": "Your code is 4821",
"sentAt": "2026-11-15T10:30:12",
"status": "delivered",
"statusCode": 1,
"units": 1,
"programId": null,
"sentboxId": null
},
"meta": { "requestId": "req_abc123xyz" }
}
Inbox Report
Get received messages report.
Query Parameters
| Parameter | Type | Constraints | Description |
|---|---|---|---|
page | number | Integer ≥ 1 (default 1) | Page index. |
pageSize | number | Integer 1–100 (default 20) | Rows per page. |
dateFrom | string | Parseable date, e.g. 2026-05-01 | Filter received at ≥ start of day. |
dateTo | string | Parseable date (end of day applied) | Filter received at ≤ end of day. |
search | string | Any substring (SQL LIKE %search%) | Match sender mobile or message body. |
Example
curl -G "https://www.HomaCRM.com/api/v1/external/messaging/reports/inbox" \
-H "Authorization: a1B2c3D4e5F6g7H8-i9J0k1L2m3N4o5P6-q7R8s9T0u1V2w3X4" \
-H "Accept: application/json" \
--data-urlencode "page=1" \
--data-urlencode "pageSize=20" \
--data-urlencode "dateFrom=2026-05-01" \
--data-urlencode "dateTo=2026-05-09" \
--data-urlencode "search=0912"