Roll20 uses cookies to improve your experience on our site. Cookies enable you to enjoy certain features, social sharing functionality, and tailor message and display ads to your interests on our site and others. They also help us understand how our site is being used. By continuing to use our site, you consent to our use of cookies. Update your cookie preferences .
×
Create a free account

Video - Tutorial on Writing an API Script

1582898050
Nick O.
Forum Champion
I created a video that walks a user through writing an API script that summons a spiritual weapon to the battlefield. It's my first time making a vid like this, so feedback is appreciated. :) 
1582905258
keithcurtis
Forum Champion
Marketplace Creator
API Scripter
I'm only halfway through, but I had to jump back in here to say this is amazing. I wish I had had this when I started. Having each line written and explained is powerful education. Best video yet.
1582906788
keithcurtis
Forum Champion
Marketplace Creator
API Scripter
And finished. GREAT JOB! This is a complex subject that causes many people to just look at it and say "I don't understand any of this. Not even gonna try". By writing each line and explaining it thoroughly as you write, you've demystified it considerably.
1582908524
Ada L.
Marketplace Creator
Sheet Author
API Scripter
Great newbie introduction to API scripting! I could give some pointers on coding conventions and some ESNext features, but I'd just be nitpicking.
1582925908
Mino
Marketplace Creator
The API Terrifies me, but it's incredibly useful. I'm away from home at the moment, but I appreciate someone making a video tutorial! I'll have to check it when I get home, as not being able to follow along with an expected result is really the highest bar I have to trying to make my own scripts with the API.
This is wonderful, thank you for creating and sharing it! I've been learning JS but have still been hesitant to attempt anything with the API, but your explanations may be just the push I needed =D
1583015293
Nick O.
Forum Champion
Thanks for the feedback, everyone! I'm glad you found the video helpful. I will try to make more like this in the future.
1586115346

Edited 1586116057
Nick,&nbsp; Most excellent video!&nbsp; It really helped out with the basics of the java scripting language.&nbsp; I'm sure the link to the documentation about the API objects will be really helpful. Can you help me out with something though?&nbsp; I can't get the new graphics object to appear. It's seems to execute the code the whole way through and I see the special affects appear beside the selected token, but no new token for the spiritual weapon appears.&nbsp; I even did a direct paste of your code from GitHub and just replaced the URL for the thumbnail image.&nbsp; Do I need to configure a setting in Roll20 or something? I put the URL to the graphic ( <a href="https://s3.amazonaws.com/files.d20.io/images/117882473/EolMEGCe0jG08KERVH0CPA/thumb.png?15860634515" rel="nofollow">https://s3.amazonaws.com/files.d20.io/images/117882473/EolMEGCe0jG08KERVH0CPA/thumb.png?15860634515</a> )&nbsp;in my web browser (Chrome) and I got the following code.&nbsp; Should I be concerned about the "AccessDenied"?: &lt;Error&gt; &lt;Code&gt; AccessDenied &lt;/Code&gt; &lt;Message&gt; Access Denied &lt;/Message&gt; &lt;RequestId&gt; DED6C2E2C7650F10 &lt;/RequestId&gt; &lt;HostId&gt; 62+lGFITcIFgE62Yao2QZOqhpR0y4dXUASn/SCqXWQbV2gRkamVnwC2XRLZv3IhACW1n2JrSrOQ= &lt;/HostId&gt; &lt;/Error&gt; &nbsp;
1586115641
Nick O.
Forum Champion
Glad you liked it, Chris! There aren't any special settings you need to configure, you just need to have the image available in your library. Are there any errors appearing on the API script page?&nbsp;
1586117798

Edited 1586118221
Nick, I don't see any except when i was trouble-shooting and i removed the numbers and question mark after the file name in the URL.&nbsp; Then it came up with the following error, but now it's obvious the API needs those numbers. "ERROR: You must include the query string in your URL. For example, use ' <a href="https://s3.amazonaws.com/files.staging.d20.io/images/123456/med.png?12345678" rel="nofollow">https://s3.amazonaws.com/files.staging.d20.io/images/123456/med.png?12345678</a> ', not ' <a href="https://s3.amazonaws.com/files.staging.d20.io/images/123456/med.png" rel="nofollow">https://s3.amazonaws.com/files.staging.d20.io/images/123456/med.png</a> '"
1586120001

Edited 1586123918
Further update:&nbsp; I put the numbers back on the end of the URL and it's still doing the same thing where the chat message comes up, and the special effects happen, but no new icon for the spiritual weapon appears. Any ideas? So I think I figured it out - you have to be specific in two things:&nbsp; 1) Graphics moved/copied from the marketplace into the folders of "My Library" doesn't actually count as being in your library, hence the error below, and the apparent hanging of the web page "ERROR: You cannot set the imgsrc or avatar of an object unless you use an image that is in your Roll20 Library. See the API documentation for more info."&nbsp;&nbsp; 2) Using the right click pop-up menu to copy an uploaded image to a folder in your library also doesn't work.&nbsp; You have to use the 3 lines to the left of the uploaded file name under "Recent Uploads" and drag it to the desired folder in "My Library".&nbsp; Using the right-click pop-up menu results in everything running, just no token appearing. I think I can work around these two requirements. Thanks again, Nick, for your excellent video!!
1586121926
Nick O.
Forum Champion
Can you post the URL to your image?&nbsp;
1586122423

Edited 1586122485
Well, since you asked (promise not to get upset though): Lollipop (yes, I'm using your code as a gag for one of my friends playing a death cleric&nbsp; &nbsp;LOL): <a href="https://s3.amazonaws.com/files.d20.io/images/118285289/f8-ICjY32IiQk35vAfsRtg/original.png?15861206975" rel="nofollow">https://s3.amazonaws.com/files.d20.io/images/118285289/f8-ICjY32IiQk35vAfsRtg/original.png?15861206975</a> I did manage to get this working.
1586123156
Nick O.
Forum Champion
A death lollipop sounds pretty awesome, actually :) If you're still having issues, try changing the URL to this - the API usually wants to use the thumbnail versions of images.&nbsp; <a href="https://s3.amazonaws.com/files.d20.io/images/118285289/f8-ICjY32IiQk35vAfsRtg/thumb.png?15861206975" rel="nofollow">https://s3.amazonaws.com/files.d20.io/images/118285289/f8-ICjY32IiQk35vAfsRtg/thumb.png?15861206975</a>
Oops.&nbsp; I actually did switch the thumb in for the original in the file name for the code.&nbsp; I just forgot to do that in my previous post.&nbsp; It's all working good now. Thanks, Nick!