[APP] NationStates AutoTelegram

[Auralia]

NationStates AutoTelegram has been replaced by nstg-web and is no longer maintained.

NationStates AutoTelegram

Summary
NationStates AutoTelegram is a free and open source client for the NationStates Telegrams API.

Documentation

System Requirements

• The .NET Framework 4 Full
• A NationStates nation
• A NationStates API client key
• A NationStates telegram ID and secret key

Tutorial

1. Obtain an API client key, and type it into the API client key textbox on the Telegram tab page.
   
   • You can request an API client key from the NationStates moderators by submitting a Getting Help Request from the nation requesting the key.
     
     • You must provide a your region's name (preferably in "quotes", no initials) and your nation name.
     • You must also provide a short description (e.g. "For <regional> recruitment of both new and existing nations.").
     • The moderators don't want or need a copy of your proposed telegram, just a one-line description.
     • If your request is approved, you will receive a client key by telegram.
     • A client name will be provided, usually "@<region_name>@<nation_name>".
     • Only one API key can be issued per region. If someone already has your regions, you will have to work it out with the key owner. If they've died off, the mods will delete the old key and issue a new one.
     • The same key can be used for both recruitment and campaigning. Don't ask for a second key.
   • Do not share your client key with anyone.
   • If you obtain a new telegram ID and secret key (see below), you do not need to request a new client key.
2. Obtain a telegram ID and secret key, and type them into the Telegram ID and Secret key textboxes respectively on the Telegram tab page.
   
   • You can obtain a telegram ID and secret key by sending your telegram on NationStates to "tag:api". Make sure that you mark the telegram as a recruitment or WA campaign telegram if appropriate. After sending the telegram, you will receive a telegram ID and secret key.
   • Do not share your secret key with anyone.
   • If you wish to change the text of your telegram, you must obtain a new telegram ID and secret key.
3. Indicate whether the telegram associated with your telegram ID is a recruitment or non-recruitment telegram by clicking the appropriate radio button, so that the appropriate rate limit can be selected.
   
   • The rate limit for recruitment telegrams is currently 1 telegram every 180 seconds, while the limit for non-recruitment telegrams is 1 telegram every 30 seconds.
4. Enter the recipients of your telegram into the Recipients textbox.
   
   • Recipients must be entered using the following format:
     
     • nation:<nation> : sends telegram to specified nation
     • region:<region> : sends telegram to all nations in specified region
     • tag:<tag> : sends telegrams to all nations in regions with the specified tag
     • special:(all, members, delegates, new) : sends telegrams to (all nations, all World Assembly members, all World Assembly delegates, 50 new nations)
     • recruitment:new : enables recruitment mode for new nations, which sends telegrams to new nations as they are created until the program is manually stopped; in the future this mode may support refounded nations through recruitment:refounded
   • Multiple recipients can be specified, separated by commas (e.g. nation:Auralia, nation:Christian Democrats sends telegrams to Auralia and Christian Democrats)
   • Appending a negative sign to any recipient specifically excludes that recipient, even if explicitly included elsewhere (e.g. region:Catholic, -nation:Auralia will send telegrams to all nations in Catholic except Auralia).
   • The following are common usage cases:
     
     • Mailing list: nation:<nation 1>, nation:<nation 2>, ... nation:<nation n>
     • GA campaign: special:delegates, -tag:No GA Campaigning (note that the No GA Campaigning tag may be removed some time in the future due to the new telegram system's spam controls)
     • SC campaign: special:delegates, -tag:No SC Campaigning (note that the No SC Campaigning tag may be removed some time in the future due to the new telegram system's spam controls)
     • General recruitment of new nations: recruitment:new
5. Send your telegrams by clicking the Start button on the Status tab page.
   
   • You can cancel the telegramming process at any time by pressing Cancel. There may be a delay before the process is cancelled since it is running on a separate thread.
   • You can pause the telegramming process by clicking Pause. Click Resume to resume the process. Again, there may be a delay before the process is paused or resumed.
   • You should probably save a copy of the log after the process completes.

Technical Information
This program reports its UserAgent to the NationStates API as follows:

Code: Select all

NationStates AutoTelegram <version> (maintained by Auralia, currently used by client key <client key>)

Downloads
The latest version (0.4.0) can be downloaded from here. The source code is available on GitHub.

Changelog

• Version 0.4.0:
  
  • Support for telegrams API
  • Added recruitment mode
  • Recipient input changes
  • UI changes
• Version 0.3.0:
  
  • UI redesign
  • Bug fixes
  • Performance improvements
  • Simplification and reformatting of code base
  • Updates to readme and license
  • Certain features removed
• Version 0.2.2:
  
  • Bug fixes
• Version 0.2.1:
  
  • Bug fixes
• Version 0.2:
  
  • %NATION% menu option
  • %REGION% feature and menu option
  • WA nations option on recipient dialog
  • Pause button
  • Cosmetic changes
  • Bug fixes
• Version 0.1:
  
  • Initial public release

Copyright and License
Copyright (C) Auralia.

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

You must read and understand the NationStates mass telegramming and scripting rules before using the Software. You agree that the author of the Software is not responsible for any breaches of NationStates rules resulting from your use of the Software.

This program uses icons from the Silk Icon Set and the Tango Desktop Project.

[Auralia]

--- RESERVED ---

[Auralia]

--- RESERVED ---

[Fischistan]

Interesting.
Does it check for failed security checks/spam timeouts and reattempt failed telegrams?
Also, can I ask how you managed to decompress .gz files using the .NET library?

[Auralia]

Does it check for failed security checks/spam timeouts and reattempt failed telegrams?

If a telegram fails - for whatever reason, including non-existent nations, security checks, etc. - it logs the error and moves on. Spam timeouts aren't a problem, since the program must wait 20 seconds between each telegram.

Also, can I ask how you managed to decompress .gz files using the .NET library?

System.IO.Compression. Here's a brief snippet from the program:

Code: Select all

                FileStream open = new FileStream(pathInfo.FullName + "regions.xml.gz", FileMode.Open);
                GZipStream gzip = new GZipStream(open, CompressionMode.Decompress);

                File.Delete(pathInfo.FullName + "regions.xml");
                FileStream save = new FileStream(pathInfo.FullName + "regions.xml", FileMode.CreateNew);
                gzip.CopyTo(save);

[Fischistan]

System.IO.Compression. Here's a brief snippet from the program:

Code: Select all

                FileStream open = new FileStream(pathInfo.FullName + "regions.xml.gz", FileMode.Open);
                GZipStream gzip = new GZipStream(open, CompressionMode.Decompress);

                File.Delete(pathInfo.FullName + "regions.xml");
                FileStream save = new FileStream(pathInfo.FullName + "regions.xml", FileMode.CreateNew);
                gzip.CopyTo(save);

Ah, thank you sooooooo much. I was using another method that involved a byte array buffer and it was just terribly complicated. Hopefully I can get this to work the same way in VB.

[Diol]

Could this send telegrams to all nations in your dossier?

[Andacantra]

Could this send telegrams to all nations in your dossier?

Presumably, if it lets you enter a list of nations - you could just get the list using the advanced dossier.

I'm not going to think about the implications for now, but this certainly seems like a nifty tool.

[Not a pipe]

Does it work on Mono?

[Auralia]

Does it work on Mono?

Maybe. I haven't tested it.

[Auralia]

Version 0.1 has been released. There shouldn't be any show-stopping bugs, but if you find any, please tell me immediately and I'll fix them ASAP.

[Moronist Decisions]

Incidentally, would this take account of registered school classes who can't be TGed? (with the "class" tag)?

[Auralia]

Incidentally, would this take account of registered school classes who can't be TGed? (with the "class" tag)?

It would try to TG them, fail, log the error and move on. This solution takes much less time, for both me to implement and the end-user to, well, use, than checking every nation to see if they're in a school region.

[Auralia]

Am I to understand that nobody is interested in this, given that it's only received two downloads?

Ah, well, I still plan on using it.

[Crushing Our Enemies]

I like it! I must have been one of the two.

[Nullarni]

I am interested as well. I just haven't had time to download it, (I am posting this from my phone, in case you were wondering why I don't just do it now.) ...And I was going to give it a couple days for any bugs to be worked out.

[Glen-Rhodes]

Very nice! You should add macros as a menu item, though. Also, the program consistently hangs on my PC when loading the font screen. I suspect this is because I have a large number of fonts, and the program loads the actual font faces, rather than just a simple list of them.

[Auralia]

You should add macros as a menu item, though.

Could you give more detail as to what you mean? A macro to automate the entire process, or just to set the recipient information?

Also, the program consistently hangs on my PC when loading the font screen. I suspect this is because I have a large number of fonts, and the program loads the actual font faces, rather than just a simple list of them.

Yes, the dialog does load the actual font faces, but I don't think I can change that. The FontDialog control doesn't seem to have an option to do that.

[Auralia]

I am interested as well. I just haven't had time to download it, (I am posting this from my phone, in case you were wondering why I don't just do it now.) ...And I was going to give it a couple days for any bugs to be worked out.

Well, I don't think there are any bugs, given my testing, but I won't know for certain until a decent number of end-users test it out as well. That would include you...

[Glen-Rhodes]

Could you give more detail as to what you mean? A macro to automate the entire process, or just to set the recipient information?

I don't know why I called it a macro. I meant to say variable. The %NATION% variable, for example.

Yes, the dialog does load the actual font faces, but I don't think I can change that. The FontDialog control doesn't seem to have an option to do that.

Pity. I don't need to change the font anyways. It's an isolated problem. I literally have over 1,000 fonts.

[Auralia]

I don't know why I called it a macro. I meant to say variable. The %NATION% variable, for example.

Oh... yeah, that'd be easy. I'll add that to the next release.

I literally have over 1,000 fonts.

[Lemonacia]

Cheers, this'll save me a bunch of time.
All hail the code wizard!

[Fotar]

Just gave it a try....very nice and easy to use! This could be a huge help for me. Thanks!

[Syrakhstan]

I'm currently on my phone, ill be downloading and editing my post once I'm home.

[Tim-Opolis]

I'll be downloading this in a bit.

Looks good