NodeJS Library v2.04 Jul 2023

NodeJS Library Introduction

Using a single NodeJS library, NodeJS developers can send Email, SMS, Fax, Voice and Text-to-Speech messages using their own software.

TypeScript Library

A newer TypeScript-first library, tnzapi-ts, is also available, targeting the current REST API v3.00. See TypeScript Library.

Getting started

Register your account

If you don't have an account, head to https://www.tnz.co.nz/Customer/SignUp/ and fill in the form.

Create an API user

To access the API, you'll need a User with API access:

  1. Login to the TNZ Dashboard
  2. Navigate to 'Users'
  3. Create a new user or select an existing one
  4. Enable API access (if it's not already enabled)
  5. Click on the 'API' tab
  6. Enable 'Auth Token' and create a new Auth Token
  7. Click the ' Copy' button to copy it to your clipboard
  8. Paste the Auth Token into the Authorization Header in your application or code

At any time, you can refresh your Auth Token by clicking the button and exporting your new Auth Token. This action will invalidate any apps using your old Auth Token.

Auth Tokens can be used for multiple use-cases, with SubAccount and Department values helping in tracking reporting and billing.

API v2.04 utilizes JWT token Authentication. For OAuth2 authentication options, contact your TNZ representative.

Understanding the NodeJS Library basics

Save hundreds of lines of code and hours of time by add the TNZ NodeJS library into your project. Using one package and simple code tweaks, your software can send Email, SMS, Fax, Voice and Text-to-Speech messages.

For a brief overview of the API, see the TNZ API Structure guide.


Download the Library:

Download and install the 'tnzapi' using npm: npm i tnzapi

TNZAPI npm Package

Alternatively you can download source code from GitHub

Reference the Library:

Reference the library in your code: const tnzapi = require('tnzapi');

Send Messages using the Library:

Using the [request].SendMessage(callback_function); function, the package will connect to TNZ's REST API (in JSON format) and send messages.

Capture Status & Replies using the Library:

Message Status and Received Messages can be captured using a Webhook (a POST to your nominated URL), or can be Polled for using the Library's [request].Poll(callback_function); function.

See Status Reporting and Receive Messages.

Send Messages

build your application with the NodeJS Library

Find instructions for each Message Type:

Sending Email

Send Email via TNZ NodeJS Library

Send Email (Basic):

const TNZAPI = require('tnzapi');

const client = new TNZAPI({
    AuthToken: "[Your Auth Token]"          // Auth Token
});

var callback = function(data) {
    console.log("Response: ",JSON.stringify(data, null, "  "));
};

client.Messaging.Email.SendMessage({
    FromEmail: "from@test.com",             // Optional : Sets From Email Address - leave blank to use your api username as email sender
    EmailSubject: "Test Email",             // Email Subject
    MessagePlain: "Test Email Body",        // Email Body
    Destinations: [                         // Email Recipients
      { Recipient: "email.one@test.com" },
      { Recipient: "email.two@test.com" }
    ]
}).then(callback); // Send Message 
Send Email (Advanced):

const TNZAPI = require('tnzapi');
const ContactModel = require('tnzapi/lib/Api/Addressbook/Contacts/models/ContactModel');
const GroupModel = require('tnzapi/lib/Api/Addressbook/Groups/models/GroupModel');

const client = new TNZAPI({
    AuthToken: "[Your Auth Token]"          // Auth Token
});

var callback = function(data) {
    console.log("Response: ",JSON.stringify(data, null, "  "));
};

client.Messaging.Email.SendMessage({
  
    MessageID: "ID12345",                           // Your custom MessageID
    Reference: "Test Email - Advanced version",     // Your reference

    SMTPFrom: "email@test.com",                     // Sender SMTP From Address
    From: "Test Email",                             // Sender Email Name
    FromEmail: "from@test.com",                     // Sender Email Address
    ReplyTo: "reply@test.com",                      // Set Reply To

    EmailSubject: "Test Email",                     // Email subject
    MessagePlain: "Test Email Body",                // Email body (plain text)
    MessageHTML: "<html><body><p>This is <b>Test message body</b>. Thank you so much!</p></body></html>",

    Destinations: [                                 // Email Recipients
        {
            Recipient: "email1@test.com",           // Recipient Email Address
            Company: "Test Company",                // Company Name
            Attention: "Test Recipient",            // Attention
            Custom1: "Custom1",                     // Custom Field
            Custom2: "Custom2",
            Custom3: "Custom3",
            Custom4: "Custom4",
            Custom5: "Custom5"
        },
        {
            Recipient: "email2@test.com",           // Recipient Email Address
            Company: "Test Company 2",              // Company Name
            Attention: "Test Recipient 2",          // Attention
            Custom1: "Custom1",                     // Custom Field
            Custom2: "Custom2",
            Custom3: "Custom3",
            Custom4: "Custom4",
            Custom5: "Custom5"
        },
        {
            Group: new GroupModel({
                GroupID: "GGGGGGGG-AAAA-AAAA-AAAA-AAAAAAAAAAAA"
            })
        },
        {
            GroupID: "GGGGGGGG-BBBB-BBBB-BBBB-BBBBBBBBBBBB"
        },
        {
            Contact: new ContactModel({
                ContactID: "CCCCCCCC-AAAA-AAAA-AAAA-AAAAAAAAAAAA",
            })
        },
        {
            ContactID: "CCCCCCCC-BBBB-BBBB-BBBB-BBBBBBBBBBBB"
        }
    ],

    Attachments: [
        "D:\\File1.pdf",
        "D:\\File2.pdf"
    ]
}).then(callback); // Send Message 

Request parameters

Parameter Example Value Description
AuthToken Required eyJhbGciOiJI...adQssw5c Auth Token value set up in Create a new API Auth token
EmailSubject Required Test Email Sets the email subject
MessagePlain Required Hello,

This is a test message.

Thank you.
Content used for the message/plain section of the email (overrides 'Template')
Destinations Required {"Recipient": "john.doe@example.com"} Email address to receive the message (for detailed formatting, see the Destinations parameter below)
MessageID Optional ID12345 A Message Identifier helps you keep track of each message (maximum 40 characters, alphanumeric). Use a unique MessageID for each request. If you leave this field blank, the API will generate a 36-character UUID (v4) for you and include it in the response body.
Reference Optional Test1 Human readable message description (free format field, maximum 80 characters).
SendTime Optional new DateTime() Delay sending until the specified date/time (YYYY-MM-DD HH:mm in your local timezone, specified by your Sender setting or overridden using the TimeZone command)
Timezone Optional New Zealand User's local timezone (see Setting Timezones)
SubAccount Optional SubAccount01 Used for reporting, billing and Web Dashboard segmentation. See the TNZ API Structure guide's Cost Tracking & Rebilling section.
Department Optional Department01 Used for reporting, billing and Web Dashboard segmentation. See the TNZ API Structure guide's Cost Tracking & Rebilling section.
ChargeCode Optional BillingGroup01 Bespoke app cost allocation code (for invoice segmentation)
SMTPFrom Optional noreply@example.com Sets the email Sender/Return-Path at the SMTP level (this address receives bounce-back emails and is used for SPF/DKIM type authentication; 'FromEmail' is used if not specified)
From Optional noreply Sets the email sender's Friendly Name (seen by the email recipient)
FromEmail Optional noreply@example.com Sets the email sender's Email Address (seen by the email recipient; API 'Sender' is used if not specified)
ReplyTo Optional reply@example.com Sets the email sender's Reply-To Address (if the recipient replies, the Reply To will receive the reply)
MessageHTML Optional <html>Hello,<br /><br />This is a test message.<br /><br />Thank you.</html> Content used for the message/html section of the email (overrides 'Template' and 'MessagePlain')
Destinations Optional > Recipient john.doe@example.com Recipient of the email
> Attention John Doe Recipient's friendly name
> Company Example Corp Recipient's company
> Custom1 Customisable field
> Custom2 Customisable field
Attachments Optional > Name Sample.pdf Attachment's filename
> Data %%Base-64%% Base-64 encoded value of the attached file

Sending SMS

Send SMS/TXT via NodeJS

Send SMS (Basic):

const TNZAPI = require('tnzapi');

const client = new TNZAPI({
    AuthToken: "[Your Auth Token]"          // Auth Token
});

var callback = function(data) {
    console.log("Response: ",JSON.stringify(data, null, "  "));
};

client.Messaging.SMS.SendMessage({
    Reference: "Test",                  // Optional
    Message: "Test SMS",                // SMS Message
    Destinations: [                     // SMS Recipients
      { Recipient: "+64211111111" },
      { Recipient: "+64222222222" }
    ]
}).then(callback); // Send Message 
Send SMS (Advanced):

const TNZAPI = require('tnzapi');
const ContactModel = require('tnzapi/lib/Api/Addressbook/Contacts/models/ContactModel');
const GroupModel = require('tnzapi/lib/Api/Addressbook/Groups/models/GroupModel');

const client = new TNZAPI({
    AuthToken: "[Your Auth Token]"          // Auth Token
});

var callback = function(data) {
  console.log("Response: ",JSON.stringify(data, null, "  "));
};

client.Messaging.SMS.SendMessage({

    MessageID: "ID12345",                             // MessageID - Leave blank to auto-generate
    Reference: "Test SMS - Advanced version",         // Reference
    SMSEmailReply: "test@example.com",                // Email address to receive reply back
    CharacterConversion: true,                        //  Convert multi-byte characters into normalised GSM character
    Message: "Test SMS Message for [[Attention]] at [[Company]]. Click [[File1]] | [[File2]] to download files.",                              // SMS Message
    Destinations: [                                   // SMS Recipients
        {
            Recipient: "+64211231234",                // Recipient Mobile Number
            Company: "Test Company",                  // Company Name
            Attention: "Test Recipient",              // Attention
            Custom1: "Custom1",                       // Custom Field
            Custom2: "Custom2",
            Custom3: "Custom3",
            Custom4: "Custom4",
            Custom5: "Custom5"
        },
        {
            Recipient: "+64271231234",                // Recipient Mobile Number
            Company: "Test Company 2",                // Company Name
            Attention: "Test Recipient 2",            // Attention
            Custom1: "Custom1",                       // Custom Field
            Custom2: "Custom2",
            Custom3: "Custom3",
            Custom4: "Custom4",
            Custom5: "Custom5"
        },
        {
            Group: new GroupModel({
                GroupID: "GGGGGGGG-AAAA-AAAA-AAAA-AAAAAAAAAAAA"
            })
        },
        {
            GroupID: "GGGGGGGG-BBBB-BBBB-BBBB-BBBBBBBBBBBB"
        },
        {
            Contact: new ContactModel({
                ContactID: "CCCCCCCC-AAAA-AAAA-AAAA-AAAAAAAAAAAA",
            })
        },
        {
            ContactID: "CCCCCCCC-BBBB-BBBB-BBBB-BBBBBBBBBBBB"
        }
    ],
    Attachments: [
        "D:/File1.pdf",
        "D:/File2.pdf",
    ]
    
}).then(callback); // Send Message 

Request parameters

Parameter Example Value Description
AuthToken Required eyJhbGciOiJI...adQssw5c Auth Token value set up in Create a new API Auth token
Message Required Hello, this is a test message from Department01. Thank you. Plain or UTF-8 formatted SMS message
Destinations Required {"Recipient": "+6421000002"} Mobile number to receive the message (for detailed formatting, see the Destinations parameter below)
MessageID Optional ID12345 A Message Identifier helps you keep track of each message (maximum 40 characters, alphanumeric). Use a unique MessageID for each request. If you leave this field blank, the API will generate a 36-character UUID (v4) for you and include it in the response body.
Reference Optional Test1 Human readable message description (free format field, maximum 80 characters).
SendTime Optional new DateTime() Delay sending until the specified date/time (YYYY-MM-DD HH:mm in your local timezone, specified by your Sender setting or overridden using the TimeZone command)
TimeZone Optional New Zealand User's local timezone (see Setting Timezones)
SubAccount Optional SubAccount01 Used for reporting, billing and Web Dashboard segmentation. See the TNZ API Structure guide's Cost Tracking & Rebilling section.
Department Optional Department01 Used for reporting, billing and Web Dashboard segmentation. See the TNZ API Structure guide's Cost Tracking & Rebilling section.
ChargeCode Optional BillingGroup01 Bespoke app cost allocation code (for invoice segmentation)
FromNumber Optional +6421000001 Setting SMS origination number, short code(s) will override in New Zealand - Not for New Zealand.
SMSEmailReply Optional person.one@domain.com For email (SMTP) reply receipt notifications
CharacterConversion Optional True Convert multi-byte characters into normalised GSM character format. ie. © to (C)
Message Optional Hello, view the link at [[Link:https://www.example.com/path/to/page.html]] or view the file at [[File1]] or reply at [[REPLY]] or OptOut at [[STOP]] An example Message that uses the URL Shortener, File Link, Reply Link and Unsubscribe functions
Destinations Optional > Recipient +6421000001 Recipient of the SMS in E.164 internationalised format (for localized or friendly formatting, contact your account manager)
> Attention John Doe Recipient's friendly name
> Company Example Corp Recipient's company
> Custom1 Customisable field
> Custom2 Customisable field

Sending Faxes

Send Fax via NodeJS

Send Fax (Basic):

const TNZAPI = require('tnzapi');

const client = new TNZAPI({
    AuthToken: "[Your Auth Token]"          // Auth Token
});

var callback = function(data) {
    console.log("Response:",JSON.stringify(data, null, "  "));
};

client.Messaging.Fax.SendMessage({
    Reference: "Test",                      // Optional
    Destinations: [                         // Fax Numbers
        { Recipient:"+6491111111" },
        { Recipient:"+6492222222" }
    ],
    Attachments: [
        "D:/File1.pdf"
    ]         
}).then(callback);
Send Fax (Advanced):

const TNZAPI = require('tnzapi');
const ContactModel = require('tnzapi/lib/Api/Addressbook/Contacts/models/ContactModel');
const GroupModel = require('tnzapi/lib/Api/Addressbook/Groups/models/GroupModel');

const client = new TNZAPI({
    AuthToken: "[Your Auth Token]"          // Auth Token
});

var callback = function(data) {
  console.log("Response:",JSON.stringify(data, null, "  "));
};

client.Messaging.Fax.SendMessage({
    MessageID: "ID12345",                         // MessageID - Leave blank to auto-generate
    Reference: "Test Fax - Advanced version",     // Reference

    Resolution: "High",                           // Resolution - High/Low
    CSID: "TEST FAX",                             // CSID

    RetryAttempts: 3,                             // RetryAttempts - no of retries
    RetryPeriod: 1,                               // RetryPeriod - no of minutes between retries

    Destinations: [
        {
            Recipient: "+6491231234",             // Fax number
            Company: "Test Company",              // Company Name
            Attention: "Test Recipient",          // Attention
            Custom1: "Custom1",                   // Custom Field
            Custom2: "Custom2",
            Custom3: "Custom3",
            Custom4: "Custom4",
            Custom5: "Custom5"
        },
        {
            Recipient: "+6471231234",             // Fax number
            Company: "Test Company 2",            // Company Name
            Attention: "Test Recipient",          // Attention
            Custom1: "Custom1",                   // Custom Field
            Custom2: "Custom2",
            Custom3: "Custom3",
            Custom4: "Custom4",
            Custom5: "Custom5"
        },
        {
            Group: new GroupModel({
                GroupID: "GGGGGGGG-AAAA-AAAA-AAAA-AAAAAAAAAAAA"
            })
        },
        {
            GroupID: "GGGGGGGG-BBBB-BBBB-BBBB-BBBBBBBBBBBB"
        },
        {
            Contact: new ContactModel({
                ContactID: "CCCCCCCC-AAAA-AAAA-AAAA-AAAAAAAAAAAA",
            })
        },
        {
            ContactID: "CCCCCCCC-BBBB-BBBB-BBBB-BBBBBBBBBBBB"
        }
    ],

    Attachments: [
        "D:\\File1.pdf",
        "D:\\File2.pdf"
    ]
}).then(callback);

Request parameters

Parameter Example Value Description
AuthToken Required eyJhbGciOiJI...adQssw5c Auth Token value set up in Create a new API Auth token
Destinations Required {"Recipient": "+6495005001"} Fax number(s) to receive the message (for detailed formatting, see the Destinations parameter below)
Attachments Required > Name Sample.pdf Fax document's filename
> Data %%Base-64%% Base-64 encoded value of the document
MessageID Optional ID12345 A Message Identifier helps you keep track of each message (maximum 40 characters, alphanumeric). Use a unique MessageID for each request. If you leave this field blank, the API will generate a 36-character UUID (v4) for you and include it in the response body.
Reference Optional Test1 Human readable message description (free format field, maximum 80 characters).
SendTime Optional new DateTime() Delay sending until the specified date/time (YYYY-MM-DD HH:mm in your local timezone, specified by your Sender setting or overridden using the TimeZone command)
Timezone Optional New Zealand User's local timezone (see Setting Timezones)
SubAccount Optional SubAccount01 Used for reporting, billing and Web Dashboard segmentation. See the TNZ API Structure guide's Cost Tracking & Rebilling section.
Department Optional Department01 Used for reporting, billing and Web Dashboard segmentation. See the TNZ API Structure guide's Cost Tracking & Rebilling section.
ChargeCode Optional BillingGroup01 Bespoke app cost allocation code (for invoice segmentation)
WatermarkFolder Optional Folder01 Directory/location of Watermark file to use
WatermarkFirstPage Optional Watermark File Name Watermark file to apply to the first page only
WatermarkAllPages Optional Watermark File Name Watermark file to apply to all pages
Resolution Optional High Quality of the fax image. High for better quality, low for lower quality (faster delivery speed)
CSID Optional Station ID Called Subscriber Identification - Maximum 30 characters
RetryAttempts Optional 3 Number of retries (retry_period required)
RetryPeriod Optional 1 Minutes between retries (retry_attempts required)
Destinations Optional > Recipient +6495005000 Recipient of the Fax in E.164 internationalised format (for localized or friendly formatting, contact your account manager)
> Attention John Doe Recipient's friendly name
> Company Example Corp Recipient's company
> Custom1 Customisable field
> Custom2 Customisable field

Sending Voice (Voicemail)

Send VoiceCast via NodeJS

Send Voice (Basic):

const TNZAPI = require('tnzapi');

const client = new TNZAPI({
    AuthToken: "[Your Auth Token]"          // Auth Token
});

var callback = function(data) {
  console.log("Response:",JSON.stringify(data, null, "  "));
};

client.Messaging.Voice.SendMessage({

    Destinations: [                         // Phone numbers to call
        { Recipient: "+6491111111" },
        { Recipient: "+6492222222" }
    ],

    // Message to play - WAV format, 16-bit, 8000hz recommended
    VoiceFiles: [
        {
            Name: "MessageToPeople",
            File: "D:/File1.wav"
        }
    ]

}).then(callback);
Send Voice (Advanced):

const TNZAPI = require('tnzapi');
const ContactModel = require('tnzapi/lib/Api/Addressbook/Contacts/models/ContactModel');
const GroupModel = require('tnzapi/lib/Api/Addressbook/Groups/models/GroupModel');

const client = new TNZAPI({
    AuthToken: "[Your Auth Token]"          // Auth Token
});

var callback = function(data) {
  console.log("Response:",JSON.stringify(data, null, "  "));
};

client.Messaging.Voice.SendMessage({

    MessageID: "ID12345",                             // MessageID - Leave blank to auto-generate
    Reference: "Test Voice - Advanced version",       // Reference

    CallerID: "+6499999999",                          // Caller ID
    BillingAccount: "TEST BILLING ACCOUNT",           // Billing Account (Sub Account)
    ReportTo: "report@example.com",                   // Email address to receive reports

    NumberOfOperators: 5,                             // No of Operators - Limits the maximum simultaneous calls
    RetryAttempts: 3,                                 // No of retries
    RetryPeriod: 1,                                   // Period between retries (minutes)

    // Message to play - WAV format, 16-bit, 8000hz recommended
    VoiceFiles: [
        {
            // Message to play when call answered - WAV format, 16-bit, 8000hz recommended
            Name: "MessageToPeople",
            File: "D:/message-to-people.wav"
        },
        {
            // Message to play when answerphone detected - WAV format, 16-bit, 8000hz recommended
            Name: "MessageToAnswerPhones",
            File: "D:/message-to-answerphones.wav"
        },
        {
            // Message to play when a keypad option is pressed - WAV format, 16-bit, 8000hz recommended
            Name: "CallRouteMessageToPeople",
            File: "D:/call-route-message-to-people.wav"
        },
        {
            // Message to play when a all centre representative answering the connected call - WAV format, 16-bit, 8000hz recommended
            Name: "CallRouteMessageToOperators",
            File: "D:/call-route-message-to-operators.wav"
        },
        {
            // Message to play when an unregistered keypad button is pressed - WAV format, 16-bit, 8000hz recommended
            Name: "CallRouteMessageOnWrongKey",
            File: "D:/call-route-message-on-wrong-key.wav"
        },
    ],

    // Adding Keypad options - WAV format, 16-bit, 8000hz recommended
    Keypads: [
        {
            Tone: 1,                                  // Keypad Tone
            RouteNumber: "+6491111111",               // Connect call to
            File: "D:/key1-play-message.wav"          // Message to play to caller
        },
        {
            Tone: 2,                                  // Keypad Tone
            RouteNumber: "+6492222222",               // Connect call to
        }
    ],

    Destinations: [                                   // Phone numbers to call
        { "Recipient": "+6491111111" },
        { "Recipient": "+6492222222" },
        {
            Group: new GroupModel({
                GroupID: "GGGGGGGG-AAAA-AAAA-AAAA-AAAAAAAAAAAA"
            })
        },
        {
            GroupID: "GGGGGGGG-BBBB-BBBB-BBBB-BBBBBBBBBBBB"
        },
        {
            Contact: new ContactModel({
                ContactID: "CCCCCCCC-AAAA-AAAA-AAAA-AAAAAAAAAAAA",
            })
        },
        {
            ContactID: "CCCCCCCC-BBBB-BBBB-BBBB-BBBBBBBBBBBB"
        }
    ]


}).then(callback);

Request parameters

Parameter Example Value Description
AuthToken Required eyJhbGciOiJI...adQssw5c Auth Token value set up in Create a new API Auth token
MessageToPeople Required [Base64encoded data] The audio data played if the call is answered by a human (WAV format, 16-bit, 8000hz)
Destinations Required {"Recipient": "+6495005001"} Telephone number(s) to receive the message (for detailed formatting, see the Destinations parameter below)
MessageID Optional ID12345 A Message Identifier helps you keep track of each message (maximum 40 characters, alphanumeric). Use a unique MessageID for each request. If you leave this field blank, the API will generate a 36-character UUID (v4) for you and include it in the response body.
Reference Optional Test1 Human readable message description (free format field, maximum 80 characters).
SendTime Optional new DateTime() Delay sending until the specified date/time (YYYY-MM-DD HH:mm in your local timezone, specified by your Sender setting or overridden using the TimeZone command)
Timezone Optional New Zealand User's local timezone (see Setting Timezones)
BillingAccount Optional BillingAccount01 Used for reporting, billing and Web Dashboard segmentation (called SubAccount). See the TNZ API Structure guide's Cost Tracking & Rebilling section.
Department Optional Department01 Used for reporting, billing and Web Dashboard segmentation. See the TNZ API Structure guide's Cost Tracking & Rebilling section.
ChargeCode Optional BillingGroup01 Bespoke app cost allocation code (for invoice segmentation)
ReportTo Optional report@example.com For email (SMTP) message delivery report notifications.
MessageToAnswerphones Optional [Base64encoded data] The audio data played when the call is answered by an answering machine/voicemail service (WAV format, 16-bit, 8000hz)
Keypads Optional > Tone 1 Keypad for call connection (supports buttons 1-9)
> RouteNumber +64800123123 Telephone number for call routing in dialling format
> PlayFile C:\Message.wav Audio file played to B-Party when a keypad option is pressed (WAV format, 16-bit, 8000hz), eg "Thank you. You have pressed keypad 1."
CallRouteMessageToPeople Optional [Base64encoded data] Audio data played when a keypad option is pressed (WAV format, 16-bit, 8000hz), eg "Connecting you now."
CallRouteMessageToOperators Optional [Base64encoded data] Audio data played to the call centre representative answering the connected call (WAV format, 16-bit, 8000hz), eg "Incoming Text To Speech call."
CallRouteMessageOnWrongKey Optional [Base64encoded data] Audio data played when an unregistered keypad button is pressed (WAV format, 16-bit, 8000hz), eg "Sorry, you have pressed an invalid key. Please try again"
NumberOfOperators Optional 5 Limits the maximum simultaneous calls (where multiple 'Destinations' are listed)
RetryAttempts Optional 3 Number of retry attempts if the recipients line is busy or unavailable
RetryPeriod Optional 1 Minutes apart when performing retries
CallerID Optional +6495005000 Sets the Caller ID used on the call (must be E.164 format)
Options Optional Customisable field that allows advanced voice options including recording survey responses, recording phone numbers, playing IVR options, capturing DTMF tones for account numbers or credit card numbers, etc.
Destinations Optional > Recipient +6495005000 Recipient of the call in E.164 internationalised format (for localized or friendly formatting, contact your account manager)
> Custom1 Customisable field
> Custom2 Customisable field
> Custom3 Customisable field
> Custom4 Customisable field
VoiceFiles Optional > Name MessageToPeople Type of message for the voice file - Available values are:
- MessageToPeople
- MessageToAnswerPhones
- CallRouteMessageToPeople
- CallRouteMessageToOperators
- CallRouteMessageOnWrongKey
> File D:/Sample.wav Local path to your voice file

Sending Voice Text To Speech

Send TTS Calls via NodeJS

Send TextToSpeech (Basic):

const TNZAPI = require('tnzapi');

const client = new TNZAPI({
    AuthToken: "[Your Auth Token]"          // Auth Token
});

var callback = function(data) {
  console.log("Response:",JSON.stringify(data, null, "  "));
}

client.Messaging.TTS.SendMessage({
    MessageToPeople: "Hi there!",               // Message to play
    Destinations: [                             // Recipients
        { Recipient: "+6491111111" },
        { Recipient: "+6492222222" }
    ]
}).then(callback);
Send TextToSpeech (Advanced):

const TNZAPI = require('tnzapi');
const ContactModel = require('tnzapi/lib/Api/Addressbook/Contacts/models/ContactModel');
const GroupModel = require('tnzapi/lib/Api/Addressbook/Groups/models/GroupModel');

const client = new TNZAPI({
    AuthToken: "[Your Auth Token]"          // Auth Token
});

var callback = function(data) {
  console.log("Response:",JSON.stringify(data, null, "  "));
};

client.Messaging.TTS.SendMessage({

    MessageID: "ID12345",                             // MessageID - Leave blank to auto-generate
    Reference: "Test TTS - Advanced version",         // Reference

    CallerID: "+6499999999",                          // Caller ID
    BillingAccount: "TEST BILLING ACCOUNT",           // Billing Account (Sub Account)
    ReportTo: "report@example.com",                   // Email address to receive reports

    NumberOfOperators: 10,                            // No of Operators - Limits the maximum simultaneous calls
    RetryAttempts: 3,                                 // No of retries
    RetryPeriod: 1,                                   // Period between retries (minutes)

    TTSVoiceType: "English-NewZealand@Female1",       // TTS Voice Engine

    // Message to play when call answered
    MessageToPeople: "Hello, this is a call from Department01. This is relevant information. Press one to be connected to our call centre.",

    // Message to play when answerphone detected (optional)
    MessageToAnswerPhones: "Hello, sorry we missed you. This is a call from Department 01. Please contact us on 0800 123123.",

    // Message to play when a keypad option is pressed (optional)
    CallRouteMessageToPeople: "Connecting you now.",

    // Message to play when a all centre representative answering the connected call
    CallRouteMessageToOperators: "Incoming Text To Speech call.",

    // Message to play when an unregistered keypad button is pressed
    CallRouteMessageOnWrongKey: "Sorry, you have pressed an invalid key. Please try again.",

    Keypads: [
      {
          Tone: 1,                                    // Keypad Tone
          RouteNumber: "+6491111111",                 // Connect call to
      },
      {
          Tone: 2,                                    // Keypad Tone
          Play: "You pressed 2",                      // Message to play to caller
          RouteNumber: "+6492222222",                 // Connect call to
      }
    ],

    Destinations: [
        {
            "Recipient": "+64211111111",              // Recipient Phone Number
            "Company": "Company 1",                   // Company
            "Attention": "Person 1",                  // Attention
            "Custom1": "Custom1",                     // Custom Field
            "Custom2": "Custom2", 
            "Custom3": "Custom3", 
            "Custom4": "Custom4"  
        },  
        { 
            "Recipient": "+64212222222",              // Recipient Phone Number
            "Company": "Company 2",                   // Company
            "Attention": "Person 2",                  // Attention
            "Custom1": "Custom1",                     // Custom Field
            "Custom2": "Custom2",
            "Custom3": "Custom3",
            "Custom4": "Custom4"
        },
        {
            Group: new GroupModel({
                GroupID: "GGGGGGGG-AAAA-AAAA-AAAA-AAAAAAAAAAAA"
            })
        },
        {
            GroupID: "GGGGGGGG-BBBB-BBBB-BBBB-BBBBBBBBBBBB"
        },
        {
            Contact: new ContactModel({
                ContactID: "CCCCCCCC-AAAA-AAAA-AAAA-AAAAAAAAAAAA",
            })
        },
        {
            ContactID: "CCCCCCCC-BBBB-BBBB-BBBB-BBBBBBBBBBBB"
        }
    ]

}).then(callback);

Request parameters

Parameter Example Value Description
AuthToken Required eyJhbGciOiJI...adQssw5c Auth Token value set up in Create a new API Auth token
MessageToPeople Required Hello, this is a call from Department01. This is relevant information. Press one to be connected to our call centre. The text-to-speech message played if the call is answered by a human (may optionally include SSML commands)
Destinations Required {"Recipient": "+6495005001"} Telephone number(s) to receive the message (for detailed formatting, see the Destinations parameter below)
MessageID Optional ID12345 A Message Identifier helps you keep track of each message (maximum 40 characters, alphanumeric). Use a unique MessageID for each request. If you leave this field blank, the API will generate a 36-character UUID (v4) for you and include it in the response body.
Reference Optional Test1 Human readable message description (free format field, maximum 80 characters).
SendTime Optional new DateTime() Delay sending until the specified date/time (YYYY-MM-DD HH:mm in your local timezone, specified by your Sender setting or overridden using the TimeZone command)
Timezone Optional New Zealand User's local timezone (see Setting Timezones)
SubAccount Optional SubAccount01 Used for reporting, billing and Web Dashboard segmentation. See the TNZ API Structure guide's Cost Tracking & Rebilling section.
Department Optional Department01 Used for reporting, billing and Web Dashboard segmentation. See the TNZ API Structure guide's Cost Tracking & Rebilling section.
ChargeCode Optional BillingGroup01 Bespoke app cost allocation code (for invoice segmentation)
ReportTo Optional report@example.com For email (SMTP) message delivery report notifications.
MessageToAnswerphones Optional Hello, sorry we missed you. This is a call from Department 01. Please contact us on 0800 123123. The text-to-speech message played when the call is answered by an answering machine/voicemail service (may optionally include SSML commands)
Keypads Optional > Tone 1 Keypad for call connection (supports buttons 1-9)
> RouteNumber +64800123123 Telephone number for call routing in dialling format
> Play You pressed Keypad 1 Message played to B-Party when a keypad option is pressed
CallRouteMessageToPeople Optional Connecting you now. Text-to-speech message played when a keypad option is pressed
CallRouteMessageToOperators Optional Incoming Text To Speech call. Text-to-speech message played to the call centre representative answering the connected call
CallRouteMessageOnWrongKey Optional Sorry, you have pressed an invalid key. Please try again. Text-to-speech message played when an unregistered keypad button is pressed
NumberOfOperators Optional 5 Limits the maximum simultaneous calls (where multiple 'Recipients' are listed)
RetryAttempts Optional 3 Number of retry attempts if the recipients line is busy or unavailable
RetryPeriod Optional 1 Minutes apart when performing retries
CallerID Optional 6495005000 Sets the Caller ID used on the call (must be E.164 format)
TTSVoiceType Optional Female1 Text-to-Speech voice to use (Male1, Female1, Nicole, Russell, Amy, Brian, Emma)
Options Optional Customisable field that allows advanced voice options including recording survey responses, recording phone numbers, playing IVR options, capturing DTMF tones for account numbers or credit card numbers, etc.
Destinations Optional > Recipient +6495005000 Recipient of the call in E.164 internationalised format (for localized or friendly formatting, contact your account manager)
> Attention John Doe Recipient's friendly name
> Company Example Corp Recipient's company
> Custom1 Customisable field
> Custom2 Customisable field

Sending messages in test mode

Under request object you can specify an additional Mode=Test parameter.

Mode=Test means any messages will be handled by the API, instantly called a SUCCESS and the success report will be delivered to you. This is a useful way to end-to-end test without sending a live message.


# Test mode
request.Mode = "Test"
                                              

Edit Messages

Edit a submitted message

Once a message has been sent, you can retry a failed message, reschedule a delayed message, abort a delayed message and edit the NumberOfOperators value on Voice/TTS messages.

Retry Sending

Resubmit a failed message

If your message is 'Failed' (sending completed and was unsuccessful), you can use this API module to retry sending.

The Retry is applied to a specific MessageID. If you use common MessageID values across multiple messages, it will apply to the most recent message and only if the Status was Failed.

Set Resubmit: (Basic)

const TNZAPI = require('tnzapi');

const client = new TNZAPI({
    AuthToken: "[Your Auth Token]"          // Auth Token
});

var callback = function(data) {
    console.log("Response:",JSON.stringify(data, null, "  "));
}

client.Actions.Resubmit.SendRequest({
    MessageID: "ID123456",                   // MessageID generated from system OR your message ID if specified
}).then(callback);
Set Resubmit: (Advanced)

const TNZAPI = require('tnzapi');

const client = new TNZAPI({
    AuthToken: "[Your Auth Token]"          // Auth Token
});

var callback = function(data) {
    console.log("Response:",JSON.stringify(data, null, "  "));
}

client.Actions.Resubmit.SendRequest({
    MessageID: "ID123456",                   // MessageID generated from system OR your message ID if specified
    SendTime: "2023-09-01T12:30"
}).then(callback);

ResubmitRequest parameters

Parameter Example Value Description
AuthToken Required eyJhbGciOiJI...adQssw5c Auth Token value set up in Create a new API Auth token
MessageID Required ID123456 MessageID the Action should apply to

ResubmitRequestResult object parameters

Parameter Example Value Description
Result Success Result of your API call (not the result of the message)
Status Transmit Current Status of your message
JobNum ABCD1234 Your Job Number
Action Resubmit What action (Resubmit) was requested
ErrorMessage ["Missing Sender"] Reason for the API call failure (see a list of possible values: TNZ API Errors)

Reschedule Sending

Adjust the Delayed Sending Date/Time

If you have an existing Delayed message (scheduled for sending at a future date/time), you can use this API module to adjust the sending date/time.

The adjustment is applied to a specific MessageID. If you use common MessageID values across multiple messages, it will apply to the most recent message.

Set Reschedule: (Basic)

const TNZAPI = require('tnzapi');

const client = new TNZAPI({
    AuthToken: "[Your Auth Token]"          // Auth Token
});

var callback = function(data) {
  console.log("Response:",JSON.stringify(data, null, "  "));
}

client.Actions.Reschedule.SendRequest({
    MessageID: "ID123456",                  // MessageID generated from system OR your message ID if specified
    SendTime: "2023-09-01T00:00"            // New Date/Time
}).then(callback);
Set Reschedule: (Advanced)

const TNZAPI = require('tnzapi');

const client = new TNZAPI({
    AuthToken: "[Your Auth Token]"          // Auth Token
});

var callback = function(data) {
  console.log("Response:",JSON.stringify(data, null, "  "));
}

client.Actions.Reschedule.SendRequest({
    MessageID: "ID123456",                  // MessageID generated from system OR your message ID if specified
    SendTime: "2023-09-01T00:00"            // New Date/Time
}).then(callback);

RescheduleRequest parameters

Parameter Example Value Description
AuthToken Required eyJhbGciOiJI...adQssw5c Auth Token value set up in Create a new API Auth token
MessageID Required ID123456 MessageID the Action should apply to
SendTime Required 2020-05-12 14:05:00 Reschedule sending for the specified date/time (YYYY-MM-DD HH:mm in your Account/Sender's default timezone setting)

RescheduleRequestResult object parameters

Parameter Example Value Description
Result Success Result of your API call (not the result of the message)
Status Delayed Current Status of your message
JobNum ABCD1234 Your Job Number
Action Reschedule What action (Reschedule) was requested
ErrorMessage ["Missing Sender"] Reason for the API call failure (see a list of possible values: TNZ API Errors)

Abort Sending

Cancel/Delete a Message from the Queue

If you have an existing Delayed message (scheduled for sending at a future date/time) you can use this API module to Cancel sending of the message.

The cancellation is applied to a specific MessageID. If you use common MessageID values across multiple messages, it will apply to the most recent message.

Set Abort: (Basic)

const TNZAPI = require('tnzapi');

const client = new TNZAPI({
    AuthToken: "[Your Auth Token]"          // Auth Token
});

var callback = function(data) {
  console.log("Response:",JSON.stringify(data, null, "  "));
}

client.Actions.Abort.SendRequest({
    MessageID: "ID123456"                     // MessageID generated from system OR your message ID if specified
}).then(callback);

Set Abort: (Advanced)

const TNZAPI = require('tnzapi');

const client = new TNZAPI({
    AuthToken: "[Your Auth Token]"          // Auth Token
});

var callback = function(data) {
  console.log("Response:",JSON.stringify(data, null, "  "));
}

client.Actions.Abort.SendRequest({
    MessageID: "ID123456"                     // MessageID generated from system OR your message ID if specified
}).then(callback);

AbortRequest parameters

Parameter Example Value Description
AuthToken Required eyJhbGciOiJI...adQssw5c Auth Token value set up in Create a new API Auth token
MessageID Required ID123456 MessageID the Action should apply to

AbortRequestResult object parameters

Parameter Example Value Description
Result Success Result of your API call (not the result of the message)
Status Pending Current Status of your message
JobNum ABCD1234 Your Job Number
Action Abort What action (Abort) was requested
ErrorMessage ["Missing Sender"] Reason for the API call failure (see a list of possible values: TNZ API Errors)

Adjust NumberOfOperators

Change the Voice/Text-to-Speech NumberOfOperators Value

When sending a Voice/Text-to-Speech message, you may specify the NumberOfOperators value (limits the quantity of simultaneous/concurrent calls). You can use this API module to adjust the NumberOfOperators value in real-time.

The cancellation is applied to a specific MessageID. If you use common MessageID values across multiple messages, it will apply to the most recent message.

Change NumberOfOperators: (Basic)

const TNZAPI = require('tnzapi');

const client = new TNZAPI({
    AuthToken: "[Your Auth Token]"          // Auth Token
});

var callback = function(data) {
  console.log("Response:",JSON.stringify(data, null, "  "));
}

client.Actions.Pacing.SendRequest({
    MessageID: "ID123456",                    // MessageID generated from system OR your message ID if specified
    NumberOfOperators: 1                      // No of operators
}).then(callback);
Change NumberOfOperators: (Advanced)

const TNZAPI = require('tnzapi');

const client = new TNZAPI({
    AuthToken: "[Your Auth Token]"          // Auth Token
});

var callback = function(data) {
  console.log("Response:",JSON.stringify(data, null, "  "));
}

client.Actions.Pacing.SendRequest({
    MessageID: "ID123456",                    // MessageID generated from system OR your message ID if specified
    NumberOfOperators: 1                      // No of operators
}).then(callback);

PacingRequest parameters

Parameter Example Value Description
AuthToken Required eyJhbGciOiJI...adQssw5c Auth Token value set up in Create a new API Auth token
MessageID Required ID123456 MessageID the Action should apply to
NumberOfOperators Required 4 NumberOfOperators value to apply

PacingRequestResult object parameters

Parameter Example Value Description
Result Success Result of your API call (not the result of the message)
Status Pending Current Status of your message
JobNum ABCD1234 Your Job Number
Action Pacing What action (Pacing) was requested
ErrorMessage ["Missing Sender"] Reason for the API call failure (see a list of possible values: TNZ API Errors)

Status Reporting

Reporting and event tracking

Delivery Reports advise whether delivery was successful. If not, it will describe why.

Each delivery report type is optional and multiple delivery report types can be used.

Web Dashboard

Tracking message statuses via the online dashboard

You will be supplied with a Web Dashboard login at registration. The Dashboard can be used to set up new sender/token pairs, as well as track sent and replied messages. You can drill into specific messages to view individual events, such as delivery attempts, retries, replies, results, clicks, etc.

SMTP Email

Receive message statuses via email

Delivery reports are emailed as an HTML email for viewing by an end-user. Your sales representative can enable this for you.

Whitelabelling of SMTP Email reports is available.

The email address to receive SMS Reply reports can be specified on the original message submission using the SMSEmailReply parameter.

Webhook

Message statuses delivered via a webhook

If you are set up to receive Status webhooks, you will also be receiving SMS Received webhooks.

To receive Delivery Reports via Webhook, please advise the URL to submit to.

Webhooks are delivered as an HTTP POST in either XML or JSON format (your preference).
Webhook failures are retried every five minutes for a maximum of 24 hours.

Supplied parameters are:

Parameter Example Value Description
AuthToken eyJhbGciOiJI...adQssw5c Auth Token value set up in Create a new API Auth token
Type SMS Type of Message ('Email', 'SMS', 'Fax', 'Voice' or 'TextToSpeech')
Destination +6421000001 Destination that the webhook is for (alphanumeric field, where telephone/mobile numbers are supplied in E.164 internationalised format)
MessageID js82hn8n MessageID parameter supplied when sending your original API call
SubAccount SubAccount01 Used for reporting, billing and Web Dashboard segmentation
Department Department01 Used for reporting, billing and Web Dashboard segmentation
JobNumber 10C7B9A0 Eight digit alphanumeric tracking number (our internal Job Number)
SentTime 16/10/2018 13:43 p.m. Time message was completed (Sender's local time time in 'YYYY-MM-DD HH:mm tt' format)
Status SUCCESS For submission results, values are SUCCESS, FAILED, PENDING
For reply reports, this will be RECEIVED
For additional analytics, this will be UPDATED
Result Sent OK Final delivery result and/or the cause for a message delivery failure
For a list of possible values, see SMS, Fax, Voice, TextToSpeech
Email result codes are defined by the receiving email server
For reply reports, this will be RECEIVED
For additional analytics, this will be the event description
Message Field will be blank; it is used by the Receive Messages webhook only
Price 0.20 Your cost for this transaction, charged by us to you
Detail SMSParts:2 Additional billing detail: "SMSParts", "FaxPages", "VoiceMinutes", "Size", "Prompts"
URL https://www.example.com/webhook The URL this webhook is sent to
RESPONSEMODE JSON This webhook's format

GET Status Poll

Track message statuses using a GET poll

You are able to poll for the status of a message via the GET Status API.

The Poll should be configured to timeout after 48 hours with no result.

Reference : TNZAPI.Messaging.Get

Get Status: (Basic)

const TNZAPI = require('tnzapi');

const client = new TNZAPI({
    AuthToken: "[Your Auth Token]"          // Auth Token
});

var callback = function(data) {
  console.log("Response:",JSON.stringify(data, null, "  "));
}

client.Reports.Status.Poll({
    MessageID: "ID123456",                    // MessageID generated from system OR your message ID if specified
}).then(callback);

Get Status: (Advanced)

const TNZAPI = require('tnzapi');

const client = new TNZAPI({
    AuthToken: "[Your Auth Token]"          // Auth Token
});

var callback = function(data) {
  console.log("Response:",JSON.stringify(data, null, "  "));
}

client.Reports.Status.Poll({
    MessageID: "ID123456",                    // MessageID generated from system OR your message ID if specified
    RecordsPerPage: 10,                       // x number of records
    Page: 1                                   // Current location
}).then(callback);

Request parameters

Parameter Example Value Description
AuthToken Required eyJhbGciOiJI...adQssw5c Auth Token value set up in Create a new API Auth token
MessageID Required ID123456 Your provided Message ID or TNZ Group generated Message ID

Receive Messages

Track messages received

Currently, tracking SMS Received is supported.

Tracking of faxes and voicemail received is scheduled for a future release. Let your account manager know if this interests you.

Web Dashboard

Tracking messages received via the online dashboard

You will be supplied with a Web Dashboard login at registration. The Dashboard can be used to set up new sender/token pairs, as well as track sent and replied messages. You can drill into specific messages to view individual events, such as delivery attempts, retries, replies, results, clicks, etc.

SMTP Email

Track messages received via email

Delivery reports are emailed as an HTML email for viewing by an end-user. Your sales representative can enable this for you.
Whitelabelling of SMTP Email reports is available.

When submitting SMS messages, specify the SMSEmailReply parameter.

Webhook

Messages received data delivered via a webhook

If you are set up to receive Status webhooks, you will also be receiving SMS Received webhooks.

To receive SMS replies via Webhook, please advise the URL to submit to.

Webhooks are delivered as an HTTP POST in either XML or JSON format (your preference).
Webhook failures are retried every five minutes for a maximum of 24 hours.

The mobile has 7 days to reply to a message. Any replies received after the 7 day window will be treated as a new message.

Supplied parameters are:

Parameter Example Value Description
AuthToken eyJhbGciOiJI...adQssw5c Auth Token value set up in Create a new API Auth token
Type SMSReply Type of Message ('Email', 'SMS', 'Fax', 'Voice', 'TextToSpeech', 'SMSInbound' or 'SMSReply')
Destination +6421000001 Mobile number sending the SMS message (alphanumeric field, where telephone/mobile numbers are supplied in E.164 internationalised format)
MessageID js82hn8n MessageID parameter supplied when sending your original API call
SubAccount SubAccount01 Used for reporting, billing and Web Dashboard segmentation
Department Department01 Used for reporting, billing and Web Dashboard segmentation
JobNumber 10C7B9A0 Eight digit alphanumeric tracking number (our internal Job Number)
SentTime 16/10/2018 13:43 p.m. Time reply message was received
Status RECEIVED For submission results, values are SUCCESS, FAILED, PENDING
For reply reports, this will be RECEIVED
For additional analytics, this will be UPDATED
Result RECEIVED Final delivery result and/or the cause for a message delivery failure
For reply reports, this will be RECEIVED
For additional analytics, this will be the event description
Message This is a reply. The received SMS message (if 'Type=SMSInbound' or 'Type=SMSReply')
Price 0.20 Your cost for the outbound message sent, charged by us to you (no cost for the reply received)
Detail SMSParts:2 Additional billing detail: "SMSParts", "FaxPages", "VoiceMinutes", "Size", "Prompts" on the outbound message sent (not the SMS Received)
URL https://www.example.com/webhook The URL this webhook is sent to
RESPONSEMODE JSON This webhook's format

GET SMS Received Poll

Track SMS Received using a GET poll

You are able to poll for all received SMS messages in a given time-frame.

The Poll should be configured to timeout after 48 hours with no result.

Reference : TNZAPI.Messaging.Get

Get SMS Received: (Basic)

const TNZAPI = require('tnzapi');

const client = new TNZAPI({
    AuthToken: "[Your Auth Token]"          // Auth Token
});

var callback = function(data) {
  console.log("Response:",JSON.stringify(data, null, "  "));
}

client.Reports.SMSReceived.Poll({
    TimePeriod: 1440                          // Return results from the last x minutes
    RecordsPerPage: 10,
    Page: 1
}).then(callback);
Get SMS Received: (Advanced)

const TNZAPI = require('tnzapi');

const client = new TNZAPI({
    AuthToken: "[Your Auth Token]"          // Auth Token
});

var callback = function(data) {
  console.log("Response:",JSON.stringify(data, null, "  "));
}

client.Reports.SMSReceived.Poll({
    DateFrom: "2023-06-01T00:00:00",          // Return results from the date/time
    DateTo: "2023-06-30T23:59:59",            // Return results to the date/time
    RecordsPerPage: 10,                       // x numbers of records to return per request
    Page: 1                                   // current location
}).then(callback);

Request parameters

Parameter Example Value Description
AuthToken Required eyJhbGciOiJI...adQssw5c Auth Token value set up in Create a new API Auth token
TimePeriod Required 1440 Return results from the last x minutes
DateFrom Required 2022-08-01T00:00:00 Return results from the specified date (optional)
DateTo Required 2022-08-01T23:59:59 Return results to the specified date (optional)
RecordsPerPage Required 20 Return x number of records per request (optional)
Page Required 1 Current location of the result set (optional)

SMSReceivedResult object parameters

Parameter Example Value Description
Result Success Result of your API call (not the result of the message)
ReceivedMessages SMSReceivedMessage List of SMS messages received
ErrorMessage ["Missing Sender"] Reason for the API call failure (see a list of possible values: TNZ API Errors)

SMSReceivedMessage object parameters

Parameter Example Value Description
Date 2019-12-01 14:02:03 Date/Time SMS was received (yyyy-mm-dd HH:mm:ss)
From +6421000001 Sender of the SMS in E.164 internationalised format
MessageText This is a reply back from the mobile phone. The SMS message received

GET SMS Reply Poll

Track SMS replies using a GET poll

You are able to poll for replies to a specific SMS message, tracked using the MessageID on the outbound message.

The Poll should be configured to timeout after 48 hours with no result.

Reference : TNZAPI.Messaging.Get

Get SMS Reply: (Basic)

const TNZAPI = require('tnzapi');

const client = new TNZAPI({
    AuthToken: "[Your Auth Token]"          // Auth Token
});

request.Poll(callback);

var callback = function(data) {
  console.log("Response:",JSON.stringify(data, null, "  "));
}

client.Reports.SMSReply.Poll({
    MessageID: "ID123456",                    // MessageID generated from system OR your message ID if specified
    Page: 1                                   // Current location
}).then(callback);
Get SMS Reply: (Advanced)

const TNZAPI = require('tnzapi');

const client = new TNZAPI({
    AuthToken: "[Your Auth Token]"          // Auth Token
});

var callback = function(data) {
  console.log("Response:",JSON.stringify(data, null, "  "));
}

client.Reports.SMSReply.Poll({
    MessageID: "ID123456",                    // MessageID generated from system OR your message ID if specified
    RecordsPerPage: 10,                       // x number of records per page
    Page: 1                                   // Current location
}).then(callback);

Request parameters

Parameter Example Value Description
AuthToken Required eyJhbGciOiJI...adQssw5c Auth Token value set up in Create a new API Auth token
MessageID Required ID123456 Your provided Message ID or TNZ Group generated Message ID

SMSReceivedResult object parameters

Parameter Example Value Description
Result Success Result of your API call (not the result of the message)
Status Received Status of your job
MessageID AAAAAAAA-BBBB-BBBB-CCCC-DDDDDDDDDDDD Your provided Message ID or TNZ Group generated Message ID
JobNum 10AB20CE Eight digit alphanumeric tracking number (our internal Job Number)
Account 102030 Your TNZ Account
SubAccount Your supplied TNZ SubAccount
Department Your supplied TNZ Department
SentMessage SMSSentMessage Object Details of your sent message
ReceivedMessages SMSReceivedMessage Objects Details of your received message(s)
ErrorMessage ["Missing Sender"] Reason for the API call failure (see a list of possible values: TNZ API Errors)

SMSSentMessage object parameters

Parameter Example Value Description
Date 2019-12-01 14:02:03 Date/Time SMS was received (yyyy-mm-dd HH:mm:ss)
Destination 6421000001 Recipient of the SMS in E.164 internationalised format
MessageText This is an outbound message sent via API. Plain or UTF-8 formatted SMS message sent

SMSReceivedMessage object parameters

Parameter Example Value Description
Date 2019-12-01 14:02:03 Date/Time SMS was received (yyyy-mm-dd HH:mm:ss)
From +6421000001 Sender of the SMS in E.164 internationalised format
MessageText This is a reply back from the mobile phone. The SMS message received

Address book: Contacts

List Contact

List Contact via TNZ NodeJS Library

List Contact (Basic):

const TNZAPI = require('tnzapi');

const client = new TNZAPI({
    AuthToken: "[Your Auth Token]"          // Auth Token
});

var callback = function(data) {
    console.log("Response:",JSON.stringify(data, null, "  "));
}

client.Addressbook.Contact.List({
    Page: 1
}).then(callback);
List Contact (Advanced):

const TNZAPI = require('tnzapi');

const client = new TNZAPI({
    AuthToken: "[Your Auth Token]"          // Auth Token
});

var callback = function(data) {
    console.log("Response:",JSON.stringify(data, null, "  "));
}

client.Addressbook.Contact.List({
    RecordsPerPage: 10,
    Page: 1
}).then(callback);

Request parameters

Parameter Example Value Description
AuthToken Required eyJhbGciOiJI...adQssw5c Auth Token value set up in Create a new API Auth token
RecordsPerPage Optional 50 Specifies the number of records per page to be returned. If not provided, the default number (100) of records per page will be used.
Page Optional 1 Specifies the page number of the contact list to retrieve. If not provided, the default (1) behaviour will be followed.

Response properties

Property Type Example Value Description
Result string Success Result of your API call (not the result of the message)
TotalRecords int 3 Total number of contacts
RecordsPerPage int 100 Return x number of records per request (optional)
PageCount int 1 Maximum number of pages
Page int 1 Current location of the result set (optional)
Contacts Array() Contact object list List of contacts
ErrorMessage Array() ["Missing Sender"] Reason for the API call failure (see a list of possible values: TNZ API Errors)

Get Contact Detail

Get Contact Detail via TNZ NodeJS Library

Get Contact Detail (Basic):

const TNZAPI = require('tnzapi');

const client = new TNZAPI({
    AuthToken: "[Your Auth Token]"          // Auth Token
});

var callback = function(data) {
    console.log("Response:",JSON.stringify(data, null, "  "));
}

client.Addressbook.Contact.Detail({
    ContactID: "AAAAAAAA-BBBB-BBBB-CCCC-DDDDDDDDDDDD"
}).then(callback);
Get Contact Detail (Advanced):

const TNZAPI = require('tnzapi');

const client = new TNZAPI({
    AuthToken: "[Your Auth Token]"          // Auth Token
});

var callback = function(data) {
    console.log("Response:",JSON.stringify(data, null, "  "));
}

client.Addressbook.Contact.Detail({
    ContactID: "AAAAAAAA-BBBB-BBBB-CCCC-DDDDDDDDDDDD"
}).then(callback);

Request parameters

Parameter Example Value Description
AuthToken Required eyJhbGciOiJI...adQssw5c Auth Token value set up in Create a new API Auth token
ContactID Required AAAAAAAA-BBBB-BBBB-CCCC-DDDDDDDDDDDD Specifies the unique identifier of the contact to retrieve.

Response properties

Property Type Example Value Description
Result string Success Result of your API call (not the result of the message)
Contact object Contact object Contact detail
ErrorMessage Array() ["Missing Sender"] Reason for the API call failure (see a list of possible values: TNZ API Errors)

Contact object properties

Property Type Example Value Description
ID string AAAAAAAA-BBBB-BBBB-CCCC-DDDDDDDDDDDD Unique identifier for the contact
Owner string COM\EXAMPLE\TEST Your UserKey
Created datetime 2023-12-01T12:00:00 Creation date for this contact in your local date/time
CreatedUTC datetime 2023-12-01T00:00:00 Creation date for this contact in UTC date/time
Updated datetime 2023-12-01T12:00:00 Last updated date for this contact in your local date/time
UpdatedUTC datetime 2023-12-01T00:00:00 Last updated date for this contact in UTC date/time
Timezone string New Zealand Timezone associated with Created/Updated date/time
Attention string Person Attention Indicates the attention or focus associated with the contact.
Title string Ms Represents the title or honorific of the contact (e.g., Mr, Mrs, Ms).
Company string TNZ Group LTD. Specifies the company or organization associated with the contact.
CompanyDepartment string Sales Dept. Indicates the department or division within the company associated with the contact.
FirstName string Person first name Represents the first name of the contact.
LastName string Person last name Represents the last name of the contact.
Position string Sales Represent Specifies the job position or role of the contact.
StreetAddress string Sales Represent Represents the street address or location of the contact.
Suburb string My Suburb Specifies the suburb or district associated with the contact's address.
City string Auckland Indicates the city or locality associated with the contact's address.
State string AKL Represents the state or province associated with the contact's address.
Country string New Zealand Specifies the country associated with the contact's address.
Postcode string 1234 Represents the postal code or ZIP code associated with the contact's address.
MainPhone string 092223333 Specifies the main phone number of the contact. This property typically used for Voice & Text-To-Speech messages.
AltPhone1 string 093334444 Represents an alternate phone number for the contact. This property typically used for Voice & Text-To-Speech messages.
AltPhone2 string 094445555 Represents a second alternate phone number for the contact. This property typically used for Voice & Text-To-Speech messages.
DirectPhone string 094445555 Indicates the direct phone number of the contact.
MobilePhone string 0211144489 Represents the mobile phone number of the contact. This property typically used for SMS messages.
FaxNumber string 093334444 Specifies the fax number associated with the contact.
EmailAddress string person1@example.com Represents the email address of the contact.
WebAddress string https://www.tnz.co.nz Specifies the website address or URL associated with the contact.
Custom1...4 string Custom Value Represents custom fields or additional information associated with the contact.
ViewBy string Account Specifies the visibility of the contact. Values can be "Account", "SubAccount", "Department" or "No" visibility option.
EditBy string Account Specifies the permission level required to edit the contact. Values can be "Account", "SubAccount", "Department" or "No" permission option.

Create Contact

Create Contact via TNZ NodeJS Library

Create Contact (Basic):

const TNZAPI = require('tnzapi');

const client = new TNZAPI({
    AuthToken: "[Your Auth Token]"          // Auth Token
});

var callback = function(data) {
    console.log("Response:",JSON.stringify(data, null, "  "));
}

client.Addressbook.Contact.Create({
    Attention: "Test Person",
    FirstName: "First",
    LastName: "Last",
    MobilePhone: "+6421000001",
}).then(callback);
Create Contact (Advanced):

const TNZAPI = require('tnzapi');

const client = new TNZAPI({
    AuthToken: "[Your Auth Token]"          // Auth Token
});

var callback = function(data) {
    console.log("Response:",JSON.stringify(data, null, "  "));
}

client.Addressbook.Contact.Create({
    Title: "Mr",
    Company: "TNZ Group",
    FirstName: "First",
    LastName: "Last",
    MobilePhone: "+6421000001",
    ViewBy: "Account",
    EditBy: "Account"
}).then(callback);

Request parameters

Parameter Example Value Description
AuthToken Required eyJhbGciOiJI...adQssw5c Auth Token value set up in Create a new API Auth token

Response properties

Property Type Example Value Description
Result string Success Result of your API call (not the result of the message)
Contact object Contact object Contact detail
ErrorMessage Array() ["Missing Sender"] Reason for the API call failure (see a list of possible values: TNZ API Errors)

Update Contact

Update Contact via TNZ NodeJS Library

Update Contact (Basic):

const TNZAPI = require('tnzapi');

const client = new TNZAPI({
    AuthToken: "[Your Auth Token]"          // Auth Token
});

var callback = function(data) {
    console.log("Response:",JSON.stringify(data, null, "  "));
}

client.Addressbook.Contact.Update({
    ContactID: "AAAAAAAA-BBBB-BBBB-CCCC-DDDDDDDDDDDD",
    Attention: "Test Attention"
}).then(callback);
Update Contact (Advanced):

const TNZAPI = require('tnzapi');

const client = new TNZAPI({
    AuthToken: "[Your Auth Token]"          // Auth Token
});

var callback = function(data) {
    console.log("Response:",JSON.stringify(data, null, "  "));
}

client.Addressbook.Contact.Update({
    ContactID: "AAAAAAAA-BBBB-BBBB-CCCC-DDDDDDDDDDDD",
    Attention: "Test Attention"
    Title: "Mr",
    Company: "TNZ Group",
    FirstName: "First",
    LastName: "Last",
    MobilePhone: "+64212223333",
    ViewPublic: "Account",
    EditPublid: "Account"
}).then(callback);

Request parameters

Parameter Example Value Description
AuthToken Required eyJhbGciOiJI...adQssw5c Auth Token value set up in Create a new API Auth token
ContactID Required AAAAAAAA-BBBB-BBBB-CCCC-DDDDDDDDDDDD Specifies the unique identifier of the contact to update.

Response properties

Property Type Example Value Description
Result string Success Result of your API call (not the result of the message)
Contact object Contact object Contact detail
ErrorMessage Array() ["Missing Sender"] Reason for the API call failure (see a list of possible values: TNZ API Errors)

Delete Contact

Delete Contact via TNZ NodeJS Library

Delete Contact (Basic):

const TNZAPI = require('tnzapi');

const client = new TNZAPI({
    AuthToken: "[Your Auth Token]"          // Auth Token
});

var callback = function(data) {
    console.log("Response:",JSON.stringify(data, null, "  "));
}

client.Addressbook.Contact.Delete({
    ContactID: "AAAAAAAA-BBBB-BBBB-CCCC-DDDDDDDDDDDD"
}).then(callback);
Delete Contact (Advanced):

const TNZAPI = require('tnzapi');

const client = new TNZAPI({
    AuthToken: "[Your Auth Token]"          // Auth Token
});

var callback = function(data) {
    console.log("Response:",JSON.stringify(data, null, "  "));
}

client.Addressbook.Contact.Delete({
    ContactID: "AAAAAAAA-BBBB-BBBB-CCCC-DDDDDDDDDDDD"
}).then(callback);

Request parameters

Parameter Example Value Description
AuthToken Required eyJhbGciOiJI...adQssw5c Auth Token value set up in Create a new API Auth token
ContactID Required AAAAAAAA-BBBB-BBBB-CCCC-DDDDDDDDDDDD Specifies the unique identifier of the contact to delete.

Response properties

Property Type Example Value Description
Result string Success Result of your API call (not the result of the message)
Contact object Contact object Contact detail
ErrorMessage Array() ["Missing Sender"] Reason for the API call failure (see a list of possible values: TNZ API Errors)

Address book: Contact groups

List Contact Group

List Contact Group via TNZ NodeJS Library

List Contact Group (Basic):

const TNZAPI = require('tnzapi');

const client = new TNZAPI({
    AuthToken: "[Your Auth Token]"          // Auth Token
});

var callback = function(data) {
    console.log("Response:",JSON.stringify(data, null, "  "));
}

client.Addressbook.ContactGroup.List({
    ContactID: "AAAAAAAA-BBBB-BBBB-CCCC-DDDDDDDDDDDD",
    Page: 1
}).then(callback);
List Contact Group (Advanced):

const TNZAPI = require('tnzapi');

const client = new TNZAPI({
    AuthToken: "[Your Auth Token]"          // Auth Token
});

var callback = function(data) {
    console.log("Response:",JSON.stringify(data, null, "  "));
}

client.Addressbook.ContactGroup.List({
    ContactID: "AAAAAAAA-BBBB-BBBB-CCCC-DDDDDDDDDDDD",
    RecordsPerPage: 10,
    Page: 1
}).then(callback);

Request parameters

Parameter Example Value Description
AuthToken Required eyJhbGciOiJI...adQssw5c Auth Token value set up in Create a new API Auth token
ContactID Required AAAAAAAA-BBBB-BBBB-CCCC-DDDDDDDDDDDD Specifies the unique identifier of the contact to retrieve. (required)

Response properties

Property Type Example Value Description
Result string Success Result of your API call
TotalRecords int 3 Total number of groups associated with this contact
RecordsPerPage int 100 Return x number of records per request (optional)
PageCount int 1 Maximum number of pages
Page int 1 Current location of the result set (optional)
Contact object Contact object Contact detail
Groups Array() Group object list List of groups associated with this contact
ErrorMessage Array() ["Missing Sender"] Reason for the API call failure (see a list of possible values: TNZ API Errors)

Get Contact Group Detail

Get Contact Group Detail via TNZ NodeJS Library

Get Contact Group Detail (Basic):

const TNZAPI = require('tnzapi');

const client = new TNZAPI({
    AuthToken: "[Your Auth Token]"          // Auth Token
});

var callback = function(data) {
    console.log("Response:",JSON.stringify(data, null, "  "));
}

client.Addressbook.ContactGroup.Detail({
    ContactID: "AAAAAAAA-BBBB-BBBB-CCCC-DDDDDDDDDDDD",
    GroupCode: "Test_Group"
}).then(callback);
Get Contact Group Detail (Advanced):

const TNZAPI = require('tnzapi');

const client = new TNZAPI({
    AuthToken: "[Your Auth Token]"          // Auth Token
});

var callback = function(data) {
    console.log("Response:",JSON.stringify(data, null, "  "));
}

client.Addressbook.ContactGroup.Detail({
    ContactID: "AAAAAAAA-BBBB-BBBB-CCCC-DDDDDDDDDDDD",
    GroupCode: "Test_Group"
}).then(callback);

Request parameters

Parameter Example Value Description
AuthToken Required eyJhbGciOiJI...adQssw5c Auth Token value set up in Create a new API Auth token
ContactID Required AAAAAAAA-BBBB-BBBB-CCCC-DDDDDDDDDDDD Specifies the unique identifier of the contact to retrieve. (required)
GroupCode Required TEST_GROUP Specifies the unique identifier of the group to retrieve. (required)

Response properties

Property Type Example Value Description
Result string Success Result of your API call (not the result of the message)
Contact object Contact object Contact detail
Group object Group object Group detail
ErrorMessage Array() ["Missing Sender"] Reason for the API call failure (see a list of possible values: TNZ API Errors)

Create Contact Group

Create Contact Group via TNZ NodeJS Library

Create Contact Group (Basic):

const TNZAPI = require('tnzapi');

const client = new TNZAPI({
    AuthToken: "[Your Auth Token]"          // Auth Token
});

var callback = function(data) {
    console.log("Response:",JSON.stringify(data, null, "  "));
}

client.Addressbook.ContactGroup.Create({
    ContactID: "AAAAAAAA-BBBB-BBBB-CCCC-DDDDDDDDDDDD",
    GroupCode: "Test_Group"
}).then(callback);
Create Contact Group (Advanced):

const TNZAPI = require('tnzapi');

const client = new TNZAPI({
    AuthToken: "[Your Auth Token]"          // Auth Token
});

var callback = function(data) {
    console.log("Response:",JSON.stringify(data, null, "  "));
}

client.Addressbook.ContactGroup.Create({
    ContactID: "AAAAAAAA-BBBB-BBBB-CCCC-DDDDDDDDDDDD",
    GroupCode: "Test_Group"
}).then(callback);

Request parameters

Parameter Example Value Description
AuthToken Required eyJhbGciOiJI...adQssw5c Auth Token value set up in Create a new API Auth token
ContactID Required AAAAAAAA-BBBB-BBBB-CCCC-DDDDDDDDDDDD Specifies the unique identifier of the contact to create. (required)
GroupCode Required TEST_GROUP Specifies the unique identifier of the group to create. (required)

Response properties

Property Type Example Value Description
Result string Success Result of your API call
Contact object Contact object Contact detail
Group object Group object Group detail
ErrorMessage Array() ["Missing Sender"] Reason for the API call failure (see a list of possible values: TNZ API Errors)

Delete Contact Group

Delete Contact Group via TNZ NodeJS Library

Delete Contact Group (Basic):

const TNZAPI = require('tnzapi');

const client = new TNZAPI({
    AuthToken: "[Your Auth Token]"          // Auth Token
});

var callback = function(data) {
    console.log("Response:",JSON.stringify(data, null, "  "));
}

client.Addressbook.ContactGroup.Delete({
    ContactID: "AAAAAAAA-BBBB-BBBB-CCCC-DDDDDDDDDDDD",
    GroupCode: "Test_Group"
}).then(callback);
Delete Contact Group (Advanced):

const TNZAPI = require('tnzapi');

const client = new TNZAPI({
    AuthToken: "[Your Auth Token]"          // Auth Token
});

var callback = function(data) {
    console.log("Response:",JSON.stringify(data, null, "  "));
}

client.Addressbook.ContactGroup.Delete({
    ContactID: "AAAAAAAA-BBBB-BBBB-CCCC-DDDDDDDDDDDD",
    GroupCode: "Test_Group"
}).then(callback);

Request parameters

Parameter Example Value Description
AuthToken Required eyJhbGciOiJI...adQssw5c Auth Token value set up in Create a new API Auth token
ContactID Required AAAAAAAA-BBBB-BBBB-CCCC-DDDDDDDDDDDD Specifies the unique identifier of the contact to delete. (required)
GroupCode Required TEST_GROUP Specifies the unique identifier of the group to delete. (required)

Response properties

Property Type Example Value Description
Result string Success Result of your API call
Contact object Contact object Contact detail
Group object Group object Group detail
ErrorMessage Array() ["Missing Sender"] Reason for the API call failure (see a list of possible values: TNZ API Errors)

Address book: Groups

List Group

List Group via TNZ NodeJS Library

List Group (Basic):

const TNZAPI = require('tnzapi');

const client = new TNZAPI({
    AuthToken: "[Your Auth Token]"          // Auth Token
});

var callback = function(data) {
    console.log("Response:",JSON.stringify(data, null, "  "));
}

client.Addressbook.Group.List({
    Page: 1
}).then(callback);
List Group (Advanced):

const TNZAPI = require('tnzapi');

const client = new TNZAPI({
    AuthToken: "[Your Auth Token]"          // Auth Token
});

var callback = function(data) {
    console.log("Response:",JSON.stringify(data, null, "  "));
}

client.Addressbook.Group.List({
    RecordsPerPage: 10,
    Page: 1
}).then(callback);

Request parameters

Parameter Example Value Description
AuthToken Required eyJhbGciOiJI...adQssw5c Auth Token value set up in Create a new API Auth token
RecordsPerPage Optional 50 Specifies the number of records per page to be returned. If not provided, the default number (100) of records per page will be used.
Page Optional 1 Specifies the page number of the contact list to retrieve. If not provided, the default (1) behaviour will be followed.

Response properties

Property Type Example Value Description
Result string Success Result of your API call (not the result of the message)
TotalRecords int 3 Total number of records
RecordsPerPage int 100 Return x number of records per request (optional)
PageCount int 1 Maximum number of pages
Page int 1 Current location of the result set (optional)
Groups object Group object list List of group
ErrorMessage Array() ["Missing Sender"] Reason for the API call failure (see a list of possible values: TNZ API Errors)

Group Detail

Group Detail via TNZ NodeJS Library

Group Detail (Basic):

const TNZAPI = require('tnzapi');

const client = new TNZAPI({
    AuthToken: "[Your Auth Token]"          // Auth Token
});

var callback = function(data) {
    console.log("Response:",JSON.stringify(data, null, "  "));
}

client.Addressbook.Group.Detail({
    GroupCode: "Test_Group"
}).then(callback);
Group Detail (Advanced):

const TNZAPI = require('tnzapi');

const client = new TNZAPI({
    AuthToken: "[Your Auth Token]"          // Auth Token
});

var callback = function(data) {
    console.log("Response:",JSON.stringify(data, null, "  "));
}

client.Addressbook.Group.Detail({
    GroupCode: "Test_Group"
}).then(callback);

Request parameters

Parameter Example Value Description
AuthToken Required eyJhbGciOiJI...adQssw5c Auth Token value set up in Create a new API Auth token
GroupCode Required TEST_GROUP Specifies the unique identifier of the group to retrieve. (required)

Response properties

Property Type Example Value Description
Result string Success Result of your API call
Group object Group object Group detail
ErrorMessage Array() ["Missing Sender"] Reason for the API call failure (see a list of possible values: TNZ API Errors)

Group object properties

Property Type Example Value Description
GroupCode string Test-Group Unique identifier for the group
GroupName string Test Group Represents the name of the group.
SubAccount string SubAccount01 Used for reporting, billing and Web Dashboard segmentation. See the TNZ API Structure guide's Cost Tracking & Rebilling section.
Department string Department01 Used for reporting, billing and Web Dashboard segmentation. See the TNZ API Structure guide's Cost Tracking & Rebilling section.
ViewEditBy string Account Specifies the permission level required to view/edit the group. Values can be "Account", "SubAccount", "Department" or "No" permission option.
Owner string COM\EXAMPLE\TEST Your UserKey

Create Group

Create Group via TNZ NodeJS Library

Create Group (Basic):

const TNZAPI = require('tnzapi');

const client = new TNZAPI({
    AuthToken: "[Your Auth Token]"          // Auth Token
});

var callback = function(data) {
    console.log("Response:",JSON.stringify(data, null, "  "));
}

client.Addressbook.Group.Create({
    GroupName: "Test Group"
}).then(callback);
Create Group (Advanced):

const TNZAPI = require('tnzapi');

const client = new TNZAPI({
    AuthToken: "[Your Auth Token]"          // Auth Token
});

var callback = function(data) {
    console.log("Response:",JSON.stringify(data, null, "  "));
}

client.Addressbook.Group.Create({
    GroupName: "Test Group",
    ViewEditBy: "Account"
}).then(callback);

Request parameters

Parameter Example Value Description
AuthToken Required eyJhbGciOiJI...adQssw5c Auth Token value set up in Create a new API Auth token
GroupCode Required TEST_GROUP Specifies the unique identifier of the group to create. (required)

Response properties

Property Type Example Value Description
Result string Success Result of your API call
Group object Group object Group detail
ErrorMessage Array() ["Missing Sender"] Reason for the API call failure (see a list of possible values: TNZ API Errors)

Update Group

Update Group via TNZ NodeJS Library

Update Group (Basic):

const TNZAPI = require('tnzapi');

const client = new TNZAPI({
    AuthToken: "[Your Auth Token]"          // Auth Token
});

var callback = function(data) {
    console.log("Response:",JSON.stringify(data, null, "  "));
}

client.Addressbook.Group.Update({
    GroupCode: "Test_Group",
    GroupName: "Test Group 123"
}).then(callback);
Update Group (Advanced):

const TNZAPI = require('tnzapi');

const client = new TNZAPI({
    AuthToken: "[Your Auth Token]"          // Auth Token
});

var callback = function(data) {
    console.log("Response:",JSON.stringify(data, null, "  "));
}

client.Addressbook.Group.Update({
    GroupCode: "Test_Group",
    GroupName: "Test Group 123",
    SubAccount: "Test",
    ViewEditBy: "Account"
}).then(callback);

Request parameters

Parameter Example Value Description
AuthToken Required eyJhbGciOiJI...adQssw5c Auth Token value set up in Create a new API Auth token
GroupCode Required TEST_GROUP Specifies the unique identifier of the group to update. (required)

Response properties

Property Type Example Value Description
Result string Success Result of your API call
Group object Group object Group detail
ErrorMessage Array() ["Missing Sender"] Reason for the API call failure (see a list of possible values: TNZ API Errors)

Delete Group

Delete Group via TNZ NodeJS Library

Delete Group (Basic):

const TNZAPI = require('tnzapi');

const client = new TNZAPI({
    AuthToken: "[Your Auth Token]"          // Auth Token
});

var callback = function(data) {
    console.log("Response:",JSON.stringify(data, null, "  "));
}

client.Addressbook.Group.Delete({
    GroupCode: "Test_Group"
}).then(callback);
Delete Group (Advanced):

const TNZAPI = require('tnzapi');

const client = new TNZAPI({
    AuthToken: "[Your Auth Token]"          // Auth Token
});

var callback = function(data) {
    console.log("Response:",JSON.stringify(data, null, "  "));
}

client.Addressbook.Group.Delete({
    GroupCode: "Test_Group"
}).then(callback);

Request parameters

Parameter Example Value Description
AuthToken Required eyJhbGciOiJI...adQssw5c Auth Token value set up in Create a new API Auth token
GroupCode Required TEST_GROUP Specifies the unique identifier of the group to delete. (required)

Response properties

Property Type Example Value Description
Result string Success Result of your API call
Group object Group object Group detail
ErrorMessage Array() ["Missing Sender"] Reason for the API call failure (see a list of possible values: TNZ API Errors)

Address book: Group contacts

List Group Contact

List Group Contact via TNZ NodeJS Library

List Group Contact (Basic):

const TNZAPI = require('tnzapi');

const client = new TNZAPI({
    AuthToken: "[Your Auth Token]"          // Auth Token
});

var callback = function(data) {
    console.log("Response:",JSON.stringify(data, null, "  "));
}

client.Addressbook.GroupContact.List({
    GroupCode: "Test_Group",
    Page: 1
}).then(callback);
List Group Contact (Advanced):

const TNZAPI = require('tnzapi');

const client = new TNZAPI({
    AuthToken: "[Your Auth Token]"          // Auth Token
});

var callback = function(data) {
    console.log("Response:",JSON.stringify(data, null, "  "));
}

client.Addressbook.GroupContact.List({
    GroupCode: "Test_Group",
    RecordsPerPage: 10,
    Page: 1
}).then(callback);

Request parameters

Parameter Example Value Description
AuthToken Required eyJhbGciOiJI...adQssw5c Auth Token value set up in Create a new API Auth token
GroupCode Required TEST_GROUP Specifies the unique identifier of the group to retrieve. (required)

Response properties

Property Type Example Value Description
Result string Success Result of your API call
TotalRecords int 3 Total number of groups associated with this contact
RecordsPerPage int 100 Return x number of records per request (optional)
PageCount int 1 Maximum number of pages
Page int 1 Current location of the result set (optional)
Group object Group object Group detail
Contacts Array() Contact object list List of contacts associated with this group
ErrorMessage Array() ["Missing Sender"] Reason for the API call failure (see a list of possible values: TNZ API Errors)

Get Group Contact Detail

Get Group Contact Detail via TNZ NodeJS Library

Get Group Contact Detail (Basic):

const TNZAPI = require('tnzapi');

const client = new TNZAPI({
    AuthToken: "[Your Auth Token]"          // Auth Token
});

var callback = function(data) {
    console.log("Response:",JSON.stringify(data, null, "  "));
}

client.Addressbook.ContactGroup.Create({
    ContactID: "AAAAAAAA-BBBB-BBBB-CCCC-DDDDDDDDDDDD",
    GroupCode: "Test_Group"
}).then(callback);
Get Group Contact Detail (Advanced):

const TNZAPI = require('tnzapi');

const client = new TNZAPI({
    AuthToken: "[Your Auth Token]"          // Auth Token
});

var callback = function(data) {
    console.log("Response:",JSON.stringify(data, null, "  "));
}

client.Addressbook.ContactGroup.Create({
    ContactID: "AAAAAAAA-BBBB-BBBB-CCCC-DDDDDDDDDDDD",
    GroupCode: "Test_Group"
}).then(callback);

Request parameters

Parameter Example Value Description
AuthToken Required eyJhbGciOiJI...adQssw5c Auth Token value set up in Create a new API Auth token
GroupCode Required TEST_GROUP Specifies the unique identifier of the group to retrieve. (required)
ContactID Required AAAAAAAA-BBBB-BBBB-CCCC-DDDDDDDDDDDD Specifies the unique identifier of the contact to retrieve. (required)

Response properties

Property Type Example Value Description
Result string Success Result of your API call
Group object Group object Group detail
Contact object Contact object Contact detail
ErrorMessage Array() ["Missing Sender"] Reason for the API call failure (see a list of possible values: TNZ API Errors)

Create Group Contact

Create Group Contact via TNZ NodeJS Library

Create Group Contact (Basic):

const TNZAPI = require('tnzapi');

const client = new TNZAPI({
    AuthToken: "[Your Auth Token]"          // Auth Token
});

var callback = function(data) {
    console.log("Response:",JSON.stringify(data, null, "  "));
}

client.Addressbook.GroupContact.Create({
    GroupCode: "Test_Group",
    ContactID: "AAAAAAAA-BBBB-BBBB-CCCC-DDDDDDDDDDDD"
}).then(callback);
Create Group Contact (Advanced):

const TNZAPI = require('tnzapi');

const client = new TNZAPI({
    AuthToken: "[Your Auth Token]"          // Auth Token
});

var callback = function(data) {
    console.log("Response:",JSON.stringify(data, null, "  "));
}

client.Addressbook.GroupContact.Create({
    GroupCode: "Test_Group",
    ContactID: "AAAAAAAA-BBBB-BBBB-CCCC-DDDDDDDDDDDD"
}).then(callback);

Request parameters

Parameter Example Value Description
AuthToken Required eyJhbGciOiJI...adQssw5c Auth Token value set up in Create a new API Auth token
GroupCode Required TEST_GROUP Specifies the unique identifier of the group to create. (required)
ContactID Required AAAAAAAA-BBBB-BBBB-CCCC-DDDDDDDDDDDD Specifies the unique identifier of the contact to create. (required)

Response properties

Property Type Example Value Description
Result string Success Result of your API call
Group object Group object Group detail
Contact object Contact object Contact detail
ErrorMessage Array() ["Missing Sender"] Reason for the API call failure (see a list of possible values: TNZ API Errors)

Delete Group Contact

Delete Group Contact via TNZ NodeJS Library

Delete Group Contact (Basic):

const TNZAPI = require('tnzapi');

const client = new TNZAPI({
    AuthToken: "[Your Auth Token]"          // Auth Token
});

var callback = function(data) {
    console.log("Response:",JSON.stringify(data, null, "  "));
}

client.Addressbook.GroupContact.Delete({
    GroupCode: "Test_Group",
    ContactID: "AAAAAAAA-BBBB-BBBB-CCCC-DDDDDDDDDDDD"
}).then(callback);
Delete Group Contact (Advanced):

const TNZAPI = require('tnzapi');

const client = new TNZAPI({
    AuthToken: "[Your Auth Token]"          // Auth Token
});

var callback = function(data) {
    console.log("Response:",JSON.stringify(data, null, "  "));
}

client.Addressbook.GroupContact.Delete({
    GroupCode: "Test_Group",
    ContactID: "AAAAAAAA-BBBB-BBBB-CCCC-DDDDDDDDDDDD"
}).then(callback);

Request parameters

Parameter Example Value Description
AuthToken Required eyJhbGciOiJI...adQssw5c Auth Token value set up in Create a new API Auth token
GroupCode Required TEST_GROUP Specifies the unique identifier of the group to delete. (required)
ContactID Required AAAAAAAA-BBBB-BBBB-CCCC-DDDDDDDDDDDD Specifies the unique identifier of the contact to delete. (required)

Response properties

Property Type Example Value Description
Result string Success Result of your API call
Group object Group object Group detail
Contact object Contact object Contact detail
ErrorMessage Array() ["Missing Sender"] Reason for the API call failure (see a list of possible values: TNZ API Errors)

Versioning

As new versions of the APIs are released, this API reference guide will be updated to reflect the latest version and features supported:
API Version ChangeLog

Frequently Asked Questions

Can messages be sent internationally?
Yes, full international delivery is supported.
Is there a maximum request size?
The maximum request size supported is 20MB. This is our server side limitation. Your client side limitation may be smaller.
How many Destinations can I specify in one request?
There is no limit to the number of Destinations (in either format), provided you do not breach the maximum request size.
How many Files can I specify in one request?
There is a limit of 10 files specified in a single request. There is no file size limitation, provided you do not breach the maximum request size.
Do you support SPF, DKIM, DMARC, etc, for MessageType=Email?
Yes, we support email security measures. Contact us for further information on setting up your own security measures for whitelabeled messages delivered with the API.
What filetypes are supported for MessageType=Fax?
You can send a wide range of file types, including Microsoft Office® documents (doc, docx, ppt, pptx, xls, xlsx, etc), Openoffice/Libreoffice documents (odt, ods, etc), Adobe® documents (pdf, etc), image file types (jpg, gif, tif, bmp, etc) and more (txt, html, etc).
When I send MessageType=SMS messages, the text is cut off at 160 characters. Why?
SMS messages are sent and charged in blocks of characters. One text message is 160 characters. By default, we will limit your message to three-message-parts in length (459 characters using the GSM character set, or 210 characters using Unicode/UCS-2). This can be increased on request. See the SMS Message Parts and Concatenated SMS guide for further information.
In addition to the Delivery Report methods listed above, am I able to receive a daily or monthly summary?
Yes, we can provide a daily or monthly email report (as an attached CSV file) containing data on messages sent. This can be used for billing (contains costs) or for reporting (doesn’t contain costs).
Is HTTPS, SSL, or TLS supported?
Yes, encrypted submissions are accepted via HTTPS. SSL/TLS is also supported for outbound email messages provided the receiving email server supports this.
Can I set the Caller ID on SMS, Fax, Voice and TextToSpeech messages?
Some networks support customised SMS Caller IDs. This can be configured using your Web Dashboard.Your Fax Caller ID can be configured using your Web Dashboard.Your Voice and TextToSpeech Caller ID is specified on a per-message basis using the 'CallerID' parameter.