Custom Apps

Introduction

A Custom App is a web application that can be embedded into Copilot and receives authentication information about the current user.

Setup

To connect a Custom App, navigate to App Setup > + Add New. Scroll to "Don't see your app?" and click Add. Then, under Setup type, choose Authenticated. From there, you can name your app and paste the URL of your hosted app into the content box. The clientId and companyId parameters will be appended to your URL in the embedded iframe, which you can then use to call the Copilot API from your app.

Since embeds are simply web pages embedded in a sandboxed iframe within Copilot, you have complete control over how to validate the request. Session storage with cookies will work as you expect with any web browser.

However, for added security, consider the following options:

Setting a Content Security Policy

Restricting the domains that are allowed to embed your app is a simple way to ensure that your app is not used outside your preferred contexts. Additionally, if you are trying to embed a web page with an existing content security policy in place, you will need to update that page’s content security policy accordingly.

The HTTP Content-Security-Policy frame-ancestors directive should be updated as follows:

Content-Security-Policy: frame-ancestors https://*.copilot.com https://<custom portal domain>;

Get Client Data

You can check the query parameters passed to your application to verify that Copilot is requesting your app. The query parameters will be clientId and companyId. These parameters correspond to the id of the client and company associated with the App channel that is being rendered.

You can call the Retrieve a client or Retrieve a company endpoint from the Copilot API with the relevant id and your provided API key, which will return a Client or Company resource that can be used in rendering your app. The client resource includes a companyId, so if your extension is set up to pass the clientId query parameter, you can still get company information by first retrieving retrieving a client and then retrieving a company.

The Client resource also includes the values set to their custom fields.

The keys in the customFields property are ids of the different custom field properties. When you create a custom field in your portal, an id will be generated for that property. Copilot uses that id when setting a value for a client user’s custom field property.

E.g., you might have a custom field in your portal called “Notes” with a generated id of c9b33f2b-97d8-4bcd-b9ad-2bb8acfc70cc. When you request a client resource that has this property set, the custom fields would look like the following:

"customFields": {
    "c9b33f2b-97d8-4bcd-b9ad-2bb8acfc70cc": "Example Text", // this is the value for the Notes custom field
}

To correlate the keys in the customFields property to their names, you can also get the custom field metadata from the Copilot API. It is recommended to do this once and store the relevant ids that your application needs so that you do not need to make an extra API call to request this metadata.

Getting Custom Field Metadata

You can query the custom fields resource to get further information about the custom fields to understand what the keys in the customFields property represent.