WebSMS Connexus API

Simple, powerful SMS API for sending messages, receiving replies, and managing delivery reports

Migrating from Bulletin Connect? See our simple 3-step migration guide

Quick Start

Send your first SMS in seconds:

curl -X POST https://websms.co.nz/api/connexus/sms/out \
  -d "userId=user@domain.co.nz" \
  -d "password=yourpassword" \
  -d "to=6421234567" \
  -d "body=Hello World"

Returns HTTP 204 on success. Simple as that.

API Endpoints

Function Endpoint
Send SMS https://websms.co.nz/api/connexus/sms/out
Receive SMS (Webhook) https://websms.co.nz/api/connexus/sms/in
Delivery Status (Webhook) https://websms.co.nz/api/connexus/sms/status
Query Incoming Messages https://websms.co.nz/api/connexus/mo/query
Check Balance https://websms.co.nz/api/connexus/sms/balance
Send OTP/2FA Code https://websms.co.nz/api/connexus/sms/otp
Number Validation (IPMS) https://websms.co.nz/api/connexus/number/lookup

Send SMS Parameters

Parameter Required Description Example
userId Required Your WebSMS account email user@domain.co.nz
password Required Your WebSMS account password mypassword
to Required Recipient phone number (international format) 6421234567
body Required Message content Hello World
from Optional Sender ID 552
messageId Optional Unique message identifier (max 36 chars) MSG123456
rateCode Optional Message source identifier CAMPAIGN1
contentType Optional Message type text/plain
fragmentationLimit Optional Maximum SMS parts (0-3) 3
schedule Optional Unix timestamp for scheduled delivery 1735689600

Response Codes

204 Success - Message sent
400 Bad Request - Missing parameters
401 Unauthorized - Invalid credentials
403 Forbidden - Insufficient funds
500 Server Error

Pricing

Standard SMS (160 chars) $0.10 +GST
Multi-part SMS (per part) $0.10 +GST
Unicode SMS (70 chars) $0.10 +GST
GST applies to NZ customers only

Register Status Webhook (Delivery Reports)

Register your webhook URL to receive delivery status updates:

curl -X POST https://websms.co.nz/api/connexus/sms/status \
  -d "userId=user@domain.co.nz" \
  -d "password=yourpassword" \
  -d "url=https://yoursite.com/webhook/status"
Note: Once registered, your webhook URL will receive a POST request for each message status update with the following data:
// Your webhook will receive:
{
  "messageId": "MSG123",        // Your original messageId
  "status": "DELIVRD",          // Delivery status
  "statusCode": 1,              // Numeric status code
  "timestamp": 1234567890,      // Unix timestamp
  "details": {
    "smsc": "carrier_name",     // Network carrier
    "smscid": "abc123"          // Carrier message ID
  }
}

Status Codes:

statusCode status Description
1DELIVRDMessage delivered successfully
2UNDELIVMessage undeliverable
4QUEUEDMessage expired/queued
8ACCEPTDMessage accepted by network
16UNDELIVMessage undeliverable

Example Implementation (PHP):

<?php
// Register webhook first
$ch = curl_init('https://websms.co.nz/api/connexus/sms/status');
curl_setopt($ch, CURLOPT_POST, 1);
curl_setopt($ch, CURLOPT_POSTFIELDS, http_build_query([
    'userId' => 'user@domain.co.nz',
    'password' => 'yourpassword',
    'url' => 'https://yoursite.com/webhook/status.php'
]));
curl_exec($ch);
curl_close($ch);

// Then in your webhook handler (status.php):
$data = json_decode(file_get_contents('php://input'), true);

if ($data['status'] == 'DELIVRD') {
    // Message was delivered
    error_log("Message {$data['messageId']} delivered");
} elseif ($data['status'] == 'UNDELIV') {
    // Message failed
    error_log("Message {$data['messageId']} failed");
}
?>

Register Incoming SMS Webhook

Register your webhook URL to receive incoming SMS messages:

curl -X POST https://websms.co.nz/api/connexus/sms/in \
  -d "userId=user@domain.co.nz" \
  -d "password=yourpassword" \
  -d "url=https://yoursite.com/webhook/incoming"
Your webhook will receive incoming SMS messages from customers replying to your messages.
// Your webhook will receive:
{
  "messageId": "MO456",         // Unique message ID
  "from": "+6421234567",        // Sender's phone number
  "to": "shortcode",            // Recipient (shortcode or your number)
  "body": "Reply text",         // Message content
  "timestamp": 1234567890,      // Unix timestamp
  "type": "SMS",                // Message type
  "encoding": "text/plain",     // Content encoding
  "network": "carrier_name"     // Origin network
}

Example Implementation (PHP):

<?php
// Register webhook first
$ch = curl_init('https://websms.co.nz/api/connexus/sms/in');
curl_setopt($ch, CURLOPT_POST, 1);
curl_setopt($ch, CURLOPT_POSTFIELDS, http_build_query([
    'userId' => 'user@domain.co.nz',
    'password' => 'yourpassword',
    'url' => 'https://yoursite.com/webhook/incoming.php'
]));
curl_exec($ch);
curl_close($ch);

// Then in your webhook handler (incoming.php):
$data = json_decode(file_get_contents('php://input'), true);

// Process incoming message
$from = $data['from'];
$message = $data['body'];

// Reply to the message
$ch = curl_init('https://websms.co.nz/api/connexus/sms/out');
curl_setopt($ch, CURLOPT_POST, 1);
curl_setopt($ch, CURLOPT_POSTFIELDS, http_build_query([
    'userId' => 'user@domain.co.nz',
    'password' => 'yourpassword',
    'to' => ltrim($from, '+'),  // Remove + prefix
    'body' => 'Thank you for your message!'
]));
curl_exec($ch);
curl_close($ch);
?>

Query Incoming Messages (MO)

Query received mobile-originated messages with filters and pagination:

curl -X POST https://websms.co.nz/api/connexus/mo/query \
  -d "userId=user@domain.co.nz" \
  -d "password=yourpassword" \
  -d "from=6421234567" \
  -d "to=551" \
  -d "start_date=2025-01-01" \
  -d "end_date=2025-01-31" \
  -d "limit=100" \
  -d "page=1"

Query Parameters:

Parameter Required Description Example
userId Required Your WebSMS account email user@domain.co.nz
password Required Your WebSMS account password yourpassword
from Optional Filter by sender number 6421234567
to Optional Filter by recipient (shortcode) 551
callback_status Optional Filter by webhook callback HTTP status 200
start_date Optional Start of date range (Y-m-d or Y-m-d H:i:s) 2025-01-01
end_date Optional End of date range (Y-m-d or Y-m-d H:i:s) 2025-01-31
limit Optional Number of results per page (default: 100, max: 200) 100
page Optional Page number for pagination (default: 1) 1

Response Format:

{
  "status": "success",
  "messages": [
    {
      "messageId": "1234",
      "from": "6421234567",
      "to": "551",
      "body": "Reply message text",
      "receivedTime": "2025-01-15 14:30:00",
      "timestamp": 1736948400,
      "relatedMessageId": "5678",        // Optional: only if reply to sent message
      "callbackUrl": "https://...",      // Optional: only if webhook configured
      "callbackStatus": "200",           // Optional: only if webhook called
      "callbackResponse": "OK"           // Optional: only if webhook responded
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 100,
    "totalRecords": 250,
    "totalPages": 3,
    "hasNextPage": true,
    "hasPreviousPage": false
  },
  "filters": {
    "from": "6421234567",
    "to": "551",
    "callback_status": null,
    "start_date": "2025-01-01 00:00:00",
    "end_date": "2025-01-31 23:59:59"
  }
}
Note: Fields like relatedMessageId, callbackUrl, callbackStatus, and callbackResponse only appear in the response if they have values.

Example Implementation (PHP):

<?php
// Query incoming messages
$ch = curl_init('https://websms.co.nz/api/connexus/mo/query');
curl_setopt($ch, CURLOPT_POST, 1);
curl_setopt($ch, CURLOPT_POSTFIELDS, http_build_query([
    'userId' => 'user@domain.co.nz',
    'password' => 'yourpassword',
    'from' => '6421234567',
    'start_date' => '2025-01-01',
    'end_date' => '2025-01-31',
    'limit' => 100,
    'page' => 1
]));
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);

$response = curl_exec($ch);
$httpCode = curl_getinfo($ch, CURLINFO_HTTP_CODE);
curl_close($ch);

if ($httpCode == 200) {
    $data = json_decode($response, true);

    echo "Total messages: " . $data['pagination']['totalRecords'] . "\n";

    foreach ($data['messages'] as $msg) {
        echo "From: {$msg['from']}, Message: {$msg['body']}\n";
    }

    // Fetch next page if available
    if ($data['pagination']['hasNextPage']) {
        // Query with page=2
    }
} else {
    echo "Error: HTTP $httpCode";
}
?>

Check Account Balance

Query your account balance before sending messages:

curl -X POST https://websms.co.nz/api/connexus/sms/balance \
  -d "userId=user@domain.co.nz" \
  -d "password=yourpassword"

Response Format:

{
  "balance": "125.50",
  "currency": "NZD"
}
Note: The balance endpoint only requires authentication credentials. No message parameters are needed.

Example Implementation (PHP):

<?php
// Check account balance
$ch = curl_init('https://websms.co.nz/api/connexus/sms/balance');
curl_setopt($ch, CURLOPT_POST, 1);
curl_setopt($ch, CURLOPT_POSTFIELDS, http_build_query([
    'userId' => 'user@domain.co.nz',
    'password' => 'yourpassword'
]));
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);

$response = curl_exec($ch);
$httpCode = curl_getinfo($ch, CURLINFO_HTTP_CODE);
curl_close($ch);

if ($httpCode == 200) {
    $data = json_decode($response, true);
    echo "Current balance: $" . $data['balance'] . " " . $data['currency'];
} else {
    echo "Error: HTTP $httpCode";
}
?>

Send OTP/2FA Verification Code

Send a one-time verification code for 2FA authentication:

curl -X POST https://websms.co.nz/api/connexus/sms/otp \
  -d "userId=user@domain.co.nz" \
  -d "password=yourpassword" \
  -d "to=6421234567" \
  -d "msgCompany=MyApp"
Auto-generated code: If you don't provide a code, a secure 6-digit code will be generated automatically and returned in the response.

Parameters:

Parameter Required Description Example
userId Required Your WebSMS account email user@domain.co.nz
password Required Your WebSMS account password yourpassword
to Required Recipient phone number 6421234567
msgCompany Required Your company/app name (shown in message) MyApp
msgCode Optional Custom 4-8 digit code (auto-generated if not provided) 426817
msgComment Optional Additional text appended to message (truncated to fit 160 chars) Valid for 5 minutes.
from Optional Sender ID (default: 552) 552

Message Format:

{msgCode} is your {msgCompany} verification code{msgComment}

Examples:
- "426817 is your MyApp verification code"
- "426817 is your MyApp verification code. Valid for 5 minutes."

Response Format:

{
  "status": "success",
  "message_id": "abc123def456",
  "to": "6421234567",
  "from": "552",
  "code": "426817",      // The OTP code that was sent (store this to verify later!)
  "parts": 1
}
Important: The code field is always returned in the response. You must store this code on your server to verify the user's input later. The code is not stored by WebSMS.

Example Implementation (PHP):

<?php
// Send OTP code
function sendOTP($phone, $company) {
    $ch = curl_init('https://websms.co.nz/api/connexus/sms/otp');
    curl_setopt($ch, CURLOPT_POST, 1);
    curl_setopt($ch, CURLOPT_POSTFIELDS, http_build_query([
        'userId' => 'user@domain.co.nz',
        'password' => 'yourpassword',
        'to' => $phone,
        'msgCompany' => $company,
        'msgComment' => 'Valid for 5 minutes.'
    ]));
    curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);

    $response = curl_exec($ch);
    $httpCode = curl_getinfo($ch, CURLINFO_HTTP_CODE);
    curl_close($ch);

    if ($httpCode == 200) {
        $data = json_decode($response, true);

        // Store the code in your database/session for verification
        $_SESSION['otp_code'] = $data['code'];
        $_SESSION['otp_expires'] = time() + 300; // 5 minutes

        return ['success' => true, 'code' => $data['code']];
    }

    return ['success' => false, 'error' => "HTTP $httpCode"];
}

// Verify OTP code
function verifyOTP($userInput) {
    if (!isset($_SESSION['otp_code']) || !isset($_SESSION['otp_expires'])) {
        return false;
    }

    if (time() > $_SESSION['otp_expires']) {
        unset($_SESSION['otp_code'], $_SESSION['otp_expires']);
        return false; // Expired
    }

    if ($userInput === $_SESSION['otp_code']) {
        unset($_SESSION['otp_code'], $_SESSION['otp_expires']);
        return true; // Valid
    }

    return false; // Invalid
}

// Usage:
$result = sendOTP('6421234567', 'MyApp');
if ($result['success']) {
    echo "OTP sent! Code: " . $result['code'];
}

// Later, when user submits code:
if (verifyOTP($_POST['otp_input'])) {
    echo "Verified!";
} else {
    echo "Invalid or expired code";
}
?>

Phone Number Validation / IPMS Lookup

Validate NZ mobile numbers and check carrier portability status:

curl -X POST https://websms.co.nz/api/connexus/number/lookup \
  -d "userId=user@domain.co.nz" \
  -d "password=yourpassword" \
  -d "number=0211234567"
Pricing: $0.005 per lookup + GST. Real-time data from the IPMS (Industry Portability Management System).

Parameters:

Parameter Required Description Example
userId Required Your WebSMS account email user@domain.co.nz
password Required Your WebSMS account password yourpassword
number Required NZ mobile number (local 02x or international 642x format) 0211234567 or 6421234567

Success Response:

{
  "success": true,
  "number": "6421234567",
  "carrier": "Spark",
  "ported": false,
  "original_network": "Spark",
  "current_network": "Spark",
  "network_code": "TCNZ"
}

Error Responses (400 Bad Request):

// Number too short
{
  "success": false,
  "error": "Invalid number",
  "message": "Number too short. NZ mobile numbers must be 9-11 digits (e.g., 021234567)."
}

// Number too long
{
  "success": false,
  "error": "Invalid number",
  "message": "Number too long. NZ mobile numbers must be 9-11 digits (e.g., 021234567)."
}

// Invalid prefix
{
  "success": false,
  "error": "Invalid number",
  "message": "Invalid prefix. NZ mobile numbers must start with 02X (e.g., 021, 022, 027)."
}

// Invalid format
{
  "success": false,
  "error": "Invalid number",
  "message": "Invalid format. NZ mobile numbers must start with 02X (local) or 642X (international)."
}

Response Fields:

Field Description
successWhether the lookup was successful
numberNormalized phone number (international format)
carrierCurrent carrier name (Spark, One NZ, 2degrees, Skinny, etc.)
portedWhether the number has been ported from its original network
original_networkOriginal network based on number prefix
current_networkCurrent network servicing the number
network_codeNetwork operator code (TCNZ, VNZL, TNZD, etc.)

Example Implementation (PHP):

<?php
// Lookup a phone number
$ch = curl_init('https://websms.co.nz/api/connexus/number/lookup');
curl_setopt($ch, CURLOPT_POST, 1);
curl_setopt($ch, CURLOPT_POSTFIELDS, http_build_query([
    'userId' => 'user@domain.co.nz',
    'password' => 'yourpassword',
    'number' => '0211234567'
]));
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);

$response = curl_exec($ch);
$httpCode = curl_getinfo($ch, CURLINFO_HTTP_CODE);
curl_close($ch);

if ($httpCode == 200) {
    $data = json_decode($response, true);

    if ($data['success']) {
        echo "Number: " . $data['number'] . "\n";
        echo "Carrier: " . $data['carrier'] . "\n";
        echo "Ported: " . ($data['ported'] ? 'Yes' : 'No') . "\n";
    }
} else {
    echo "Error: HTTP $httpCode";
}
?>
Use Cases: SMS routing optimization, contact database cleaning, fraud prevention, carrier-based cost management, customer verification.

Configure All Webhooks

Alternative method to configure all webhooks at once:

# Get current configuration
curl -X GET https://websms.co.nz/api/connexus/configure.php \
  -u "user@domain.co.nz:password"

# Set webhook URLs
curl -X POST https://websms.co.nz/api/connexus/configure.php \
  -u "user@domain.co.nz:password" \
  -H "Content-Type: application/json" \
  -d '{
    "mo_webhook_url": "https://yoursite.com/receive-sms",
    "dlr_webhook_url": "https://yoursite.com/delivery-status"
  }'

Delivery Report Format

{
  "messageId": "MSG123",
  "status": "DELIVRD",
  "statusCode": 1,
  "timestamp": 1234567890,
  "details": {
    "smsc": "carrier",
    "smscid": "abc123"
  }
}

Incoming Message Format

{
  "messageId": "MO456",
  "from": "+6421234567",
  "to": "shortcode",
  "body": "Reply text",
  "timestamp": 1234567890,
  "type": "SMS",
  "encoding": "text/plain",
  "network": "carrier"
}

Code Examples

<?php
$url = 'https://websms.co.nz/api/connexus/sms/out';
$data = [
    'userId' => 'user@domain.co.nz',
    'password' => 'yourpassword',
    'to' => '6421234567',
    'body' => 'Hello from WebSMS!'
];

$ch = curl_init($url);
curl_setopt($ch, CURLOPT_POST, 1);
curl_setopt($ch, CURLOPT_POSTFIELDS, http_build_query($data));
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);

$response = curl_exec($ch);
$httpCode = curl_getinfo($ch, CURLINFO_HTTP_CODE);
curl_close($ch);

if ($httpCode == 204) {
    echo "Message sent successfully!";
} else {
    echo "Error: HTTP $httpCode";
}
?>
import requests

url = 'https://websms.co.nz/api/connexus/sms/out'
data = {
    'userId': 'user@domain.co.nz',
    'password': 'yourpassword',
    'to': '6421234567',
    'body': 'Hello from WebSMS!'
}

response = requests.post(url, data=data)

if response.status_code == 204:
    print("Message sent successfully!")
else:
    print(f"Error: HTTP {response.status_code}")
const axios = require('axios');

const data = new URLSearchParams({
    userId: 'user@domain.co.nz',
    password: 'yourpassword',
    to: '6421234567',
    body: 'Hello from WebSMS!'
});

axios.post('https://websms.co.nz/api/connexus/sms/out', data)
    .then(response => {
        if (response.status === 204) {
            console.log('Message sent successfully!');
        }
    })
    .catch(error => {
        console.error('Error:', error.response?.status);
    });
using System;
using System.Net.Http;
using System.Collections.Generic;

var client = new HttpClient();
var values = new Dictionary<string, string>
{
    { "userId", "user@domain.co.nz" },
    { "password", "yourpassword" },
    { "to", "6421234567" },
    { "body", "Hello from WebSMS!" }
};

var content = new FormUrlEncodedContent(values);
var response = await client.PostAsync(
    "https://websms.co.nz/api/connexus/sms/out", 
    content
);

if ((int)response.StatusCode == 204)
{
    Console.WriteLine("Message sent successfully!");
}
else
{
    Console.WriteLine($"Error: {response.StatusCode}");
}

Need Help?

API Support

Our team is here to help with your integration:

  • Free integration assistance
  • Testing credits available
  • Direct technical support

Contact Us

Email: support@websms.co.nz
Phone: +64 27 4909-712
Hours: Monday-Friday, 9am-5pm NZST

Migrating from Bulletin Connect?

If you're moving from Bulletin Connect, switching to WebSMS is straightforward. Our Connexus API is fully compatible - just update three things:

OLD

service.bulletinconnect.net

NEW

websms.co.nz
  1. Username: Your WebSMS email
  2. Password: Your WebSMS password
  3. URL: Change domain only
100% Compatible - No code changes required beyond updating your configuration

Endpoint Mapping

Function Bulletin Connect WebSMS
Send SMS http://service.bulletinconnect.net/api/1/sms/out https://websms.co.nz/api/connexus/sms/out
Receive SMS http://service.bulletinconnect.net/api/1/sms/in https://websms.co.nz/api/connexus/sms/in
Status Updates http://service.bulletinconnect.net/api/1/sms/status https://websms.co.nz/api/connexus/sms/status

Need help with migration? Contact us at support@websms.co.nz - we offer free migration assistance.