Your app in the CRM

Allow users to view and interact with your app from inside their CRM

In addition to interacting with the existing data in your users' CRMs, you probably want your users to be able to interact with your app from inside of their CRM.

Their CRM is their home base and the place where they have all of the context on critical business data.

By placing your data and app's actions in that context, you're putting your app at your user's fingertips where they need it most.

Modal action in Salesforce embed powered by Xkit

App Objects

The concept Xkit uses to place your data and app actions inside your user's CRM is that of an App Object.

App Objects are objects that exist in your application and should appear in the user's CRM.

An example App Object for an e-signature SaaS app would be a Document, which might be linked to an Opportunity or Deal in the user's CRM.

App Objects are created and managed inside the Developer Portal, and are common across your entire application. Depending on CRM support, App Objects will appear inside of the CRM alongside the objects they are related to.

Create App Objects

To create an app object, navigate to the "App Objects" menu item in Xkit.

Click on "Add App Object" and fill out the fields below:

  • Slug: the name of your App Object as it appears in the Xkit API, e.g. document
  • Singular Name: the name of your App Object as it appears to your users, e.g. "Document"
  • Plural Name: the pluralized name of your App Object, e.g. "Documents"
  • Description: a description of your App Object for your users

Display data in the CRM

To display your data in the CRM, you'll respond to HTTP requests with data from your app. Xkit will include the related CRM objects in the request, and your app will respond with the pre-configured properties of your App objects.

Here's an example of how that looks in Salesforce:

App Object List in Salesforce

Relations

When requesting data from your app, Xkit will include the CRM object that a given App Object is related to so that your app can provide data that is in the right context for the CRM.

For example, for an e-signature app, you may want to display the Documents related to a specific Opportunity or Deal.

To appear in the CRM, App Objects need to be related to at least one CRM Object.

You configure relationships in the Developer Portal, so they must be common for all of your users.

For each Relation, you'll need to provide:

  • Related Object: Select a CRM Object to associate the App Object with.

Properties

Properties define data fields on your object that are visible to users in the CRM.

Due to limitations in some CRMs, these fields must be defined upfront in the Xkit developer portal, so should be applicable to all users.

For each property, you'll need to provide:

  • Slug: short string identifying the property (e.g. status)
  • Label: a user-facing name for the property (e.g. "Status")
  • Description: a user-facing description (e.g. "The current status of a document in Acme")
  • Type: the data type of the property (currently must be string)

Request and response

The data request is a POST request to your application and is made to the URL you configure in the Developer Portal for this App Object.

The request will be authenticated using the API Key you configure for it in the Developer Portal.

Requests will include the current CRM connection (connection), the user/company context (platform_context) and the CRM record that is related (record).

An example request is below:

POST /api/crm-embed/objects HTTP 1.1
Host: myapp.com
Authorization: Bearer 818e07e5-94c0-4ec4-a001-c5b4c19ee11a
Content-Type: application/json

{
  "request_type": "list",
  "app_object": {
    "type": "document"
  },
  "record": {
    "type": "opportunity",
    "id": "Opportunity|09876",
    "data": {
      "document_name": "Sales Contract",
      "document_tags": []
    }
  },
  "platform_context": {
    "id": "usr5c7e8c43"
  },
  "connection": {
    "id": "12345"
  },
  "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyfQ.SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c"
}

For successful requests, respond with HTTP status 200 and the following body:

  • app_objects: the list of App Objects that are associated with the CRM object; each object contains:
    • type: the slug of the App Object as configured in the Developer Portal
    • id: a unique identifier for the App Object, meaningful to your app
    • properties: the values of the object properties of the object,
200 OK

{
  "app_objects": [
    {
      "type": "document",
      "id": "doc766b46a7",
      "properties": {
        "title": "Agreement Document",
      }
    }
  ]
}

Enable actions from the CRM

In addition to displaying your app's data in your user's CRM, you can allow your users to take actions from the CRM.

Actions are interactions that you enable your users to take from inside the CRM. They are triggered by a button or a link that the user clicks in the context of an App Object, or a collection of App Objects.

Depending on CRM support and what you want to set up, these actions come in three forms:

  • links: link to a specific page in your app
  • commands: take an action in your app without additional user input
  • modals: launch a modal screen in the CRM with an iframe to your app for advanced actions

Create actions

To create actions, you'll configure them ahead of time in the Developer Portal.

For each Action, you'll need to provide:

  • Type: Whether this is an action for an entire collection (e.g. create a Document) or an individual record (e.g. archive a Document)
  • Slug: the short string identifying this action
  • Label: the user-facing name for this action
  • Action Handler URLs: the URL that Xkit should POST to
    • Link (required)
    • Command (optional)
    • Modal (optional)

Display actions in CRM

To allow a user to user a previously created action, include the action's slug when responding to a data request.

For collection-level actions (e.g. create a Document), include the slug in the top-level actions array. For record-level actions (e.g. archive a Document), include the slug in the actions array for that specific app object.

Example response:

200 OK

{
  "app_objects": [
    {
      "type": "document",
      "id": "doc766b46a7",
      "properties": {
        "title": "Agreement Document",
      },
      "actions": [
        "open-document",
        "edit-document",
        "archive-document"
      ]
    }
  ],
  "actions": [
    "archive-all",
    "new-document"
  ]
}

Respond to actions

Once display in the UI, the action will trigger a webhook to your application upon its usage by the user (e.g. when the user clicks the actions button in the CRM).

Each webhook will contain information about the app object record (if a record-level action), the CRM Object record, the platform context, and the connection.

They'll also include a token, which is a JWT signed by Xkit which you can use to log the user into your app.

Requests for hyperlinks to redirect users from the CRM into highly contextualized locations in your application.

You can choose to log users in (e.g. by passing a one-time login token in the returned URL), or rely on their existing session.

Here's an example of a link action in Salesforce:

View document action in Salesforce

Example request:

POST /api/crm-embed/new-document HTTP 1.1
Host: myapp.com
Authorization: Bearer 818e07e5-94c0-4ec4-a001-c5b4c19ee11a
Content-Type: application/json

{
  "request_type": "link",
  "action": "new_document",
  "app_object": {
    "type": "document"
  },
  "record": {
    "type": "opportunity",
    "id": "Opportunity|09876",
    "data": {
      "document_name": "Sales Contract",
      "document_tags": []
    }
  },
  "platform_context": {
    "id": "usr5c7e8c43"
  },
  "connection": {
    "id": "12345"
  },
  "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyfQ.SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c"
}

For successful requests, respond with HTTP status 200 and a JSON body with a url key indicating the URL the user should be redirected to in order to complete this action.

You may want to include either the provided Xkit token or your own login token in the query string to allow the existing platform context to log into your app seamlessly.

Example response:

200 OK
Content-Type: application/json

{
  "url": "https://myapp.com/documents/new?name=Sales%20Contract&tags=&crm_object=Opportunity|09876&token=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyfQ.SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c"
}

Modals

Modals display your user interface directly inside of the CRM, typically inside of a modal dialog rendered as an iframe.

Modals are best used to take complex actions in your application and are a more advanced interface design than a simple link.

Here's an example of a modal action in Salesforce:

Create document action in Salesforce

Example request:

POST /api/crm-embed/new-object HTTP 1.1
Host: myapp.com
Authorization: Bearer 818e07e5-94c0-4ec4-a001-c5b4c19ee11a
Content-Type: application/json

{
  "request_type": "modal",
  "action": "new-document",
  "app_object": {
    "type": "document"
  },
  "record": {
    "type": "opportunity",
    "id": "Opportunity|09876",
    "data": {
      "document_name": "Sales Contract",
      "document_tags": []
    }
  },
  "platform_context": {
    "id": "usr5c7e8c43"
  },
  "connection": {
    "id": "12345"
  },
  "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyfQ.SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c"
}

For successful requests, respond with HTTP status 200 and a url key indicating the URL of the iframe for the user to complete this action.

You may want to include either the provided Xkit token or your own login token in the query string to allow the existing platform context to log into your app seamlessly.

Example response:

200 OK
Content-Type: application/json

{
  "url": "https://myapp.com/documents/new-modal?name=Sales%20Contract&tags=&crm_object=Opportunity|09876&token=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyfQ.SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c"
}

Commands

Commands are interaction points in your app that don't require user input beyond the command itself and the App Object it's acting on.

Good examples of commands are actions like "delete" or "remove".

After the action is invoked, the UI will be refreshed with another data request.

Here's an example of a command action in Salesforce:

Archive document action in Salesforce

Example request:

POST /api/crm-embed/archive HTTP 1.1
Host: myapp.com
Authorization: Bearer 818e07e5-94c0-4ec4-a001-c5b4c19ee11a
Content-Type: application/json

{
  "request_type": "command",
  "action": "archive-document",
  "app_object": {
    "type": "document"
    "id": "doc766b46a7"
  },
  "record": {
    "type": "opportunity",
    "id": "Opportunity|09876",
    "data": {
      "document_name": "Sales Contract",
      "document_tags": []
    }
  },
  "platform_context": {
    "id": "usr5c7e8c43"
  },
  "connection": {
    "id": "12345"
  },
  "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyfQ.SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c"
}

For successful requests, respond with HTTP status 200 and the following body:

  • message: a user-friendly message to be displayed in the CRM
  • status: success

Example successful response:

200 OK
Content-Type: application/json

{
  "status": "success",
  "message": "Archived document succesfully"
}

For requests that could not be completed (but were otherwise well-formed), respond with HTTP status 400 and the following body:

  • message: a user-friendly message to be displayed in the CRM
  • status: error

Example error response:

400 Bad Request
Content-Type: application/json

{
  "status": "error",
  "message": "Document already archived"
}

Ready to build your CRM app?

Integrate every CRM with one build, request access to get started.