Menu items

"app_type": ["menu_items"]

Applications of type Menu items allow you to extend vcita by injecting your custom pages and adding new menu items under the existing menu categories.
When clicking the new menu item, vcita will load the app's redirect URL into an iFrame that takes the entire page view.

How does it work?

menu-item applications take several parameters required for displaying additional menu items.
Let's take a look at an example of such an application structure and then review its elements one by one.

Here's a request for creating a new app of type "menu-items:

POST https://api.vcita.biz/platform/v1/apps

Request body:

{
    "name": "{APP_NAME}", // your application name. free text.
    "app_type": ["menu_items"],
    "trusted": true,
    "redirect_uri": "https://your-app-redirect-uri/",
    "url_params": ["business_uid"],
    "menu_items": {
        "subitems": [
            {
                "item_name": {
                    "en": "Playground"
                },
                "route": "my-app-route",
                "category": "calendar",
                "permissions": ["can_access_clients"]
            }
        ]
    }
}

Headers:

{
        "Authorization": "Bearer {API_TOKEN}",
    "Content-Type": "application/json"
}

app_type: ['menu_items']

As the name suggests, specifying the app_type as 'menu_items' is what allows the app to inject new menu items into vcita.
The app_type property accepts an array because applications can have more than one type.

redirect_uri

This is the base URL of your application. It is used for OAuth as described in the OpenID article.
The below meun_item routes relate to this redirect URI. In other words, all additional routes should be children of the main redirect URL route on your app.

menu_items: []

The menu_items property is the core of any "menu items" type of app, and it defines the list of desired menu items to be added, along with several parameters that are configured per each menu item:

• item_name: the name or title of the menu item. This would be reflected in the text on the menu item itself, as well as the iFrame's page header.
  The item_name property supports multiple languages, hence it accepts an object that can contain the language as a key and the title (in that language) as a value.
  All supported languages are listed in the "Create App" API reference.
• route: the route of the page to be opened when clicking the menu item.
  The route is relative to the redirect_uri configured in your app.
  Using this routing mechanism you can configure multiple menu items under the same app (assuming they indeed represent separate pages of the same app, of course) where each menu item has it's own route.
• category: the category (main menu item) under which your new menu item will appear.
  Available options are: ["calendar", "clients", "payments", "documents", "campaigns", "reputation", "my-livesite", "social", "reports", "team-chat"]
  Note that "reports" and "team-chat" will create their own main-menu item.
• permissions: the permissions array defines the permissions needed in order to view the menu item.
  For instance, if a menu item requires the "payments" permission, only users with permission to see payments will also see the menu item, while it will remain hidden from non-permitted users.
  If no permissions are specified, the menu item will be visible for all users.
  Available permission options: ["can_access_listings_management", "can_access_soci", "can_access_online_presence", "can_access_clients", "can_use_reports", "can_view_payments", "can_view_documents"]

url_params: ["business_uid"]

The url_params array specifies the list of query params that can be chained to each of the menu items' URLs.
For instance, your app may need to know the user's role that's viewing the app in order to hide or show some of its features, or maybe it'll need to business uid in order to pull business info.

Example: https://app.redirect-uri/menu-item-route?business_uid={BUSINESS_UID}

Supported params: ["impersonate", "business_uid", "staff_role", "staff_uid", "payment_permissions", "language", "package", "brand_host"]