Work with Canvas

To integrate Open CTI with external applications that require authentication methods, such as signed requests or OAuth 2.0 protocols, Salesforce recommends that you use Canvas.

Open CTI for Lightning Experience doesn’t support Canvas.

Important

Canvas and Open CTI are similar—they’re a set of tools and JavaScript APIs that developers can use to add third-party systems to Salesforce. However, one of the benefits of Canvas, is the ability to choose authentication methods.

For a canvas app to appear in a Salesforce console, you must add it to the console as a custom console component. For more information, see the Canvas Developer Guide.

Note

When developing a canvas app, and you want to include functionality from Open CTI, do the following:

  1. Include the Open CTI API in index.jsp.
  2. Call Sfdc.canvas.client.signedrequest() to store the signed request needed by the console integration toolkit API. For example, if the Canvas method of authentication is a signed request, do the following:
    Sfdc.canvas.client.signedrequest('<%=signedRequest%>')

    If the Canvas method of authentication is OAuth, do the following in the callback function used to get the context, as shown in the Canvas Developer Guide:

    Sfdc.canvas.client.signedrequest(msg)

Consider the following when working with Open CTI and canvas apps:

  • The Open CTI API script depends on the signed request and should be added after the call to Sfdc.canvas.client.signedrequest() has executed. We recommend that you load the scripts dynamically.
  • To retrieve the entity ID of the record that is associated with the canvas sidebar component, do the following:
    // Get signedRequest
    var signedRequest = Sfdc.canvas.client.signedrequest();
    var parsedRequest = JSON.parse(signedRequest);
    // get the entity Id that is associated with this canvas sidebar component.
    var entityId = parsedRequest.context.environment.parameters.entityId;
  • To retrieve the entityId for OAuth, do the following:
    var entityId = msg.payload.environment.parameters.entityId;

    To see an example on how to retrieve msg.payload, see the Canvas Developer Guide.