API Recruiting questions

[Strawberrry Fields]

So roughly two years ago I requested an API Client Key from the admins/mods which got approved, but I never got around to using it.

Will the one I have still work? Or did it expire? (It's called "Hippy Haven Recruiting")

Also if someone could point me to where a guide in using this client key is. As i'm not really sure how it works.

Thanks for your time.

[Laevendell]

Here's the API documentation for the telegrams part: https://www.nationstates.net/pages/api.html#telegrams
I don't think the client keys expire.

[Ever-Wandering Souls]

Hello! As far as I can tell you, yes, your key will still work. Now, to use it, the main thing you need is a client, some program to use it. If you have NS++, and are a founder, delegate, or recruitment officer as appointed by one of the former, you can plug the details in there and follow the included instructions. Assuming, however, that one of more of those conditions do no apply, there's a very basic API client located at http://nspostmaster.com/mass_telegram.html . You can, of course, code your own client, following the rules linked by the previous poster, if you have the skill, but (no offense, I don't either), I'm assuming you do not. So how do you use that site I linked, huh? Well, the first step is to write the recruitment Telegram you wish to send. Write it exactly as you wish it to be sent (including any @nation@ or @region@ inserts), and then mark it as recruitment. In the address box, enter "tag:api". Send the telegram. Now, go to sent telegrams, and click on the telegram you just sent. Listed there will be two more code's you'll need. Now, let's go to link I sent. First, you need to enter targets. There's tools built in to target region, and you can also enter as long a list as you wish of nations. You can also visit some of the API shards to get nation names - for example, https://www.nationstates.net/cgi-bin/ap ... newnations lists the 50 most recently created nations. They're formatted in a way you can copy-paste directly into NS Postmaster. There currently does not exist a shard for refounded nations. If you want to target categories like "refounded" or "active," you'll have to use the more complex NS++ recruitment tool, or any other tool that includs those options. SO now you have nations listed, what's next? Plug in your client key, and the other two codes from that telegram you sent, the telegram ID and secret key. You've already made the telegram permanently marked as recruitment by marking it when yo first sent it, but it doesn't hurt to check the box again here. Then, hit start! It'll gradually process the list of nations above, as the rate limit allows.

Hope that helped! ANy further questions?

- Ever-Wandering Souls

[Strawberrry Fields]

Hey thanks a bunch Ever-Wandering Souls, that was very helpful! The very user friendly explanation I was hoping for as i'm not very good with this kind of thing. I believe I have it up and running.

[Ever-Wandering Souls]

Anytime! Good luck. One thing I forget to mention, and definitely should, is to make sure you're only using one client at a time - each client should be designed not to exceed the legal rate limit for telegram API requests, but if you use more than one at once, you will exceed that limit.

[Strawberrry Fields]

Hmm I seem to be having an issue with it.

I thought it was working but when I added some of my nations to the list, they never got the telegrams. (I double checked to make sure they wouldn't block it)

I plugged the client key, Telegram Id, and secret key in, used the new nation generator thing to get nation names. Hit send, it shows a clock countdown and starts removing names from the list in real time. Looks like it should be working, but none of my nations I added to the list got the recruitment telegram for some reason.

Not sure if this is a postmaster issue, or if my client key isn't valid, I don't use NS++ if that's a factor here.

[Ever-Wandering Souls]

Hmm I seem to be having an issue with it.

I thought it was working but when I added some of my nations to the list, they never got the telegrams. (I double checked to make sure they wouldn't block it)

I plugged the client key, Telegram Id, and secret key in, used the new nation generator thing to get nation names. Hit send, it shows a clock countdown and starts removing names from the list in real time. Looks like it should be working, but none of my nations I added to the list got the recruitment telegram for some reason.

Not sure if this is a postmaster issue, or if my client key isn't valid, I don't use NS++ if that's a factor here.

It might be postmaster. When I used it to try to send about 10,000 telegrams a few months back, only about three sent. The rest disappeared from list there, but didn't show any signs of sending. I assumed at the time that, as a tool created by the creator of NS++, it was somehow skipping any NS++ created nations...but later, after asking the person it was handed off to, they never did find any evidence in the code of it doing so. Never got a great answer there

IMHO, one of the most versatile and easiest to use ones is the one built into NS++ - but that does mean either getting used to a bunch of other new features, or turning almost all the features off and just using that one It may be worth considering getting it. If you search Technical with some keywords like API, Telegram, and/or client, you may find a few others as well - they should rely on the same principle, though they'll likely be a bit old.

- For example, viewtopic.php?f=15&t=183419&hilit=recruitment+telegram+API+client this one. Never used it, but it looks a bit more technical, and is likewise no longer supported, though still available.

[Strawberrry Fields]

Aight, so I broke down and got NS++ for my less used browser.

I see where I would be able to recruit, but it's only for founders or delegates.

I got the Key for this nation, but i'd need to use my other nation Forever Fields (founding nation) to do the recruiting. Do I just set up a new API recruitment TG to get a new TGID and Secret Key, and use the same client key? Or do I need to request a new one?

[Ever-Wandering Souls]

Aight, so I broke down and got NS++ for my less used browser.

I see where I would be able to recruit, but it's only for founders or delegates.

I got the Key for this nation, but i'd need to use my other nation Forever Fields (founding nation) to do the recruiting. Do I just set up a new API recruitment TG to get a new TGID and Secret Key, and use the same client key? Or do I need to request a new one?

As far as I know, you should be able to use the same client key. You *may* need to resend the tag:API telegram on the other nation.

Alternatively, you can use your founder nation to add this nation as a "recruitment officer" which gives it access as well.

[Strawberrry Fields]

Yea, just noticed that, I added myself, seemed easiest. I think I have it going for real this time.

Do you (or anyone) know if I need to be logged onto this nation to have it running?

Also, I assume i'm only supposed to do a max of 100% Allocation. Does it make more sense to just do one recruit at 100%?

Or if I do 50% new nation and 50% refound, do both campaigns go?

[Ever-Wandering Souls]

Yea, just noticed that, I added myself, seemed easiest. I think I have it going for real this time.

Do you (or anyone) know if I need to be logged onto this nation to have it running?

Also, I assume i'm only supposed to do a max of 100% Allocation. Does it make more sense to just do one recruit at 100%?

Or if I do 50% new nation and 50% refound, do both campaigns go?

Yes, you've got to be logged in. If you use several nations, might want to add them all as recruitment officers. Any listed nation will run the campaigns regardless of who started them.

Allocation can exceed 100% - setting two at 100 just gives the same effect as setting each at 50. It's a portion-of-the-total-sum deal IIRC.

Yes. Since you can only send one TG at a time, what it does is alternate which pool it targets. So if you've got it split evenly, 1 of every 2 telegrams sent goes to each. If you have one set at 80 and one at 20, out of five telegrams sent, four are for one campaign, and one for the other.

[Strawberrry Fields]

Oh aight cool. So when you say "Any listed nation will run the campaigns regardless of who started them."

If I added another player's nation, would the campaigns run still when their online? Assuming they had NS++

Again thanks a bunch for answering my questions, you've been very helpful!

[Ever-Wandering Souls]

Oh aight cool. So when you say "Any listed nation will run the campaigns regardless of who started them."

If I added another player's nation, would the campaigns run still when their online? Assuming they had NS++

Again thanks a bunch for answering my questions, you've been very helpful!

Yep! I'm not even sure if they *have* to have NS++, that'd be a better question to ask in that thread.

You're very welcome!

[Strawberrry Fields]

Ugh, something is still not working properly. >_<

I founded a new nation to verify my telegrams were going through, and I even saw it say it was telegramming my new nation, but the new nation never got the tg...

I think I need mod help, maybe my client key did expire? Anyway to tell if nations are actually getting these "sent" telegrams?

[Ever-Wandering Souls]

Ugh, something is still not working properly. >_<

I founded a new nation to verify my telegrams were going through, and I even saw it say it was telegramming my new nation, but the new nation never got the tg...

I think I need mod help, maybe my client key did expire? Anyway to tell if nations are actually getting these "sent" telegrams?

How did you found the new nation? Did it have recruitment TG's blocked? It may be queuing too, there's a whole system

Also, you can go to the sent API telegram, and click on "delivery reports" to see statistics about how many were received.

[Strawberrry Fields]

Well you can be logged into a nation per web browser.

So I got NS++ just for Fire Fox, and am logged on as SF, then on google chrome, I created a new nation. I saw on my SF nation say it was telegraming that nation. But it never got it, and nothing was blocked. I just doubled checked, it still hasn't come.

And sending the API tg just sets up the template, under delivery reports is where you get the telegram ID and secret key. Doesn't say how many where received or sent. Unless I need to send another telegram or something?

On the NS++ recruit thing it says it's sent about 20, but nothing about receiving there either. Considering my nation didn't get it, but has gotten several other Api tgs, I don't think mine are sending.

[Ever-Wandering Souls]

Well you can be logged into a nation per web browser.

So I got NS++ just for Fire Fox, and am logged on as SF, then on google chrome, I created a new nation. I saw on my SF nation say it was telegraming that nation. But it never got it, and nothing was blocked. I just doubled checked, it still hasn't come.

And sending the API tg just sets up the template, under delivery reports is where you get the telegram ID and secret key. Doesn't say how many where received or sent. Unless I need to send another telegram or something?

On the NS++ recruit thing it says it's sent about 20, but nothing about receiving there either. Considering my nation didn't get it, but has gotten several other Api tgs, I don't think mine are sending.

Below those codes, t doesn't show something like

"3,991 Delivered [+]
[?]1,317 Read (33.00%)
[?]
25 No Such Nation [+]
[?]
157 Blocked by Category [+]"

...Anyways, sorry, but I don't have any way of looking behind the scenes for you here. You could assume it's running and you just didn't get it with that nation for some reason or another, you could go ask about it in the NS++ thread (though with how that's been recently, you may not get a reply any time soon), you can try to find another client, or you can hope the Postmaster is sending most of them. That's about the best I can say.

[Strawberrry Fields]

It doesn't show that below the codes. I've sent tg using stamps and seen what your referring to, but it's not listed on the API delivery reports for some reason.

I guess i'll try that thread or make a request for a new client key.

[Strawberrry Fields]

Heh it turns out my Client Key was expired! >_<

I got a new key and both the postmaster site and NS++ recruitment now work!

[Ever-Wandering Souls]

Heh it turns out my Client Key was expired! >_<

I got a new key and both the postmaster site and NS++ recruitment now work!

Awesome, glad everything is going well for you!