# Biz SMS API **Biz SMS** (the eCommunicate Automated Interactive SMS gateway) is a batch-oriented HTTP SMS API built for high-volume, two-way campaigns with delivery receipts, reply routing via virtual numbers, scheduling, and credit/charge queries. It is a distinct product from the JSON [SMS Gateway API](./sms.yaml) and the WhatsApp-centric [Omnichannel Integration API](./omnichannel.yaml). An **Email-to-SMS** facility is also available — send an email addressed to `cellnumber@ecommunicate.biz` and the gateway sends the SMS. See the Biz SMS guide for details. ## How it works - Requests are sent as **`application/x-www-form-urlencoded`** parameters ("keywords"). Production traffic must use **HTTP POST**; `GET` is only for light testing (roughly five numbers or fewer). - Responses are **XML** documents in the namespace `https://messaging.ecommunicate.biz/sms/response` (the `httpresponse` diagnostic returns plain text). Always parse with a namespace-aware XML parser — attribute order and tag counts are not fixed. - Implement **HTTP/1.1 Keep-Alive**. Break large batches into ~200 numbers per POST, reusing the same `batchref` and incrementing `batchid`. ## Correlation: batchref + batchid There is 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. Re-sending an identical `batchref`+`batchid` does **not** resend — the gateway returns the original response wrapped in `` (status `1034`). ## Authentication Every request is authenticated with an **API key**: send an `X-API-Key: ecom_...` header. Generate and revoke keys from the client portal. The optional `specversion`, `commsversion`, and `appversion` keywords are advisory. The gateway keys on major version **2**. ## Status codes Every outcome is carried in the XML ``. Ranges: `0` success · `1`–`99` partial success / fail · `1000`–`1999` keyword error · `2000`–`2999` functional error · `3000`–`3999` system error. A send is successful when the code is `0` (or `1` = partial, some invalid numbers). Common codes: `1010` authentication failed · `1021` message keyword missing · `1034` duplicate batchref+batchid · `1071` all numbers invalid · `1100` senderid required · `2012` insufficient credits · `1310` bad `futuredatetime` format. High-volume batch SMS with two-way replies, delivery receipts and virtual numbers. Version: 2.62 ## Servers Production (HTTPS also available on port 8443) ``` https://messaging.ecommunicate.biz ``` ## Security ### ApiKeyAuth Per-client API key, prefixed `ecom_`. Required on every request. Generate and revoke keys from the client portal. Type: apiKey In: header Name: X-API-Key ## Download OpenAPI description [Biz SMS API](https://docs.ecommunicate.co.za/_bundle/apis/biz-sms.yaml) ## Messaging Send batch SMS. ### Send SMS batch - [POST /smsbatch/sms](https://docs.ecommunicate.co.za/apis/biz-sms/messaging/sendbatch.md): Send one message to one or many numbers, immediately or scheduled. Provide a source of replies by either setting senderid (non-priority) or priority=true with one of repliesperuserid or manageownreplies+virtualname. Also available over GET for testing (~5 numbers). Returns an XML batch-send result; check ` is 0 (or 1` for partial success). ## Delivery Receipts Pull delivery receipts for a sent batch. ### Check delivery receipts - [POST /smsbatch/deliveryreceiptscheck](https://docs.ecommunicate.co.za/apis/biz-sms/delivery-receipts/checkdeliveryreceipts.md): Pull delivery receipts for a previously sent batch. The original send must have used rdr=true. Use repeatallreceipts=true to re-fetch receipts you have already retrieved. Until a message reaches a final state it is PENDING and returns no receipt. ## Replies Pull inbound replies routed to virtual numbers. ### Check replies - [POST /smsbatch/replysmscheck](https://docs.ecommunicate.co.za/apis/biz-sms/replies/checkreplies.md): Pull inbound replies routed to your virtual numbers. The original send must have used repliesperuserid or manageownreplies. Use repeatallreplies=true to re-fetch replies already returned. Only a client admin userid may filter by virtualname. ## Inbound Retrieve messages sent by handsets to a keyword-routed number. ### Check incoming messages - [POST /smsservice/messagecheck](https://docs.ecommunicate.co.za/apis/biz-sms/inbound/checkincomingmessages.md): Retrieve messages sent by handsets to a keyword-routed mobile number. Requires a campaign/keyword setup with eCommunicate. Filter to a sub-campaign with smskeyword. Uses a different namespace (http://messaging.ecommunicate.biz/sms/service) and a plain `` root. ## Account Credit checks, server time, and SMS cost queries. ### Service query - [POST /smsbatch/servicequery](https://docs.ecommunicate.co.za/apis/biz-sms/account/servicequery.md): Credit checks, server time, SMS cost, and connectivity diagnostics. Exactly one of servertime, httpresponse, creditcheck, or charge is required. charge also requires version > 2.00 and cell. ## Templates Predefined messages and cell-number groups. ### Manage templates - [POST /smsbatch/templates](https://docs.ecommunicate.co.za/apis/biz-sms/templates/managetemplates.md): Register a predefined message (pmessage + message) or a predefined cell group (pgroup + cell) to reference later instead of inlining. Requires version=2.55. Note: this operation is not yet fully implemented. ## Batches Manage scheduled (delayed) batches. ### Manage delayed batches - [POST /smsbatch/managebatch](https://docs.ecommunicate.co.za/apis/biz-sms/batches/managebatch.md): Delete an unsent delayed (futuredatetime) batch. Best-effort, not guaranteed. Requires deletebatch=true with the original batchref and batchid, and version=2.55. ## Webhooks Push callbacks the gateway POSTs to your server (not yet supported). ### Delivery receipt push - [POST urlreceipts](https://docs.ecommunicate.co.za/apis/biz-sms/webhooks/onreceiptpush.md): When urlreceipts is set on a send (and rdr=true), the gateway POSTs form parameters to your URL as final receipts arrive. PENDING states are not pushed. Not yet supported in this version. ### Reply push - [POST urlreplies](https://docs.ecommunicate.co.za/apis/biz-sms/webhooks/onreplypush.md): When urlreplies is set on a send (with repliesperuserid or manageownreplies), the gateway POSTs form parameters to your URL for each reply. Not yet supported in this version.