[NOW OPEN] *THE* Simple Guide to Sending Telegrams via API

[Ever-Wandering Souls]

Welcome, leaders, recruiters, and everyday citizens of NS, to....

Souls' Simple Syllabus to Sending Scores of Speedy Statements!
(You find an S synonym for telegrams!)

aka

What is the "API" thing and how do I use to send lots and lots of Telegrams with very little effort?

---

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

---

General FAQ's

What is "The Telegram API?"

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

"API" is an acronym for "application program interface." NS API documentation, found Here, states "The NationStates API allows external sites to collect data about the game world. You can access it with your own scripts to gather information and produce extended reports or analysis. It is faster than scraping regular HTML pages, easier on our servers, and the data format is guaranteed not to change unexpectedly." Specifically, "The Telegrams API exists to support things that aren't possible using the in-game Mass Telegram system; for example, automatically targeting telegrams at nations with capitalist leanings in regions with more than 50 residents. It's also possible to duplicate what the in-game system offers you via Telegram Stamps, only slower." The Telegram API is the only legal avenue for automating the sending of telegrams, and is subject to various restrictions. For more technical information, see Here.

(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

[Ever-Wandering Souls]

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:

>Any Resident (Any Nation in the region can send API, stamp, or manual recruitment telegrams on its behalf)

>Specified Nations Only (Nations added below and in the region can send API, stamp, or manual recruitment telegrams on its behalf)

>Regional Admin Only (Only the Founder and an Executive Delegate can send API, stamp, or manual recruitment telegrams on the region's behalf)

>Officers Only (Only Regional Officers can send API, stamp, or manual recruitment telegrams on the region's behalf)

>Communications Officers Only (Only Regional Officers with Communications authority can send API, stamp, or manual recruitment telegrams on the region's behalf)

>API Only (only the API system [regulated by rate limits and stopped it breaks rules] can be used to send recruitment telegrams for the region

>No-one (Nobody can recruit for this region)

- 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.

[Ever-Wandering Souls]

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):

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.

I just cleaned up the Client Key database. I removed

• Anyone whose script hasn't been active for a year or more
• Anyone who had requested a key three or more months ago and never used it

We don't mind issuing Client Keys to players who will use them, but it's annoying and a fair amount of work to issue keys to people who just think it's cool to have a key.
Please don't request a Client Key unless you a) know how to use it and b) plan to use it.

Thanks,
The NS Game Mods

---

Keep reading below to learn how to put these codes to work!

[Ever-Wandering Souls]

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

The process of making "calls" to the NS API is exactly the same as the process that happens when you use your browser to visit a link.

When you click the following link:
cgi-bin/api.cgi?a=sendTG&client=CLIENTKEY&tgid=TGID&key=TGKEY&to=NATION
you make a "call" to the TG API, to send a telegram with ID (TGID) and key (TGKEY), using your regional client key (CLIENTKEY), to nation (NATION). Every time you click the link, you make another manual call to the TG API. Note that you do not need to be logged into NS, or even have a nation, to make the API call. All you need is the link and being able to "click" it.

(Note: until you replace CLIENTKEY, TGID, etc. with valid values, the responses you'll be receiving will be error messages and no telegrams will be sent.)

Therefore, the foundation for any telegramming script is having a programmatic way for making such "clicks" to links. Probably unsurprisingly, there are a myriad of ways for doing this. One standard approach would be to use a program called cURL: http://curl.haxx.se/ . This is a standard piece of software whose purpose (one of the main ones anyway) is to make HTTPS requests, which is exactly what "virtual URL clicks" are. For instance, if you have a command line and you type
curl --user-agent YOURUSERAGENT cgi-bin/api.cgi?a=sendTG&client=CLIENTKEY&tgid=TGID&key=TGKEY&to=NATION
this is essentially equivalent to opening your browser, pasting the link in the address line, and hitting enter.

Important note: The cURL call includes a "user agent". This is information included in the HTTPS call that is used to identify who is making the call. When you visit URLs from your browser, a default (and not terribly informative) user agent is provided automatically. cURL, on the other hand, by default sends no user agent information, unless you ask it too.

When you use an automated tool to make TG API calls, you need to make sure not just that you are providing a user agent, but also that it's an informative one. The API terms of use says "You must set your script's UserAgent to something informative, such as the URL of your site. This allows us to contact you if something goes wrong with your script." The consequences of noncomplinace can be founds discussed by [violet] HERE.

cURL is available in many operating systems, including Windows, Linux, and MacOS. Moreover, it can be called from many programming languages popular for web programming, such as Java, PHP, and Python.

Again, that's just a very basic (though also very important) example. You could also use either alternative programs/libraries, or even a fundamentally different approach. To mention an example of the latter, you could even have a browser script that automatically opens API links in a tab.

That's the foundation. You are going to need a few more components on top of that. One is some sort of timer, to schedule the requests so that your script does not violate the API rate limits. Another is some way of providing your "URL clicker" the URLs to click. There is a very large and very diverse set of methods for doing these tasks, so those are on you, depending on your usage and personal preference.

[Ever-Wandering Souls]

Extra reserved.

[Luxdonia]

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).

[Ever-Wandering Souls]

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!

[Ever-Wandering Souls]

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!

[The Silver Sentinel]

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.

[Ever-Wandering Souls]

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.

[Voltrovia]

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.

[Ever-Wandering Souls]

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!

[Ever-Wandering Souls]

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!

[Omigodtheykilledkenny]

Thanks, very helpful.

Grammar check:

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

[Ever-Wandering Souls]

Thanks, very helpful.

Grammar check:

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"

[Ever-Wandering Souls]

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

[Ever-Wandering Souls]

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

[Imperium Anglorum]

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.

[Ever-Wandering 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.

Further edits made. See my TG for one note.

[Agadar]

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.

[Ever-Wandering Souls]

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!

[Agadar]

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.

[Ever-Wandering Souls]

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.

[Imperium Anglorum]

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?

[Agadar]

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.

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?