Messaging API

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: positive integer = ID from GET /messaging/numbers (same as row in accounts_refnumbers), e.g. 42. Black List: -11, or 99, or 100 (mapped to Black List). If the value looks like an Iranian mobile (09…), it is not used as a line ID; resolution falls through to referenceId.	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.

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 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 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"

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 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"