Connexus/Bulletin Connect API Migration

Seamless migration from Bulletin Connect to WebSMS - Just change your credentials and URL!

100% Compatible - No code changes required, just update your configuration

3-Step Migration

OLD (Bulletin)

service.bulletinconnect.net

NEW (WebSMS)

websms.co.nz

Just Update:

  • Username: Your WebSMS email
  • Password: Your WebSMS password
  • URL: Change domain only

Before (Bulletin Connect)

curl -X POST http://service.bulletinconnect.net/api/1/sms/out \
  -d "userId=myuser" \
  -d "password=mypass" \
  -d "to=6421234567" \
  -d "body=Hello World"

After (WebSMS)

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

API Endpoints

Function Bulletin Connect URL WebSMS Replacement URL
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
Query MO Messages N/A https://websms.co.nz/api/connexus/mo/query
Check Balance N/A https://websms.co.nz/api/connexus/sms/balance
Send OTP/2FA Code N/A https://websms.co.nz/api/connexus/sms/otp

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 2190
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:

Bulletin Connect Method:

POST http://service.bulletinconnect.net/api/1/sms/status
Content-Type: application/x-www-form-urlencoded

userId=myuser&password=mypass&url=https://yoursite.com/status

WebSMS Method:

POST https://websms.co.nz/api/connexus/sms/status
Content-Type: application/x-www-form-urlencoded

userId=user@domain.co.nz&password=pass&url=https://yoursite.com/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:

Bulletin Connect Method:

POST http://service.bulletinconnect.net/api/1/sms/in
Content-Type: application/x-www-form-urlencoded

userId=myuser&password=mypass&url=https://yoursite.com/incoming

WebSMS Method:

POST https://websms.co.nz/api/connexus/sms/in
Content-Type: application/x-www-form-urlencoded

userId=user@domain.co.nz&password=pass&url=https://yoursite.com/incoming
Note: 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: 2190) 2190

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": "2190",
  "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";
}
?>

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?

Migration Support

Our team is ready to help you migrate from Bulletin Connect:

  • Free migration assistance
  • Testing credits available
  • Direct support during transition

Contact Us

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