• Public
  • Public/Protected
  • All

Class CallbackURL

CallbackURL objects can be used to open x-callback-url requests and wait for a response from the target app.

NOTE: If you want to open a URL in Safari or another app and do not need a response or x-callback-url support, use the app.openURL(url) method on the App object.


// Open callback URL for each line in a draft
// Setup base Fantastical URL, with no parameters
const baseURL = "fantastical2://x-callback-url/parse/";

// split draft and loop over lines
var lines = draft.content.split("\n");
for (var line of lines) {
    // create and configure callback object
    var cb = CallbackURL.create();
    cb.baseURL = baseURL;
    cb.addParameter("sentence", line);
    // open and wait for result
    var success = cb.open();
    if (success) {
        console.log("Event created");
    else { // something went wrong or was cancelled
          if (cb.status == "cancel") {
        else {


  • CallbackURL




baseURL: string

The baseURL of the request. This should include the x-callback-url base URL and action, typically something like app-scheme://x-callback-url/actionName


callbackResponse: object

An object contain and URL query parameters returned by the target app along with it’s callback response. For example, if the target app called x-success with the query parameters result=MyTestText, callbackResponse would contain {"result": "MyTestText"}.

Type declaration

  • [x: string]: any


parameters: object

Object containing string keys and values to be appended to the base url as query parameters. Values should not be pre-encoded, but will be encoded and added to the base URL automatically. Do not include x-callback parameters (x-success, x-error, x-cancel) as these will be generated by Drafts.

Type declaration

  • [x: string]: any


status: "created" | "success" | "cancelled" | "error" | "timeout" | "invalid"

The current status of the callback. Used to check outcome after open is called. Possible values:

  • created: open has not yet been called.
  • success: x-success callback was received from target app.
  • cancelled: x-cancel callback was received from target app.
  • error: x-error callback was received from target app.
  • timeout: Waiting for the response timed out without receiving a callback URL from the target app.
  • invalid: The URL was invalid and could not be opened.


waitForResponse: boolean

If true, the script will pause and wait for the x-success, x-error or x-cancel response from the app being targeted by the URL. If false, execution of the script/action will continue immediately and no response/results will be available.



  • addParameter(key: string, value: any): void
  • Add a query parameter for the outgoing URL. FIXME: can the value be anything?


    • key: string
    • value: any

    Returns void


  • open(): boolean
  • Opens the URL with associated parameters, and waits for a callback response. Returns true if an x-success response was received from the target app, otherwise false. If false, use the "status" property to determine the type of failure.

    Returns boolean

Static create

  • Creates a new CallbackURL object.

    Returns CallbackURL

Generated using TypeDoc