On this page

Canvases

The canvas object has three primary keys, plus specific options (like title, icon, height):

1. “type”: The type of canvas. Required.
2. “url”: The target URL for the canvas. Required.
3. “identification”: Field that identifies the canvas between other canvases. Optional if you don’t have two or more canvases using the same type.

To view the available canvas types and options, visit the Canvas lists for the mobile app and admin dashboard.

The canvas URL is manipulated before being introduced into the interface. To enable contextual experiences, Optix adds an authentication token that can be used by the canvas to retrieve user/organization-wide data.

If you don’t provide a “macro” to be replaced, the canvas system appends the variable “token” to the query parameter list of the URL.

Using macro replacements

Macros can be defined to customize the URL generation. With macros, you can change the request variables, repeat information, and also use fragment variables.

Example 1:
If you provide “https://example.com/mypage”, the Optix system opens the link “https://example.com/mypage?token=thepersonaltokengenerated”

If you want to change the URL to use a specific format, you can use macroses, like “{token}.”

Example 2:
If you provide “https://example.com/mypage?mytoken={token}” the Optix system opens the link “https://example.com/mypage?mytoken=thepersonaltokengenerated”

You can also use the macro as part of the URL path or a fragment.

Example 3:
If you provide “https://example.com/mypage/{token}/show” the Optix system opens the link “https://example.com/mypage/thepersonaltokengenerated/show”

Example 4:
If you provide “https://example.com/mypage?anyother=var#mytoken={token}” the Optix system opens the link “https://example.com/mypage?anyother=var#mytoken=thepersonaltokengenerated”

If your canvas application backend does not require the token, we support the use of tokens in the URL fragment (example 4) for security purposes. In this case, the token is never sent to the backend.

Macros list

Webhooks

The webhook object has 2 required keys:

• “event”: The event name.
• “URL”: The target URL for the webhook. Your URL can contain GET parameters.

Check the webhook list to see all available events and data.

On this page

On this page

1. App settings

This canvas could be used to display all of the global configuration UI that your app needs (e.g., dropdown select boxes with settings or an OAuth flow to get integrations connected). It opens when a user clicks the Configure button on the Apps → Manage apps menu item.

JSON type

ADMIN_APP_SETTINGS

Settings file example

Learn more about using this in the app settings file section.

{  
   "canvases": [  
      {  
         "type": "ADMIN_APP_SETTINGS",
         "url": "https://api.optixapp.com/canvas-placeholder",
         "title": "My app interface"
      }
   ]
}

Placement in admin dashboard

The admin dashboard displaying a full-screen canvas for an app’s settings.

1. title
2. url (loaded in an iframe)

Example app

2. Main menu item

This canvas is displayed in a section much like the other core features. It is accessed from the main left menu.

JSON type

ADMIN_MAIN_MENU

Settings file example

Learn more about using this in the app settings file section.

{  
   "canvases": [  
      {  
         "type": "ADMIN_MAIN_MENU",
         "url": "https://api.optixapp.com/canvas-placeholder",
         "title": "My app interface",
         "icon": "unlock"
      }
   ]
}

Placement in admin dashboard

The app home screen with a custom ‘section’ (on the left), and a full-screen canvas opening when the ‘secondary title’ is tapped (on the right).

1. icon (you can find the available icons here)
2. title
3. url (loaded in an iframe)
4. admin_role (“OWNER”, “MANAGER”, “CLIENT_SERVICE”, or “RECEPTION”)

3. Invoice options menu

This can be used to present a pop-up modal when an admin selects one or more invoices in the invoice list, then clicks on ‘options.’ Setting up this canvas will add your item to the menu that opens, and will display a canvas in a modal when that option is clicked.

JSON type

ADMIN_MODAL_INVOICES_MENU

Settings file example

Learn more about using this in the app settings file section.

{  
   "canvases": [  
      {  
         "type": "ADMIN_MODAL_INVOICES_MENU",
         "url": "https://api.optixapp.com/canvas-placeholder",
         "title": "My app interface"
      }
   ]
}

Placement in the admin dashboard

The admin dashboard showing the options menu for a selected invoice (above) and the modal open after the custom menu option is clicked.

1. title
2. title (inherited from #1)
3. url (loaded in an iframe)

Example app

On this page

1. Home screen primary action

This canvas can be used to add a primary action to the top group found on the home screen. The supporting content is used to construct the primary action card, which opens a full-screen canvas when tapped.

JSON type

MOBILE_HOME_PRIMARY

Settings file example

Learn more about using this in the app settings file section.

{  
   "canvases": [  
      {  
         "type": "MOBILE_HOME_PRIMARY",
         "url": "https://api.optixapp.com/canvas-placeholder",
         "title": "My app interface",
         "icon": "exporter"
      }
   ]
}

Placement in app

The app home screen with a custom ‘primary action’ (on the left), and a full-screen canvas opening when that primary action is tapped (on the right).

1. icon (you can find the available icons here)
2. title
3. title (inherited from #2)
4. url (loaded in a webview)

Example app

2. Home screen section

This canvas appears in the main content of the mobile app home screen. It gets a title and one or more web views in the home screen. It is used to add content or actions to the home screen (e.g., blogs, essential information, access control, or surveys). Additionally and optionally, a secondary action that loads a full-screen canvas when tapped can be specified. The secondary action would be useful when the primary canvas is showing a subset of the UI, and a ‘See all’ reveals the full version.

JSON types

MOBILE_HOME_SECTION (to group the items)

MOBILE_HOME_SECTION_ITEM (for each item to be displayed in a web view)

Settings file example

Learn more about using this in the app settings file section.

{

"canvases": [

		{
			"type":"MOBILE_HOME_SECTION",
			"title":"Section title",
			"subtitle":"My subtitle",
			"secondary_title":"See all",
			"secondary_url":"https://api.optixapp.com/canvas-placeholder",
			"height":"300",
			"items": [
				"article-happy-springs1",
				"article-happy-springs2",
				"article-happy-springs3"
			],
			"show_at_top": true
		},
		{
			"type":"MOBILE_HOME_SECTION_ITEM",
			"url": "https://api.optixapp.com/canvas-placeholder",
			"title":"Title 1",
			"identification": "article-happy-springs1"
		},

		{
			"type":"MOBILE_HOME_SECTION_ITEM",
			"url": "https://api.optixapp.com/canvas-placeholder",
			"title":"Title 2",
			"identification": "article-happy-springs2"
		},

		{
			"type":"MOBILE_HOME_SECTION_ITEM",
			"url": "https://api.optixapp.com/canvas-placeholder",
			"title":"Title 3",
			"identification": "article-happy-springs3"
		}
	]
}

Notes

• The maximum height is 400 (the unit is ‘dp,’ you can consider them to be pixels relative to a 1x resolution screen).
• You must specify at least one (and a maximum of six) MOBILE_HOME_SECTION_ITEM for a MOBILE_HOME_SECTION.

Placement in app

The app home screen with a custom ‘section’ (on the left), and a full-screen canvas opening when the ‘secondary title’ is tapped (on the right).

1. title
2. first item’s url (loaded in a webview)
3. secondary title
4. second item’s url (loaded in a webview)
5. title (inherited from #1 above)
6. secondary url (loaded in a webview)
7. show at top

Example app

3. Tab bar item

This can be used to add a whole new tab to the mobile apps. The tab title is shown at the top along with the venue picker and messaging icon (to maintain consistency). This could be used to add a primary section considered very important by the admin (e.g., door locks, events or food ordering).

JSON type

MOBILE_TAB_BAR_ITEM

Settings file example

Learn more about using this in the app settings file section.

{  
   "canvases": [  
      {  
         "type": "MOBILE_TAB_BAR_ITEM",
         "url": "https://api.optixapp.com/canvas-placeholder",
         "title": "My app interface",
         "icon": "unlock",
         "lock_header": false
      }
   ]
}

Notes

• lock_header is a true/false flag that instructs the mobile app to fix the header section in place or not. When it is not fixed, certain web content that relies on browser height may not function as desired. In this case, you can enable lock_header.

Placement in app

The app displaying a custom tab.

1. title
2. url (loaded in a webview)
3. icon (you can find the available icons here)

Example app

4. More screen item

This can be used to create additional items in the more screen. This item opens a full-screen canvas when tapped.

JSON type

MOBILE_MORE_SCREEN

Settings file example

Learn more about using this in the app settings file section.

{  
   "canvases": [  
      {  
         "type": "MOBILE_MORE_SCREEN",
         "url": "https://api.optixapp.com/canvas-placeholder",
         "title": "My app interface"
      }
   ]
}

Placement in app

The app more screen with a custom ‘more screen item’ (on the left), and a full-screen canvas opening when it is tapped (on the right).

1. title
2. title (inherited from #1 above)
3. url (loaded in a webview)

On this page

Choosing the best canvas for your use case

There are several canvases available for the mobile app and admin dashboard. They display in different places and offer slightly different opportunities/restrictions. Use the lists found in the following pages to learn more about the available canvases and choose the best place to host your UI.

Each canvas in the list contains information regarding the sizing, scrolling behavior, and configurations available. The list is broken into two sections:

1. Optix mobile app canvases
2. Optix admin dashboard canvases

On this page

Webhook debugger demo

This live demo shows what you can expect from the Webhook debugger:

On this page

On this page

Retry policy

Each webhook request will be repeated until a 2xx (successful) HTTP response is received. 301 redirects will not be followed. A 410 response will force the webhook subscription to be removed, no other request will be sent to the endpoint regarding the same event (unless a new app is installed). Any other code will be logged as a failure, and the system will retry the request up to 10 times (with a delay of 10 minutes between each attempt).

The webhook system has a timeout of 5 seconds for connection and 2 seconds to receive the response. Any request that takes more time will be considered failed and will retry in the manner described above. You can use the Webhook debugger to identify problems during the development of your app.

On this page

Booking session ID

The Server-generated booking_session_id identifies the sequence of your interactions with the API. You can grab it from BookingSet of the first response and then pass it in all subsequent requests related to that booking set.

Making new bookings

The input for new bookings must include the following:

• The account
  • Defines the available allowances through the active personal/team plan subscriptions.
  • Used to invoice the overage charges, if any.
• The owner of the booking
  • For member accounts, it must be that same user.
  • For team accounts, it can be any team member.
• A single resource to be booked

When updating the bookings, booking_session_id, account, and owner_user_id may be omitted.

Draft a booking

query {
  bookingsDraft(
    input: {
      account: { member_id: MEMBER_ID }
      # account: { team_id: TEAM_ID, organization_id: ORGANIZATION_ID }
      owner_user_id: USER_ID
      bookings: [{ resource_id: RESOURCE_ID }]
    }
  ) {
    booking_session_id
    bookings {
      booking_id
      start_timestamp
      end_timestamp
    }
  }
}

Commit a booking

Committing a booking will draft and save that booking. Pass booking_id to update the existing booking. Note that it is possible to call bookingsCommit without calling bookingsDraft first.

mutation {
  bookingsCommit(
    input: {
      account: { member_id: MEMBER_ID }
      owner_user_id: USER_ID
      bookings: [{ resource_id: RESOURCE_ID }]
    }
  ) {
    booking_session_id
    bookings {
      booking_id
      start_timestamp
      end_timestamp
    }
  }
}

Payment preferences

By default, if the booking requires a payment, the system will choose the optimal available allowance for the given account and use as much of it as possible. You can also manually specify the allowance and the exact amount to be used.

Get the available allowances

query {
  bookingsDraft(
    input: {
      account: { member_id: MEMBER_ID }
      owner_user_id: USER_ID
      bookings: [{ resource_id: RESOURCE_ID }]
    }
  ) {
    booking_session_id
    bookings {
      booking_id
      start_timestamp
      end_timestamp

      # the optimal allowance and the resulting booking cost
      payment {
        allowance_usage {
          allowance {
            allowance_id
            unit
            total
            available
          }
          amount
        }
        total
      }

      # all other allowances and the full payment option (no allowance usage)
      available_payments {
        account {
          account_id
        }
        allowance_usage {
          allowance {
            allowance_id
            unit
            total
            available
          }
          amount
        }
        total
      }
    }
  }
}

Use a specific allowance

Set amount: 0 if you want to only apply the discount to overage charges, without consuming the allowance.

Use calculate: NO_ALLOWANCE to disable the selection of the optimal allowance and generate a full charge instead.

query {
  bookingsDraft(
    input: {
      account: { member_id: MEMBER_ID }
      owner_user_id: USER_ID
      bookings: [{
        resource_id: RESOURCE_ID
        payment: {
          calculate: FIXED_ALLOWANCE
          allowance_usage: [{
              allowance_id: "ALLOWANCE_ID"
              amount: 2.5
          }]
        }
        # payment: { calculate: NO_ALLOWANCE }
      }]
    }
  ) {
    booking_session_id
    bookings {
      booking_id
      start_timestamp
      end_timestamp
      payment {
        allowance_usage {
          allowance {
            allowance_id
            unit
            total
            available
          }
          amount
        }
        total
      }
    }
  }
}

Updating a booking

Change the booking times

query {
  bookingsDraft(
    input: {
      account: { member_id: MEMBER_ID }
      owner_user_id: USER_ID
      bookings: [{
        booking_id: BOOKING_ID
        start_timestamp: 1577869200
        end_timestamp: 1577874600
      }]
    }
  ) {
    booking_session_id
    bookings {
      booking_id
      start_timestamp
      end_timestamp
    }
  }
}

Cancel the booking

query {
  bookingsDraft(
    input: {
      account: { member_id: MEMBER_ID }
      owner_user_id: USER_ID
      bookings: [{
        booking_id: BOOKING_ID
        is_cancelled: true
      }]
    }
  ) {
    booking_session_id
    bookings {
      booking_id
      is_confirmed
      is_cancelled
    }
  }
}

Other features

Invoice the booking

Use payment: {charge: TODAY} to invoice the booking with a positive payment.total. This will create a new invoice with a single line item due today.

Alternatively, set payment: {charge: NOW} to charge this invoice immediately using the default payment method associated with the given account.

Add invitees to the booking

For existing users, please provide either user_id, or email. If you enter an email address for which an existing user is not found, one will be created using the given email.

When you edit a booking, existing invitees will be preserved, along with their invitation status. Set invitees: [] to remove them from a booking.

query {
  bookingsDraft(
    input: {
      account: { member_id: MEMBER_ID }
      owner_user_id: USER_ID
      bookings: [{
        resource_id: RESOURCE_ID
        invitees: [
          { user_id: USER_ID }
          { email: "EMAIL" }
          { email: "EMAIL", name: "NAME SURNAME" }
        ]
      }]
    }
  ) {
    booking_session_id
    bookings {
      booking_id
      invitees {
        user {
          user_id
          fullname
        }
        status
      }
    }
  }
}

Get the alternative bookings

The system suggests multiple alternatives for each booking based on the given preferences; e.g. resource type, hourly price, duration, etc.

query {
  bookingsDraft(
    input: {
      account: { member_id: MEMBER_ID }
      owner_user_id: USER_ID
      bookings: [{
        resource_id: RESOURCE_ID
      }]
    }
  ) {
    booking_session_id
    bookings {
      booking_id
      alternative_bookings {
        booking_id
        start_timestamp
        end_timestamp
        resources {
          resource_id
        }
        payment {
          total
        }
      }
    }
  }
}

Check the resource availability

query {
  resourceAvailability(
    input: {
      resource: { price_hour_to: 20 }
      start_timestamp: 1577869200
      end_timestamp: 1577874600
      duration_sec: 3600
    }
  ) {
    resource {
      resource_id
      title
    }
    available {
      start_timestamp
      end_timestamp
    }
  }
}

On this page