Send SMS messages, check credit balance, and view message reports.

Send Message

POST /messaging/send

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

FieldTypeRequiredValid values / constraintsDescription
recipientstringYesNormalizes to 09XXXXXXXXX (11 digits). Also accepts forms like 98912…, +98912…, 00989….Destination mobile.
messagestringYesMax 600 characters (API enforced).SMS text.
senderIdnumber or stringNoLine 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.
referenceIdnumberNoInteger > 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.
serverTypenumberNoDefault 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_domainstringNoYour 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 /messaging/credit

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 /messaging/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 /messaging/reports/outbox

Get sent messages report with pagination.

Query Parameters

ParameterTypeConstraintsDescription
pagenumberInteger ≥ 1 (default 1)Page index.
pageSizenumberInteger 1–100 (default 20)Rows per page.
dateFromstringParseable date, e.g. 2026-05-01Filter sent at ≥ start of day.
dateTostringParseable 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

GET /messaging/reports/outbox/{messageId}

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

ParameterTypeConstraintsDescription
messageIdstring (path)Positive integer, up to 19 digitsThe messageId from the send response.
bystringmessageId (default) or idUse 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 /messaging/reports/inbox

Get received messages report.

Query Parameters

ParameterTypeConstraintsDescription
pagenumberInteger ≥ 1 (default 1)Page index.
pageSizenumberInteger 1–100 (default 20)Rows per page.
dateFromstringParseable date, e.g. 2026-05-01Filter received at ≥ start of day.
dateTostringParseable date (end of day applied)Filter received at ≤ end of day.
searchstringAny 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"

HomaCRM External API

For support, create a ticket via /support/tickets endpoint.

Using WordPress? The HomaCRM WordPress plugin connects SMS and CRM without code.