Web2SMS API Documentation

Integrate SMS messaging into your applications with our simple and powerful REST API

Quick Start

With our Web to SMS service, you can automate the sending of text messages from your website or devices. You'll need credit in your account to send messages.

Note: SMS messages cost $0.10 +GST per message. Premium route with delivery reports costs an additional $0.02 +GST per message.

API Endpoint

Send SMS Endpoint


                            https://websms.co.nz/api/send.php

Example Request

https://websms.co.nz/api/send.php?username=username@domain.co.nz&password=mypassword&premium=0&cellnum=64271234567&message=Hello from WebSMS API

Optional Delivery Report URL


                            &dlrurl=http://www.yoururl.co.nz/delivery-report.php

Parameters

Parameter	Required	Description	Example
`username`	Required	Your WebSMS account username (email)	`user@domain.co.nz`
`password`	Required	Your WebSMS account password	`mypassword`
`cellnum`	Required	Recipient phone number (with country code)	`64271234567`
`message`	Required	SMS message content (max 160 characters)	`Hello World`
`premium`	Optional	Use premium route for delivery reports (0 or 1)	`1`
`dlrurl`	Optional	URL for delivery report callbacks	`http://yoursite.com/dlr.php`
`balance`	Optional	Check account balance only (true)	`true`

Response Codes

Success Responses

Response	Description
`OK:Queued:109720`	Message successfully queued with ID 109720

Error Responses

Response	Description
`NOK:Funds:You do not have enough funds`	Insufficient account balance
`NOK:Login:Invalid Username or Password`	Authentication failed

Delivery Reports (DLR)

When you specify a dlrurl, we'll send delivery status updates to your server via GET requests.

Example DLR Callbacks

GET /delivery-report.php?id=109720&dlr=8 - Message Queued
GET /delivery-report.php?id=109720&dlr=1 - Message Delivered

DLR Status Codes

DLR Code	Status	Description
`1`	Delivered	Message successfully delivered to handset
`2`	Failed	Delivery failure
`4`	Buffered	Message buffered for delivery
`8`	Queued	Message queued at SMSC
`16`	Rejected	Message rejected by SMSC

Note: Sometimes messages may be delivered but only show DLR 8 (Queued) due to SMSC resource prioritization.

Reply Messages

Reply messages are delivered to your registered email address and optionally to your DLR URL.

Reply Callback Example

GET /delivery-report.php?id=+109720&reply=Reply Text

Note the + prefix in the message ID for reply messages.

Balance Check

Check your account balance programmatically using the API.

Balance Check Request

https://websms.co.nz/api/send.php?username=user@domain.co.nz&password=mypassword&balance=true

Returns your current account balance in credits.

Code Examples

PHP Example

<?php
$username = 'user@domain.co.nz';
$password = 'mypassword';
$to = '64271234567';
$message = 'Hello from PHP!';

$url = 'https://websms.co.nz/api/send.php?' . http_build_query([
    'username' => $username,
    'password' => $password,
    'cellnum' => $to,
    'message' => $message,
    'premium' => 0
]);

$response = file_get_contents($url);
echo $response;
?>

JavaScript (Node.js) Example

const axios = require('axios');

const params = {
    username: 'user@domain.co.nz',
    password: 'mypassword',
    cellnum: '64271234567',
    message: 'Hello from Node.js!',
    premium: 0
};

axios.get('https://websms.co.nz/api/send.php', { params })
    .then(response => {
        console.log(response.data);
    })
    .catch(error => {
        console.error(error);
    });

Python Example

import requests

params = {
    'username': 'user@domain.co.nz',
    'password': 'mypassword',
    'cellnum': '64271234567',
    'message': 'Hello from Python!',
    'premium': 0
}

response = requests.get('https://websms.co.nz/api/send.php', params=params)
print(response.text)

Need Help with Integration?

Our support team is here to help you get started with the WebSMS API

Migrating from Bulletin Connect?

We also offer a drop-in replacement API that's 100% compatible with Bulletin Connect/Connexus. No code changes required - just update your credentials and URL!

View Connexus API Documentation