URI protocol

This URI protocol enables developers to open the wallet app in desired screen with pre-filled inputs.

If you want to open Obyte app for users then there is a obyte: protocol URI for that. If you are not aware what it is then it's like mailto: , ftp: , tel: or intents on Android. When user visits a link with that protocol then it can open the wallet app in specific screen with pre-filled inputs, helping users to insert long account addresses or amounts without the need to copy-paste them.

Opening Send screen

Following hyperlinks will open the wallet app on Send screen. These hyperlinks (without the HTML) also work when posted as chat messages.

Requesting to send funds

We can request payments with chat bot messages and we can use the same commands as links on the website. This is how it will look as a hyperlink:

<a href="obyte:ACCOUNT_ADDRESS?amount=123000&amp;asset=base">
    open Send screen with bytes
</a>

ACCOUNT_ADDRESS should be replaced with the wallet address where the funds should be sent, amount parameter should have bigInt type number in bytes (not KByte, not MByte, not GByte) and asset parameter is optional, by default it is base for bytes, but it can be issued asset unit ID too.

One website that heavily relies on this feature is Currency converter for Obyte (source code).

It is also possible to request that the payment to be done from specific address in user's wallet. Since wallet version 3.3.0, this also work from chat messages.

<a href="obyte:ACCOUNT_ADDRESS?amount=123000&amp;from_address=USER_ACCOUNT_ADDRESS">
    open Send screen with bytes
</a>

If you don't know user's account address, but still want them to user single-address account then you can use single_address=1 parameter like this:

<a href="obyte:ACCOUNT_ADDRESS?amount=123000&amp;single_address=1">
    open Send screen with bytes
</a>

Requesting to send data to AA

In order to open a Send screen with pre-filled payment and data, the data object needs to be converted into URI encoded Base64 (using JSON.stringify, btoa andencodeURIComponent) string. Many cases, when the Autonomous Agent stores data based on triggering address, we would also want the users to use single-address account, this can by adding the single_address=1 parameter. Autonomous agents can also accept nested data.

var base64 = global.btoa || require('btoa');
var data = {
    number: 1,
    foo: "bar",
    foobar: {
        foo: "bar",
    },
    "?<?>?": ["a",1,2,3],
};
var json_string = JSON.stringify(data);
var base64_string = base64(json_string);
var uri_encoded_base64data = encodeURIComponent(base64_string);

This will open Send screen, which will be pre-filled to post 10 000 bytes and data object.

<a href="obyte:AA_ADDRESS?amount=10000&amp;single_address=1&amp;base64data=eyJudW1iZXIiOjEsImZvbyI6ImJhciIsImZvb2JhciI6eyJmb28iOiJiYXIifSwiPzw%2FPj8iOlsiYSIsMSwyLDNdfQ%3D%3D">
    open Send screen with bytes and data
</a>

Requesting to post data

This will open Send screen, which will be pre-filled to post unstructured key/value pairs as data (single-address account required). Keys need to be unique.

<a href="obyte:data?app=data&amp;anykey1=anyvalue&amp;anykey2=anyvalue">
    open Send screen with data
</a>

Requesting to post temporary data

Like the above, this will open Send screen, which will be pre-filled to post unstructured key/value pairs as data (single-address account required) meant for temporary storage. Keys need to be unique.

<a href="obyte:data?app=temp_data&amp;anykey1=anyvalue&amp;anykey2=anyvalue">
    open Send screen with temp data
</a>

The data posted this way will be available on the Obyte DAG only for 1 day, after which it will be purged but the hashes of the data will stay on the DAG forever. Unlike permanent data, temporary data costs less in fees.

Requesting to post data feed

This will open Send screen, which will be pre-filled to post indexable key/value pairs as data feed (single-address account required). Keys need to be unique.

<a href="obyte:data?app=data_feed&amp;anykey1=anyvalue&amp;anykey2=anyvalue">
    open Send screen with data feed
</a>

Requesting to post a profile

This will open Send screen, which will be pre-filled to post key/value pairs as profile info (single-address account required). Keys need to be unique.

<a href="obyte:data?app=profile&amp;anykey1=anyvalue&amp;anykey2=anyvalue">
    open Send screen with profile
</a>

Requesting to post attestation

This will open Send screen, which will be pre-filled to post key/value pairs as someone else attestation profile (single-address account required). Keys need to be unique.

<a href="obyte:data?app=attestation&amp;address=ACCOUNT_ADDRESS&amp;anykey1=anyvalue&amp;anykey2=anyvalue">
    open Send screen with attestation
</a>

Requesting to post a poll

This will open Send screen, which will be pre-filled to post poll (single-address account required). Option keys can be named anything, but values need to be unique. Question parameter is also required.

<a href="obyte:data?app=poll&amp;question=How%20are%20you&amp;option1=fine&amp;option2=tres%20bien">
    open Send screen with poll
</a>

Requesting to post a AA definition

This will open Send screen, which will be pre-filled to post Autonomous Agent definition (single-address account required). The definition parameter needs to be URL encoded.

<a href="obyte:data?app=definition&amp;definition=%7B%0A%09messages%3A%20%5B%0A%09%09%7B%0A%09%09%09app%3A%20'payment'%2C%0A%09%09%09payload%3A%20%7B%0A%09%09%09%09asset%3A%20'base'%2C%0A%09%09%09%09outputs%3A%20%5B%0A%09%09%09%09%09%7B%0A%09%09%09%09%09%09address%3A%20%22%7Btrigger.address%7D%22%0A%09%09%09%09%09%7D%0A%09%09%09%09%5D%0A%09%09%09%7D%0A%09%09%7D%0A%09%5D%0A%7D">
    open Send screen with AA definition
</a>

Because most browsers support only URLs up to 2048 characters length, it is also possible to post a AA definition by making it fetch the definition from some other other address like this:

<a href="obyte:data?app=definition&amp;definition=https%3A%2F%2Fexample.com%2Fdefinition.json">
    open Send screen with AA definition
</a>

Requesting to post short text content

This will open Send screen, which will be pre-filled to post short text content (single-address account required). The content parameter needs to be URL encoded and can be maximum of 140 chars before encoding.

<a href="obyte:data?app=text&amp;content=Lorem%20ipsum%20dolor%20sit%20amet%2C%20consectetur%20adipiscing%20elit.%0AQuisque%20venenatis%20elementum%20dolor%20in%20malesuada.%20Cras%20ultrices%20ultrices%20fermentum.%20Nullam%20ac%20commodo%20ante.%20Pellentesque%20quis%20nibh%20laoreet%2C%20sagittis%20augue%20in%2C%20dapibus%20nunc.%20Etiam%20vel%20eleifend%20urna%2C%20in%20tincidunt%20turpis%20nullam.">
    open Send screen with text content
</a>

Requesting to post a system vote

This will open Send screen, which will be pre-filled to post a vote for a system variable.

<a href="obyte:data?app=system_vote&subject=base_tps_fee&value=11.5">
    open Send screen with the system vote
</a>

The subject parameter is one of op_list, threshold_size, base_tps_fee, tps_interval, tps_fee_multiplier, it is the name of the variable being voted for. The value parameter is the value of the variable that the voter supports. For op_list, it must be a list of 12 valid addresses of the proposed order providers (OPs) separated by \n (url-encoded, of course). All other variables have positive numeric (including fractional) values.

The votes are used to govern the network and change the values of the said system-wide variables (described in OIP 3, OIP 5, and OIP 6). The weight of each vote depends on the balance of the voting address(es) in Bytes.

Requesting to count votes for a system variable

This will open Send screen, which will be pre-filled to post a vote-count request for a system variable.

<a href="obyte:data?app=system_vote_count&subject=base_tps_fee">
    open Send screen with the system vote count request
</a>

The subject parameter is one of op_list, threshold_size, base_tps_fee, tps_interval, tps_fee_multiplier, it is the name of the variable whose vote count is requested.

The vote-count requests are used to govern the network and commit changes to the values of the said system-wide variables (described in OIP 3, OIP 5, and OIP 6). All votes for the requested variable will be tallied, weighted by the voter's current balance in Bytes, and the value that received most votes will become active. For op_list, total votes for each proposed OP will be calculated, and the top 12 will become the new active OPs.

The user pays a 1 GB fee for this request.

Receiving textcoins via link

Textcoins are funds that can be sent via text messages. These text messages contain 12 randomly picked words and by entering them into the wallet app in exact same order, user will get the funds that were added to them. If you have ever received any textcoins then you also know that you don't actually have to re-type or copy-paste those words, textcoin receivers are usually directed to Obyte textcoin claiming page, which has green "Receive funds" button, which will launch the wallet app with exactly those textcoin words. Obyte textcoin claiming page tries to check first if user has wallet installed, but basically, underneath that button is a hyperlink similar to this:

<a href="obyte:textcoin?RANDOMLY-GENERATED-TWELVE-WORDS">
    Recieve funds
</a>

So, additionally to sending textcoins with a bot, you can also make clickable textcoins on your website (link either to textcoin claiming page or directly to obyte: protocol). Just make sure each user on your webiste has access to textcoins specifically generated for them. Otherwise, if all users see the same textcoins then it can become a rush to who claims the textcoins first.

Interacting with chat bot

Bot Store on Obyte is like Apple App Store or Google Play Store, but instead of apps, Bot Store has chat bots that are written for Obyte platform. Each Obyte Hub can have each own bots that are shown for users of that app. Currently, most users are using the official wallet app and official Hub, but it makes sense that if somebody forks the wallet, they would use their own Hub for it too. This means that in the future, in order to get your chat bot exposed to maximum amount of users, it needs to get listed on all Hubs.

Pairing with another device

Luckily, adding chat bots to your wallet app is much easier on Obyte than it is to side-load apps on iOS or Android. All you need to do is add the pairing code that bot outputs to your website - everyone who has Byteball app already installed and clicks on it, will get automatically paired with your chat bot. Hyperlink to pairing code would be something like this:

<a href="obyte:[e-mail]/bb#0000">
    Add Sports Betting bot
</a>

One example, where all the official Hub bots are displayed on a website can be seen on Bots section obyte.io.

Pairing codes in hyperlinks are not limited to only chat bots, you could create a pairing link to any device, all you need to do is find you pairing invitation code (Chat > Add new device > Invite other device) and add the code after obyte: protocol inside the hyperlink.

Sending commands to chat bots

Once you have paired with a chat bot already, you might wonder whether it is possible to get users from your website to some specific state in chat bot (for example, by sending a predefined command) with a click on any hyperlink. There are 2 options how to do that, first option would be to fill the pairing_secrets database table with all the possible commands, but if there could be indefinite number of valid commands then easiest would be to accept any pairing secret and use them as custom commands.

conf.js

exports.permanent_pairing_secret = '*';

Websites that use this feature are BB Odds and Polls section on obyte.io. How it can be done can be seen from Poll bot (source code). For example, opening a poll app with results of specific poll can be done with hyperlink like this:

<a href="obyte:AhMVGrYMCoeOHUaR9v/[e-mail]/bb#stats-HAXKXC1EBn8GtiAiW0xtYLAJiyV4V1jTt1rc2TDJ7p4=">
    see stats
</a>

Steem Attestation bot uses this method also as an alternative way how to refer other people, source code for that is more advanced that the poll bot code, but it can be found on Github.

Using protocol URI in a QR code

obyte: protocol is not only for websites, it could be used in physical world too with QR codes. This means that if users have the Obyte app installed and they scan any QR code that contains any of the above codes (just value of the href, without quotes and without the HTML around them) then the installed Obyte app will open the same way. The QR code is not just meant to be printed on paper, it can work on websites too, giving the users the ability to use your services cross-device (browse the website on a laptop, scan the QR code with a phone and complete the payment on the phone).

There are many online QR code generators to create those QR codes manually, but QR codes can be created in real-time too. Following is the example how to create a QR code with obyte: protocol link using jQuery.

<div class="container">
	<div id="qr_code"></div>
</div>

<script src="https://cdnjs.cloudflare.com/ajax/libs/jquery/3.3.1/jquery.min.js"
	integrity="sha256-FgpCb/KJQlLNfOu91ta32o/NMZxltwRo8QtmkMRdAu8="
	crossorigin="anonymous"></script>
<script src="https://cdnjs.cloudflare.com/ajax/libs/jquery.qrcode/1.0/jquery.qrcode.min.js"
	integrity="sha256-9MzwK2kJKBmsJFdccXoIDDtsbWFh8bjYK/C7UjB1Ay0="
	crossorigin="anonymous"></script>
<script type="text/javascript">
$(document).ready(function() {
	$('#qr_code').html('').qrcode({
		width: 512,
		height: 512,
		text: 'obyte:ACCOUNT_ADDRESS?amount=123000&asset=base'
	});
});
</script>

A website that creates QR codes this way is Currency converter for Obyte (source code) and Steem Attestation bot (source code) generates referral links this way. Alternatively, there is also code example how to generate QR code like that on server side.

Using these with testnet wallets

If you are testing these functions with TESTNET headless wallet and TESTNET GUI wallet then instead of obyte: protocol, use obyte-tn:. This can be easily controlled in your bot's code like this:

const pairingProtocol = process.env.testnet ? 'obyte-tn:' : 'obyte:';