NationStates

---

Welcome, reader, to The Simplest Comprehensive Guide to Sending API telegrams on Nationtates! So, I hear you want to learn how to have your computer pump out telegrams on full auto, right? Well, you're in the right place! If you have no idea what I'm talking about, you're still in the right place! Keep on reading to learn everything you need to know about the telegram API for personal or regional usage.

---

Table of Contents:

> What is the telegram API? (and other general questions)
> Uses and Requirements
> Codes
> Clients

---

What is "The Telegram API?"

Short answer: Something that lets programs interface with NS to automatically send telegrams in a legal manner.



(Will be continued as I get some ... Frequently Asked Questions )


Tags: mass telegrams many nations tg recruit auto client code automated automatic fast free api program script easy large stamps alternative messages group

Usage

What can I do with the telegram API?

In short, the telegram API can be used to send many telegrams over time, with little effort, at a moderate to slow speed. What kind of telegrams? Any! The most common use is generally for recruitment - indeed many clients (discussed later) have a number of specialized tools to assist you with targeting certain types of nations. Recruitment telegrams send via the API at a rate of 1 per every 3 minutes per NS rules. While slower than stamps or even manual sending, it's free, requires less effort, and can be used to assure all recruitment for a region is secure. However, the API can also be used to send non-recruitment telegram! Whether WA campaign telegrams, or any other non-recruitment type, these can be sent at a rate of one every 30 seconds - a fairly decent rate. Don't worry, you don't have to set these speeds - clients do it for you. For reference, telegramming all WA delegates via API would take about 11 hours, but save you 1250 stamps. Other uses could included sending a regionwide telegram concerning an event or other matter without stamps or access to the regional administration, or otherwise messaging a large body of people. The telegram API system makes it possible for anyone to have the same reach as a stamp purchaser for free, with the sacrifice being a more lengthy delivery period.

---

Secure your Recruitment!

As of July 22, 2015, Nationstates regions now have built-in recruitment restriction settings. Found under the regional control page (the same place you edit the WFE and such) and accessible to Founders and Executive Delegates, these settings allow you to limit who can send telegrams for your region, and what kind of telegrams can be sent. Settings include:



- None of these options affect non-recruitment API (or any other type of) telegrams
- Restrictions affecting API usage apply to the telegram creator. If the creator of the TGID and Secret Key is not permitted to send recruitment telegrams, telegrams WILL NOT send.

---

What you need:

So, what do you need to send telegrams using the telegram API?

• A Telegram
• A Telegram Identification Code (TGID)
• A Secret Key
• A Client Key
• A Client
• Permission to Recruit

Keep reading to see how each of these is obtained.

Codes

There are three main codes you'll need to send your telegrams via API. These are the TGID, the Secret Key, and your Client Key. Below, you'll find steps to obtain each. This section is only about how to get these codes, not how to use them! Go to the Next Section to learn how to use these codes.

---

TGID and Secret Key

Both of these items are obtained through the same processes, and are specific to the individual telegram being sent. These codes *can* be shared with another nation, but doing so is not recommended, as they'll always send with the name of the creator on the "from" line! Also, if the creator ceases to exist or leaves the region the client key is issued for (more on that later), the telegrams will stop! Best to keep all your codes coming from the same place, eh?

First, go to your telegrams page, and hit "new telegram." Write the telegram you wish to be sent via the API in the relevant box (reminder: the code "%NATION%" allows each recipient to see their nation name where it is placed). If your telegram is a recruitment message, make sure to click the drop down arrow and check the box stating "This is a recruitment telegram" - this both adds the "move to [region]" link at the bottom of your message, and properly marks all instances of this telegram sent. If your telegram is a campaign message, use the further options available in the drop down menu to select that instead and avoid modly wraith. If your message is neither, don't worry about checking any boxes. For more information, see the technical section of the FAQ.

Next, address the telegram to "tag:api" and send it. You will not receive a reply- rather, use the menu in the top left of your inbox to navigate to your sent messages, find the message you just sent, and click to open it in full. Scrolling to the bottom of that message, click "Recruitment & Delivery Reports." The following information will appear:

This is an API Template. To wire a copy to someone, make make an API request using the following information:

TGID: #######

Secret Key: a111111a1111

Do not share your Secret Key with anyone.

...followed by delivery information (which, while perhaps of interest to you later, is not relevant at present time). These are the TGID and Secret Key for this message, and can always be found under this link in your sentbox.

---

Client Key

To acquire a Client Key, you'll need to file a "Getting Help Request" (GHR). To do so, go to This Page. Select, the "other" option, and enter the following information into the text box (as described by Senior Game Moderator Frisbeeteria, with an associated notice):

Frisbeeteria wrote:You MUST include:

Please send me a client key
<Your nation name>
<Your region name> (and your requesting nation MUST reside in that region)
<The reason for the script> (can be as simple as "Recruiting")

It rarely takes more than a day or two, but wait patiently - we'll get to it eventually. If you pester us with "WHERE THE HELL IS MY CLIENT KEY" tasks, it's very annoying and will most likely get you an irritated response or even a warning for spamming.

When the Moderation Team processes your request, they'll send you back a Voice of Mod telegram containing your Client Key. Please note, Client Keys are region-specific. If you wish to recruit for a new region, you need to acquire a new key.

---

Clients

Creators of any clients I may have missed- please telegram me information if you wish it included!

So- You've written an awesome telegram, gotten your TG ID and your secret key, and acquired/dug up a client key from the mods. What now? How do you put all these pieces together? Is there a set bonus for equipping them all at once? (Answer: No.) Why, you need a Client!

"Huh? What's a Client?"

An API client is a program that uses all this information to actually send your telegrams. I'll shortly present several publicly available ones, along with the very basics of how to make your own. Public Clients are not officially supported by Nationstates, but are a user-based creation. That said, all those listed on the site should comply with the rules. Each linked client has it's own instructions on where exactly to input the codes you obtained above.

So what clients are available?

---

Something Old

Auralia's NationStates AutoTelegram

A free and open source client for the NationStates Telegrams API.

+ Features that work have worked for a while, and will likely continue to work
+ On-site instructions for use
+ Sends telegrams while not using NS
> Requires .NET framework 4
> Windows only
- NO LONGER SUPPORTED (bugs and errors will not be fixed)
- Not all features work entirely

See below for Auralia's newer web-based client.

---

Something New

Agadar's Telegrammer

This desktop application allows you to automate sending telegrams to other nations, making it useful for recruiting, World Assembly campaigning, region-wide telegramming, and so forth. It only requires Java to be installed on your machine in order to run.

+ Currently supported
+ Very easy to use
+ Sends telegrams while not using NS
+ Includes advanced filters
+ Filters and recipient history persist through restart

AND

South Jarvis' pyNSrecruit

An open-source cross-platform desktop application to use the NationStates Telegram API to automatically telegram nations. It is designed to be robust, minimising the prevalence of crashes, and powerful, with a wide range of capabilities.

+ Currently supported
+ Easy-to-read guide to Client use prominently linked
+ Sends telegrams while not using NS
+ Very expansive targeting options
> Requires user to download Python 3 to use

AND

Imperium Anglorum's Communiqué

Communiqué is a simple open-source way to send telegrams through the Telegram API. It is built using Java (you will need an up-to-date version of Java), so it will probably run on your home computer! It has two versions, Communiqué-proper and Marconi, a GUI and a CLI respectively. Marconi is designed to run headless and will only run if you provide it with a proper Communiqué configuration file (which are easily generated by saving using Communiqué itself). It is designed on the open-source JavaTelegram library (which I also build and maintain) and is open for other programmers to extend and build off. It is on its seventh version.

+ Endlessly customizable
+ Easy-to-read guide to Client use prominently linked
+ Sends telegrams while not using NS
+ Filter system mirrors NS'
+ Checks for an skips most undeliverable recipients
> Automatically generates the option to negate nations to which a campaign has already been delivered

AND

Auralia's nstg-web

nstg-web is a free and open source web application that allows you to easily send telegrams to a list of NationStates nations defined using a powerful query language called Telegram Recipient Language.

+ Complex filtering options
+ Savable recipient history
+ Savable configurations
> Is a web app. This means no admin access/downloading/running are necessary, but also requires the user to have the page open.

---

Something Widely Followed

Eluvatar's (Originally Afforess') NationStates++

NationStates++ (often shortened to 'NS++') is a tiny, light-weight, and open-source browser extension for NationStates. Focused on an easy-user experience, it is designed to simplify the NationStates game, provide players with more data and information to make educated decisions, and provide more powerful tools to interact with other players.

+ Contains a browser-based API client tool. No downloads needed!
+ Onboard statistics
+ Allows user to alternate sending between several "campaigns" running at once, potentially targeting different groups with different messages
> Comes with all the other features of NS++, not a standalone tool
- Relies on NS++ functioning, breaks in service have occurred
- Less instructions than other clients
- Only allows target category selection, cannot use to send telegrams to a specific region or list of nations
- Only sends telegrams while you or another listed recruiter nation are logged in to NS

---

Now how about you?

Short Answer: You can, of course, make your own TG API Client, if you have the technical knowledge and time to do so! Make sure you follow the telegram-specific rate limits and other associated regulations found here

Extra reserved.

Sounds awesome Souls! I (like many other players) have often found difficulty with using the API telegram system so having an easy to read guide will massively help a lot of new players (and more experienced technical dunces like myself).

Got some new information from the lovely mods, and talked to a few friends who've recruited more recently. Cue the next round of renovations!

I'm also looking to speak with anyone who's made an API client for the NS TG API, and is willing to give me just a few minutes of their time. Please telegram me if you are willing!

I've reached a stage where I'm comfortable to say this guide is now OPEN FOR BUSINESS!!!

That's not to say further changes cannot be made, and in fact there are several areas that I'm still looking to expand a bit, but I feel as though someone can currently use this guide to send API telegrams, meaning it's in working condition!

Please, post any questions, comments, or noticed errors, and feel free to link this wherever you wish!

I personally use a mix of Auralia's and South Jarvis's handiwork. Auralia's client is great if you happen to be targeting a very specific sub-group, such as delegates, whereas South Jarvis's client is probably the best NS recruiting client out there. If you own a server it works even better. I personally recommend staying away from NS++ for recruiting.

The Silver Sentinel wrote:I personally use a mix of Auralia's and South Jarvis's handiwork. Auralia's client is great if you happen to be targeting a very specific sub-group, such as delegates, whereas South Jarvis's client is probably the best NS recruiting client out there. If you own a server it works even better. I personally recommend staying away from NS++ for recruiting.

Each client has it's own ups and downs. I've tried to list some of the largest ones, and color code them red and green for easy differentiation between good and bad. Some of Auralia's functions no longer...function. You'll note I have no red text for South Jarvis', but the fact it has to be downloaded and installed may pose a problem for some users. While NS++ may have flaws in reliability, running time, and target customization, it's also easy to use, doesn't require downloading or installing any programs (something not everyone can do on their computer), allows you to run several "campaigns" at once, and has it's own onboard statistics. I figured it was not at all my place as a guide to judge one better than the others - merely list them all, along with their respective flaws and strong points.

Excellent work! I would have loved a guide like this when I started using the API. Now it'll be a much easier process for many people.

Regarding S synonyms for message, statement might make a good match.

Voltrovia wrote:Excellent work! I would have loved a guide like this when I started using the API. Now it'll be a much easier process for many people.

Regarding S synonyms for message, statement might make a good match.

Thank you!

Oh my, that's perfect. Will edit!

Changelog 9/2/15 - Clients Section

- Added Imperium Anglorum's Communiqué to the client listing

- Guest Writer HMS Unicorn has been quoted under "Now how 'bout you?" with more detailed guidlines to making your own API client. Thank you!

Thanks, very helpful.

Grammar check:

Ever-Wandering Souls wrote:I'll shortly [present?] several publicly available ones, as well as the very basics of how to make your own.

Omigodtheykilledkenny wrote:Thanks, very helpful.

Grammar check:

Ever-Wandering Souls wrote:I'll shortly [present?] several publicly available ones, as well as the very basics of how to make your own.

Thanks for the catch! The second one was some bastard child of "as well" and "along with"

Need for RO edits noted, update coming when time is available.

Edited to include Officers Only and Communications Officers Only regional settings, as well as Adgar's Telegrammer (new client). As always, if you spot any errors, have a client you want added, etc, just let me know by posting here or telegramming me.

-Souls

Communiqué can now be used for recruitment. In fact, I've been using it for recruitment in Europe for the last four months. It's also no longer in development and has been released. I also don't believe that it requires any more user input than other clients anymore. Significant changes have occurred between version 2 and the current version, 6.

It is also probably important to include some information on OS compatibility. Auralia's program only runs on Windows. South Jarvis' python program requires Python. Both my and Agadar's program just need Java 8.

I've tried Telegrammer, and I do not believe that it is possible to send a telegram to one specific nation. It is only possible to address groups (which, admittedly, was a problem when I had to allow for Communiqué to both address some specific nation and various groups.

Imperium Anglorum wrote:Communiqué can now be used for recruitment. In fact, I've been using it for recruitment in Europe for the last four months. It's also no longer in development and has been released. I also don't believe that it requires any more user input than other clients anymore. Significant changes have occurred between version 2 and the current version, 6.

It is also probably important to include some information on OS compatibility. Auralia's program only runs on Windows. South Jarvis' python program requires Python. Both my and Agadar's program just need Java 8.

I've tried Telegrammer, and I do not believe that it is possible to send a telegram to one specific nation. It is only possible to address groups (which, admittedly, was a problem when I had to allow for Communiqué to both address some specific nation and various groups.

Further edits made. See my TG for one note.

Hey, Souls. Thank you for updating the OP and for adding my client to it! I'll throw in a link to this thread from my client's thread right after this post.

I do have two remarks, though. You noted in my client's description that it has "somewhat limited targeting options at present". I'm not entirely sure how you came to that conclusion, as I'm pretty sure my client supports just about the greatest number of targeting options available out of all clients. Correct me if I'm wrong: I have only glanced over the other clients.

As for the "still in development" part: the current version (1.2.0) is the final version for now. It has all the features I personally demand of it, so unless features are requested by others or bugs are discovered, I will only sparsely be tinkering on it as I already deem it almost as complete as it can be.

Agadar wrote:Hey, Souls. Thank you for updating the OP and for adding my client to it! I'll throw in a link to this thread from my client's thread right after this post.

I do have two remarks, though. You noted in my client's description that it has "somewhat limited targeting options at present". I'm not entirely sure how you came to that conclusion, as I'm pretty sure my client supports just about the greatest number of targeting options available out of all clients. Correct me if I'm wrong: I have only glanced over the other clients.

As for the "still in development" part: the current version (1.2.0) is the final version for now. It has all the features I personally demand of it, so unless features are requested by others or bugs are discovered, I will only sparsely be tinkering on it as I already deem it almost as complete as it can be.

Your client has a fairly limited set of filters. PyNS for example, allows the input of specific nations, and building custom targets with even such things as government category. Communique, IIRC, also allows the input of nations at least.

In development removed!

Ever-Wandering Souls wrote:

Agadar wrote:Hey, Souls. Thank you for updating the OP and for adding my client to it! I'll throw in a link to this thread from my client's thread right after this post.

I do have two remarks, though. You noted in my client's description that it has "somewhat limited targeting options at present". I'm not entirely sure how you came to that conclusion, as I'm pretty sure my client supports just about the greatest number of targeting options available out of all clients. Correct me if I'm wrong: I have only glanced over the other clients.

As for the "still in development" part: the current version (1.2.0) is the final version for now. It has all the features I personally demand of it, so unless features are requested by others or bugs are discovered, I will only sparsely be tinkering on it as I already deem it almost as complete as it can be.

Your client has a fairly limited set of filters. PyNS for example, allows the input of specific nations, and building custom targets with even such things as government category. Communique, IIRC, also allows the input of nations at least.

In development removed!

My client also allows the input of specific nations, and has targets such as new WA delegates, new WA nations, nations in embassy regions, nations in regions with or without specific tags, and so forth. Hence, I don't see how the "somewhat limited targeting options" is justified.

Agadar wrote:

Ever-Wandering Souls wrote:
Your client has a fairly limited set of filters. PyNS for example, allows the input of specific nations, and building custom targets with even such things as government category. Communique, IIRC, also allows the input of nations at least.

In development removed!

My client also allows the input of specific nations, and has targets such as new WA delegates, new WA nations, nations in embassy regions, nations in regions with or without specific tags, and so forth. Hence, I don't see how the "somewhat limited targeting options" is justified.

I stand corrected, I didn't see nations (include) earlier. Line removed.

Agadar wrote:My client also allows the input of specific nations, and has targets such as new WA delegates, new WA nations, nations in embassy regions, nations in regions with or without specific tags, and so forth. Hence, I don't see how the "somewhat limited targeting options" is justified.

Okay. How does that work?

Ever-Wandering Souls wrote:

Agadar wrote:
My client also allows the input of specific nations, and has targets such as new WA delegates, new WA nations, nations in embassy regions, nations in regions with or without specific tags, and so forth. Hence, I don't see how the "somewhat limited targeting options" is justified.

I stand corrected, I didn't see nations (include) earlier. Line removed.

Appreciated. Thank you, and thank you for your hard work of maintaining this excellent guide.

Imperium Anglorum wrote:

Agadar wrote:My client also allows the input of specific nations, and has targets such as new WA delegates, new WA nations, nations in embassy regions, nations in regions with or without specific tags, and so forth. Hence, I don't see how the "somewhat limited targeting options" is justified.

Okay. How does that work?

How does what work, exactly?