# TNZ Communications MCP

> TNZ Communications connects your AI agent directly to New Zealand and global messaging channels. You can send SMS, automated voice calls (TTS), and digital faxes through one API gateway. This server lets your agent check account balances, manage contacts, track delivery status, and handle incoming replies without leaving your workspace.

## Overview
- **Category:** communication-messaging
- **Price:** Free
- **Tags:** sms-gateway, voice-broadcasting, text-to-speech, fax-services, multichannel-messaging, api-integration

## Description

When you hook up your AI agent to this TNZ Communications server, you're giving it direct access to New Zealand and global messaging channels. You can make your agent send SMS texts, automated voice calls using Text-to-Speech (TTS), or digital faxes—all through one API gateway. It lets your agent check account credit, manage contacts, track delivery status, and handle incoming replies without leaving your workspace.

### Setup and Status Checks
First, you'll want to make sure the connection is solid. Use `check_api_health` to verify that the TNZ API link is active and working correctly before anything else. You can also monitor your operational finances; run `get_account_balance` to see exactly how much credit you've got left on your communications account, or pull a full picture of spending by running `get_messaging_usage_report`, which gives detailed reports showing total messaging usage and associated costs over time.

### Contact Management
Need to talk to people? Your agent can manage all the contacts in your TNZ address book. You'll use `list_tnz_contacts` to fetch a complete list of every saved contact. If you need to organize them for bulk messaging, run `list_contact_groups` to see every group you've set up. When you find someone new, don't manually enter their info; just call `create_tnz_contact` to add a brand-new entry directly into your managed list.

### Messaging Capabilities
This server lets your agent communicate across three channels: SMS, voice, and fax. To send a standard text message, you dispatch it with `send_sms_message`. For automated calling, your agent initiates the call using `send_tts_voice_call`, which reads out any script via Text-to-Speech technology. If you need to transmit documents as faxes, just use `send_digital_fax` to send a specific file document to the recipient.

### Tracking and Interaction
Your agent doesn't just fire off messages; it tracks them. You can check if a message actually got there by using `get_message_delivery_status`, passing in the specific message ID for real-time status checks. When you're setting up automated outbound messages, you won't need to start from scratch; run `list_message_templates` to retrieve all your pre-saved content templates. The agent handles incoming replies too: it lists recent SMS responses using `list_received_sms_replies`, letting your AI client read and respond automatically. You can also use `list_message_templates` if you need to check what message formats are available for immediate use.

## Tools

### check_api_health
Verifies that the TNZ API connection is active and working correctly.

### create_tnz_contact
Adds a new contact entry to your managed list within the TNZ system.

### get_account_balance
Checks how much credit you have remaining on your TNZ communications account.

### get_messaging_usage_report
Pulls detailed reports showing your total messaging usage and associated costs over time.

### get_message_delivery_status
Retrieves the current delivery status for a specific message ID.

### list_tnz_contacts
Fetches a list of all saved contacts currently in your TNZ address book.

### list_contact_groups
Shows all the contact groups you have set up in your TNZ address book.

### list_received_sms_replies
Lists recent incoming SMS replies, allowing your agent to read and respond to them.

### list_message_templates
Retrieves a list of pre-saved message templates you can use for sending content.

### send_digital_fax
Sends a specific document file as a digital fax message to a recipient.

### send_sms_message
Dispatches a standard text message (SMS) to a specified mobile number.

### send_tts_voice_call
Initiates an automated voice call using Text-to-Speech technology.

## Prompt Examples

**Prompt:** 
```
Send a SMS to +6421000000: 'The delivery is arriving at 2 PM today.'
```

**Response:** 
```
Done! I've sent the SMS message to +6421000000 via TNZ. MessageID: ref_123.
```

**Prompt:** 
```
What is the status of my message ID 'ref_123'?
```

**Response:** 
```
The status for message 'ref_123' is 'DELIVERED'. It was received by the recipient today at 10:15 AM.
```

**Prompt:** 
```
Check my current TNZ account balance.
```

**Response:** 
```
You currently have $25.50 remaining in your TNZ Communications account.
```

## Capabilities

### Send multi-channel messages
Your agent sends SMS, TTS voice calls, or digital faxes using specific tools like `send_sms_message` or `send_tts_voice_call`.

### Manage contact lists and groups
The server lets your agent list contacts with `list_tnz_contacts`, create new ones using `create_tnz_contact`, or organize them into groups via `list_contact_groups`.

### Track message delivery and usage
You can check if a sent message arrived with `get_message_delivery_status`, retrieve incoming SMS replies using `list_received_sms_replies`, or run full reports with `get_messaging_usage_report`.

### Automate proactive alerts
Your agent can initiate automated processes, like sending a reminder via SMS or calling a client using TTS voice calls, based on conversation context.

## Use Cases

### Alerting staff about a system outage
The ops engineer doesn't want to email 50 people. They ask their agent: 'Send an urgent SMS alert to the Site Manager group.' The agent uses `list_contact_groups` and then triggers `send_sms_message`, guaranteeing everyone gets the warning instantly.

### Following up after a sales call
A rep needs to send an immediate follow-up reminder. Instead of drafting an email, they ask: 'Call John Smith and leave a message about the contract.' The agent uses `send_tts_voice_call`, ensuring the client gets the personalized voice touch.

### Processing customer service queries
A customer texts back asking for tracking info. Instead of having to switch apps, the support specialist asks: 'Check the reply from SMS ID 456.' The agent uses `list_received_sms_replies` and replies automatically.

### Sending formal documentation
The accounting team needs to send a final, signed contract. They tell their agent: 'Fax this document now.' The agent executes `send_digital_fax`, handling the specialized formatting required for official documents.

## Benefits

- Get full visibility into messaging status. Use `get_message_delivery_status` to confirm if a critical alert actually arrived at the recipient's phone.
- Manage outreach in batches. Combine `list_tnz_contacts` and `send_sms_message` to send alerts to entire groups without manual copy-pasting.
- Handle conversations automatically. The ability to run `list_received_sms_replies` means your agent can read inbound customer texts and respond instantly.
- Automate high-touch communication. Instead of just sending text, use `send_tts_voice_call` for automated reminders or follow-ups.
- Keep track of costs in real time. Run `get_account_balance` frequently so you never get hit with unexpected billing charges from the TNZ gateway.

## How It Works

The bottom line is that once authenticated, any conversational instruction can trigger complex messaging operations across multiple channels.

1. First, subscribe to the TNZ server and enter your unique TNZ Auth Token in the dashboard.
2. Second, call any tool (like `get_account_balance` or `send_sms_message`) from your AI client using natural language conversation.
3. Third, the agent executes the API request against the TNZ gateway and returns a status update or confirmation ID to you.

## Frequently Asked Questions

**Can I use send_sms_message for bulk alerts?**
Yes, you can. First, run `list_contact_groups` to get your target audience, and then the agent uses `send_sms_message` across all members of that group.

**How do I check if a message was received?**
You use `get_message_delivery_status`. You just need to provide the unique message ID, and it tells you exactly where the message is right now.

**What tools handle incoming texts?**
The server provides `list_received_sms_replies`. Your agent reads these replies so your workflow can respond to customer queries in real-time.

**Can I check my billing balance with this API?**
Yep, just run the `get_account_balance` tool. It pulls your current credit usage directly from your TNZ account.

**How do I verify that the connection is working using `check_api_health`?**
Run `check_api_health`. This tool confirms your credentials and connectivity status with TNZ's gateway before you send any messages. It’s a quick check to ensure everything's live and ready to go.

**How can I get detailed historical usage records using `get_messaging_usage_report`?**
Call `get_messaging_usage_report`. This tool pulls comprehensive reports detailing both message volumes and associated costs over a specified period. It helps you track spending patterns, which is different from just checking the current balance.

**Before sending messages, how do I add or manage recipient contacts using `create_tnz_contact`?**
Use `create_tnz_contact`. This tool allows your agent to programmatically add new recipients directly into the TNZ address book. Always verify contact details before initiating any broadcast campaigns.

**Where do I find pre-written voice scripts or message content using `list_message_templates`?**
Use `list_message_templates`. This shows all your saved, reusable message templates. You can pull these predefined texts to ensure consistency and save time when sending SMS or triggering a Text-to-Speech call.

**How do I get an Auth Token for TNZ?**
Log in to your TNZ Dashboard, go to Users, select your user, and click the API tab to generate your unique Auth Token.

**Can the agent send voice calls?**
Yes, using the `send_tts_voice_call` tool, the agent can convert text into a high-quality voice call for your recipients.

**Does this support sending faxes?**
Absolutely. The `send_digital_fax` tool allow you to send documents or text as faxes directly from your agent.