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:
- Login to the TNZ Dashboard
- Navigate to 'Users'
- Create a new user or select an existing one
- Enable API access (if it's not already enabled)
- Click on the 'API' tab
- Enable 'Auth Token' and create a new Auth Token
- Click the ' Copy' button to copy it to your clipboard
- 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
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