Integrating TNZ with n8n for Workflow Automation

n8n allows you to connect thousands of apps and services to create sophisticated workflows.

You can easily connect to our powerful communications platform using the HTTP Request node.

This article provides a comprehensive, step-by-step guide to setting up TNZ's SMS, Email, and Voice APIs within your n8n workflows.

Prerequisites: Enabling Your API Access

Before you can configure your n8n workflow, you need to generate an Auth Token from your TNZ Dashboard. This token acts as a secure, private key that authenticates your API calls.

Step 1: Log into Your TNZ Dashboard and Access API Settings

1. Log in to your TNZ Account at https://my.tnz.co.nz.

2. From the menu, navigate to Users.

3. Click on an existing user, or create a new one.

Step 2: Enable API and Generate an Auth Token

1. Toggle 'Enable API' to Yes (if not already enabled).

2. Click 'Enable' next to 'Auth Token'.

3. Click 'Create Auth Token' and confirm the action.

4. 'Copy' your newly created Auth Token. Keep this token secure, it is a secret credential.

Triggering an SMS, Email or Voice

Since the TNZ API is a RESTful API that works over HTTP, you will use n8n's HTTP Request node to connect.

To configure the n8n Workflow:

1. Log in to your n8n instance or cloud account and open your Workflow, or create a new one.

2. Ensure your workflow has a Trigger node (the workflow's first step).

3. Click the '+' icon and search for the HTTP Request node.

4. Configure these variables:
   1. Method = POST
   2. URL =
      1. For SMS, use: https://api.tnz.co.nz/api/v3.00/sms
      2. For Voice, use: https://api.tnz.co.nz/api/v3.00/tts 
      3. For Email, use: https://api.tnz.co.nz/api/v3.00/email 
   3. Authentication = None
   4. Send Headers = Yes
      1. Header Name = Authorization
      2. Header Value = Basic [Your-auth-token-here]
   5. Send Body = Yes
      1. Body Content Type = JSON
      2. Specify Body = Using JSON
      3. JSON = 
         

         {
           "Message": "Hello {{ $json.customerName }}, your order has shipped! Tracking: {{ $json.trackingNumber }}",
           "Destination": "{{ $json.mobileNumber }}"
         }
         

         (Replace these values as appropriate)

Customising the message:

Each message type (SMS, Email, Voice) has unique variables you can include to customise your message.

For example, in an Email you can customise the EmailSubject, FromEmail, CCEmail, and in a Voice call you can customise the Caller ID, Voice that is used, etc.

Refer to the TNZ REST API Documentation for all available parameters.

Tip: You can copy the cURL samples from the TNZ API documentation directly into n8n: 

Webhook Callbacks:

When configuring your message, you may wish to receive a callback when the message delivery completes, or if an SMS Reply is detected.

Set these values: 
  "NotificationType": "Webhook",
  "WebhookCallbackURL": "Your n8n Webhook URL"

Example: 

{
  "Message": "Hello {{ $json.customerName }}, your order has shipped! Tracking: {{ $json.trackingNumber }}",
  "Destination": "{{ $json.mobileNumber }}",
  "NotificationType": "Webhook",
  "WebhookCallbackURL": "https://localhost:5678/webhook/95c28040d2f4-0d7c-47e7-8e5d"
}

(Replace these values as appropriate)

Capturing Inbound SMS Messages

When TNZ receives an SMS message, it can webhook the data to your n8n Workflow.

To configure the n8n Workflow:

1. Log in to your n8n instance or cloud account and open your Workflow, or create a new one.

2. Click the '+' icon and search for the Webhook node.
3. Configure these variables:
   1. Method = POST
   2. Path = [leave default]
   3. Authentication = None
   4. Respond = Immediately
4. Note the Test and Production URLs.

To activate the webhook:

Now that your n8n Workflow's Webhook URL is set up, you need to advise TNZ to use it.

When sending an outbound message from n8n, you may specify the URL in the "WebhookCallbackURL" body parameter.

Your user in the TNZ Dashboard can also have a default Webhook URL configured.

Follow the Configuring Webhooks and API Notifications for full instructions.

Reporting on Activity

After your n8n workflow executes the API call, you can review the status and details of the sent messages directly in the TNZ Dashboard:

1. Log in to the TNZ Dashboard.

2. Select 'View Messages' from the menu.

3. Select 'Detailed Messages Sent' to view comprehensive delivery and usage reports for all messages sent via the API (including those from n8n).

This detailed log allows you to monitor delivery status, costs, and any replies received from your customers.