Tusker/Documentation/X-Callback-URL.md

X-Callback-URLs in Tusker

Tusker supports inter-app-communication using the X-Callback-URL standard.

In short, requests are performed by opening the URL tusker://x-callback-url/[request] (where [request] is one of the requests listed below) with a variety of parameters.

Callbacks

X-Callback-URLs support three types of callbacks: on success, on cancellation, and on error. Callbacks are specified as query parameters whose keys identify which callback (x-success, x-cancel, and x-error) and whose values are other URLs that should be opened to run the callback.

Data is passed to callbacks by adding additional query parameters to the callback URL. The x-error callback always returns a description of the error in the error parameter. Other data is provided depending on the request.

JSON Responses

By default, callback data is included in URL query parameters of the callback URL. If the json=true parameter is provided, the response data will be encoded as JSON, converted to Base64, and provided in the response query parameter of the callback.

Silent Requests

Tusker X-Callback-URL requests can be performed silently, without user confirmation. Each source app requires user permission on the first attempted silent action.

To perform a silent request:

1. Provide the silent=true URL query parameter in the request.

2. Specify the x-source parameter. It must be a (human interpretable) name of the source application/service. If x-source is not specified, the error callback will be invoked with the error message:

Cannot perform silent action without source app, x-source parameter must be specified.

3. Depending on the current permission state of the source app, one of several things will happen:
   1. If the permission is undecided (i.e. the user has neither accepted nor rejected the silent action request), an alert will be displayed notifying the user that the source app has requested permission to silently perform actions. After the user either accepts or rejects the request, execution will continue with that permission state.
   2. Accepted: the request will be carried out silently and the appropriate callback executed.
   3. Rejected: the request will be performed with the confirmation UI, as if the silent parameter had been false/unprovided.

The silent actions permission state of a given source app is not exposed in the callback.

Other Notes

Instance-Local IDs

Instance-local IDs are provided for many responses and accept in place of URLs/URIs/qualified names in many requests. When possible, instance-local IDs should be preferred requests using them can often be performed faster because there's no need to perform a search query or make requests to remote instances.

Qualified Usernames

Qualified username refers to the domain-qualified identifier of an account. For example, shadowfacts@social.shadowfacts.net. They do not include a leading @.

Dates

Dates in responses are encoded as Unix timestamps.

Requests

• Accounts
  • getCurrentUser
  • getAccount
  • followUser
• Statuses
  • getStatus
  • postStatus
  • favoriteStatus
  • reblogStatus
• Notifications
  • getNotification
  • getNotifications
  • dismissNotification
  • dismissAllNotifications
• Instances
  • getCurrentInstance

Accounts

getCurrentUser

Retrieves the currently logged-in user.

Request

No parameters.

Response:

Parameter (type)	Description	Optional
username (string)	The qualified username	No
displayName (string)	The display name	No
locked (bool)	Whether the user's account is locked	No
followers (int)	The number of followers the user has	No
following (int)	The number of accounts user is following	No
url (URL)	The URL of the user's account	No
avatarURL (URL)	The URL of the user's avatar image	No
headerURL (URL)	The URL of the user's header image	No

getAccount

Retrieves the given account details. One of accountID, accountURL, or acct must be provided.

Request

Parameter (type)	Description	Optional
accountID (string)	The instance-local ID of the account	Yes
accountURL (URL)	The URL/URI of the account	Yes
acct (string)	The qualified username of the account	Yes

Response

Parameter (type)	Description	Optional
username (string)	The qualified username	No
displayName (string)	The display name	No
locked (bool)	Whether the account is locked	No
followers (int)	The number of followers the account has	No
following (int)	The number of accounts account is following	No
url (URL)	The URL of the account	No
avatarURL (URL)	The URL of the account's avatar image	No
headerURL (URL)	The URL of the account's header image	No

followUser

Follows the given account from the logged-in user's account. One of accountID, accountURL, or acct must be provided.

Request

Parameter (type)	Description	Optional
accountID (string)	The instance-local ID of the account	Yes
accountURL (URL)	The URL/URI of the account	Yes
acct (string)	The qualified username of the account	Yes

Response

Parameter (type)	Description	Optional
url (URL)	The URL of the followed account	No

Statuses

getStatus

Retrieves the given status details. One of statusID or statusURL must be provided.

Request

Parameter (type)	Description	Optional
statusID (string)	The instance-local ID of the status	Yes
statusURL (URL)	The URL/URI of the status	Yes
html (bool)	Whether to return the content as HTML or plain-text only. Default: false (plain-text).	Yes

Response

Parameter (type)	Description	Optional
url (URL)	The URL of the status	Yes
uri (string)	The URI of the status	No
account (string)	The qualified username of the account that posted (or reblogged if reblog is present) the status	No
inReplyTo (string)	The instance-local ID of the status	Yes
posted (date)	The date the status was posted	No
content (string)	The content of the status (HTML if the html parameter was true, plain-text otherwise)	No
reblog (string)	The instance-local ID of the status that this is a reblog of. If not present, this status was not a reblog.	Yes

postStatus

Posts a status from the logged-in user's account.

Can be performed silently.

Request

Parameter (type)	Description	Optional
mentioning (bool)	The qualified username to mention in the status	Yes
text (string)	The text to post/pre-fill the status text field with	Yes

Response

Parameter (type)	Description	Optional
statusURL (URL)	The URL of the posted status	Yes
statusURI (string)	The URI of the posted status	No

favoriteStatus

Favorites the given status from the logged-in user's account. One of statusID or statusURL must be provided.

Can be performed silently.

Request

Parameter (type)	Description	Optional
statusID (string)	The instance-local ID of the status	Yes
statusURL (URL)	The URL/URI of a status	Yes

Response

Parameter (type)	Description	Optional
statusURL (URL)	The URL of the favorited status	Yes
statusURI (string)	The URI of the favorited status	No

reblogStatus

Reblogs the given status from the logged-in user's account. One of statusID or statusURL must be provided.

Can be performed silently.

Request

Parameter (type)	Description	Optional
statusID (string)	The instance-local ID of the status	Yes
statusURL (URL)	The URL/URI of a status	Yes

Response

Parameter (type)	Description	Optional
statusURL (URL)	The URL of the reblogged status	Yes
statusURI (string)	The URI of the reblogged status	No

Notifications

getNotification

Retrieves the given notification details.

Request

Parameter (type)	Description	Optional
notificationID (string)	The instance-local ID of the notification	No

Response

Parameter (type)	Description	Optional
kind (string)	One of mention, reblog, favourite, or follow	No
date (date)	The date the notification was created.	No
accountID (string)	The instance-local ID of the account that sent the notification	No
statusID (string)	The instance-local ID of the status associated with the notification. Not applicable for kind=follow.	Yes

getNotifications

Retrieves the most recent notifications.

Request

Parameter (type)	Description	Optional
count (int)	The number of notifications to retrieve. Default: 20	Yes

Response

Parameter (type)	Description	Optional
notifications (string)	A comma-delimited array of instance-local notification IDs	No

dismissNotification

Dismisses the given notification.

Request

Parameter (type)	Description	Optional
notification (string)	The instance-local ID of the notification	No

Response

No response data if successful.

dismissAllNotifications

Dismisses all notifications.

Request

No parameters.

Response

No data if successful.

Instances

getCurrentInstance

Retrieves the current instance details.

Request

No parameters.

Response

Parameter (type)	Description	Optional
uri (string)	The instance URI	No
name (string)	The instance name	No
description (string)	The instance description	No
contactAccount (string)	The instance-local ID of the instance's contact account	No