# Biz SMS **Biz SMS** is a batch-oriented HTTP SMS gateway built for high-volume, two-way campaigns — with delivery receipts, reply routing through virtual numbers, scheduling, and credit/charge queries. It is a distinct product from the JSON [SMS Gateway](/apis/sms) and the [Omnichannel API](/apis/omnichannel). For the full endpoint and schema reference, see the [Biz SMS API](/apis/biz-sms). ## How it works - Requests are sent as **`application/x-www-form-urlencoded`** parameters ("keywords"). Use **HTTP POST** in production; `GET` is only for light testing. - Responses are **XML** documents in the namespace `http://messaging.ecommunicate.biz/sms/response`. Parse them with a namespace-aware XML parser — attribute order and tag counts are not guaranteed. - Implement **HTTP/1.1 Keep-Alive**, and break large sends into ~200 numbers per POST. ## Base URL ``` https://messaging.ecommunicate.biz ``` HTTPS is also available on port `8443`. ## Authentication Every request is authenticated with an **API key** — send an `X-API-Key: ecom_...` header. Generate and revoke keys from the client portal. Use HTTPS so the key is never sent in the clear. ## Correlation: batchref + batchid Biz SMS has no per-message id. Each send is identified by a client-chosen **`batchref`** (max 80 chars) plus a **`batchid`** (unique within the batchref, max 20 chars). You pull delivery receipts and replies later using the same pair. Duplicate sends are protected Re-sending an identical `batchref` + `batchid` does **not** resend. The gateway returns the original response wrapped in `` with status `1034`. ## Send your first batch Choose a reply model first: either set a `senderid` (non-priority), **or** set `priority=true` with `repliesperuserid` (or `manageownreplies` + `virtualname`). ```bash curl -X POST https://messaging.ecommunicate.biz/smsbatch/sms \ -H "Content-Type: application/x-www-form-urlencoded" \ -H "X-API-Key: ecom_your_api_key" \ --data-urlencode "batchref=Finance-2026-05" \ --data-urlencode "batchid=1" \ --data-urlencode "senderid=eCommunicate" \ --data-urlencode "rdr=true" \ --data-urlencode "message=Your statement is ready" \ --data-urlencode "cell=27821234567, Jane Doe | 27821234568" ``` **Response — a send is successful when `` is `0` (or `1` for partial):** ```xml success 2026-05-21T21:22:26+02:00 Finance-2026-05 1 2 2 ``` ## Cell number format - Numbers are 10–11 digits; non-numeric characters (brackets, dashes, spaces) are stripped. - South African numbers must start with `27`, `+27`, or `0`. - International numbers must include the destination country's IDD code (e.g. Botswana `26771333444`). - Separate multiple numbers with commas. To attach an identifier that contains digits, separate it from the number with a `|`. ## Message length | Mode | Per SMS | Concatenated (per part) | Max | | --- | --- | --- | --- | | GSM (default) | 160 | 156 (auto-split, prefixed `1/3`, `2/3`…) | 9 parts | | `concat=true` | — | 153 | 9 parts (1377) | | `unicode=true` | 70 | 67 | 9 parts | Use `maxparts` to cap segments and protect against unintended extra-SMS billing. ## Pull delivery receipts The original send must have used `rdr=true`. ```bash curl -X POST https://messaging.ecommunicate.biz/smsbatch/deliveryreceiptscheck \ -H "Content-Type: application/x-www-form-urlencoded" \ -H "X-API-Key: ecom_your_api_key" \ --data-urlencode "batchref=Finance-2026-05" \ --data-urlencode "batchid=1" ``` Final states include `DELIVRD`, `UNDELIV`, `EXPIRED`, `REJECTD`, `UNKNOWN`, and `NOTAVAIL`. Until a message reaches a final state it is `PENDING` and returns no receipt. ## Pull replies The original send must have enabled replies (`repliesperuserid` or `manageownreplies`). ```bash curl -X POST https://messaging.ecommunicate.biz/smsbatch/replysmscheck \ -H "Content-Type: application/x-www-form-urlencoded" \ -H "X-API-Key: ecom_your_api_key" ``` Disambiguating replies When you message the same recipient across multiple batches, use a different `senderid` / virtual number per batch so replies can be matched back to the right campaign. ## Check credits ```bash curl -X POST https://messaging.ecommunicate.biz/smsbatch/servicequery \ -H "Content-Type: application/x-www-form-urlencoded" \ -H "X-API-Key: ecom_your_api_key" \ --data-urlencode "version=2.55" \ --data-urlencode "creditcheck=true" ``` Use `charge=true` with a `cell` number to estimate the cost of a send before dispatching it. ## Email-to-SMS Biz SMS can also send an SMS straight from an email — no HTTP request needed. Address the email to the recipient's cell number at the Biz SMS domain, put your account password in the subject, and write the message in the body. | | Address | | --- | --- | | **Live** | `cellnumber@ecommunicate.biz` | | **Test** | `cellnumber@ecommunicate.co.za` | For example, to SMS `27821234567`, send an email to `27821234567@ecommunicate.biz`. | Part | Contents | | --- | --- | | **To** | `@ecommunicate.biz` — the recipient's number in `27` format | | **Subject** | Your account **password** | | **Body** | The message text, **160 characters or less**, followed by a blank line | The gateway emails the batch result back to the sender. An error email is returned if the message exceeds 160 characters or the password is wrong. Setup required Email-to-SMS must be enabled on your account by eCommunicate, and every sender email address must be pre-registered (each address is globally unique across the platform). Contact [support@ecommunicate.co.za](mailto:support@ecommunicate.co.za) to enable it. ## Status codes at a glance | Code | Meaning | | --- | --- | | `0` | Success | | `1` | Partial success (some invalid numbers) | | `1010` | Authentication failed | | `1021` | `message` keyword missing | | `1034` | Duplicate `batchref` + `batchid` | | `1071` | All numbers had invalid formats | | `1100` | A `senderid` is required | | `1310` | Bad `futuredatetime` format | | `2012` | Insufficient credits | Full ranges: `1000`–`1999` keyword errors, `2000`–`2999` functional errors, `3000`–`3999` system errors.