Add a CRM Integration Template

Yeastar P-Series Software Edition allows you to create and configure custom integration templates, which can be used to seamlessly integrate the PBX with a CRM system via API, enabling data exchange and synchronization. This topic describes how to create a CRM integration template and configure the necessary settings to meet specific operational requirements.

Requirements and restrictions

Requirements
  • PBX Server: The PBX server should meet the following requirements.
    • Firmware: Version 83.18.0.102 or later.
    • Plan: Enterprise Plan (EP) or Ultimate Plan (UP)
  • CRM System: Supports REST API.
Restrictions
Supports to add up to 10 custom CRM integration templates.

Prerequisites

  • You have basic coding skills
  • You have obtained the REST API documentation of your desired CRM for reference, and get the following information:
    • Authentication method: Determine the authentication method used by your desired CRM (None, basic, or OAuth2 authentication method are supported).
    • API request information: You have gathered the necessary API request URLs and data specification for the following features according to the capabilities of the CRM and your specific requirements.
      API request Description
      Search contacts The API request URLs to search contacts within the CRM using specific criteria.
      Get users Optional. The API request URL to retrieve user information from the CRM.
      Create contacts Optional. The API request URL to add new contacts to the CRM.
      Call journalling Optional. The API request URL to create call records in the CRM.

Procedure

  1. Log in to PBX web portal, go to Integrations > CRM.
  2. In the CRM list, click Custom.

    You are redirected to the Template Management page.

  3. Click Add to add a template.
  4. In the pop-window, complete the following template settings according to the capabilities the CRM system and your specific requirements.
  5. Click Save to generate a custom CRM integration template.

Configure general settings

In the General section, complete the basic settings for the template.

  • Logo: Upload a logo for the CRM, which will be displayed in the CRM list on the Integration page.
    Note: The logo file should meet the following requirements:
    • File format: PNG (recommended), JPG, or JPEG
    • Suggested Resolution: 150 × 150
    • File size: Less than 500KB
  • CRM Name: Enter the name of the CRM.
  • Max Concurrent Request: Specify the maximum number of concurrent HTTP requests allowed to the CRM.
  • Remark: Optional. Enter a description for the CRM template, which will be displayed in the Template Management page.

(Optional) Configure user association

In the User Association section, enable and configure the feature to support associating CRM users with PBX extensions.
Note: If enabled, the system will require associating CRM users with PBX extensions during integration, as shown in the following picture. Only the associated extension users can use the CRM integration functionalities.

  1. Turn on the switch of User Association.
  2. In the Get User field, enter the CRM API request URL for getting the list of CRM users.
    Note:
    • The default HTTP request method is GET, if you need to use a different request method, you can manually change it in the template later. For more detailed descriptions about the template parameters in this scenario, see XML Description - User Association Scenario.
    • The values input by the users during the integration authentication process can be used as variables in the template if necessary.
    For example,
    https://www.api.example.com/v1/users?type=ActiveUsers
  3. In the User Field Mapping section, map the CRM fields to the required PBX fields by specifying the JSON path (e.g. data.#(key=="value").field) for the corresponding fields in the CRM response.
    Tip: For more information about the path syntax, see GJSON Path Syntax.
    PBX Field Description
    User Unique ID The unique ID of the user.

    For example, users.#.id.
    First Name The first name of the user, which will be displayed in the CRM user list.

    For example, users.#.First_Name.
    Last Name The last name of the user, which will be displayed in the CRM user list.

    For example, users.#.Last_Name.
    Email The email of the user, which will be displayed in the CRM user list, and can be used for automatic association of CRM users and PBX extensions.

    For example, users.#.Email.

Configure authentication method

In the Configure Authentication Method section, configure the authentication method based on the CRM system's requirements.
None authentication

This method is used when there is no authentication required, or when the CRM only requires relevant variables for the integration, such as an API Key for the request, or a webhook URL for real-time data delivery.

  1. In the Authentication Method drop-down list, select None.
  2. Optional: Click Add to add custom fields, which will be displayed as input field on the integration page, requiring users to provide the necessary information for the integration.
    Note:
    • If no fields are added, the CRM will be integrated directly without requiring any additional settings or input from the users.
    • Supports up to 5 custom fields.
    • The values input by users during the integration authentication process can be used as variable values in the template.
    Setting Description
    Type Select the type of the custom field.
    • Text Input: A standard input field where users can enter plain text.
    • Password Input: A specialized input field for sensitive information, with text masked for privacy.
    • Dropdown List: A selectable list that allows users to choose from a pre-defined list of options.
    Name Specify the variable name for the field, which can be referenced within the template as needed.
    Title Specify the title for the field, which will be display above the input component.
    Dropdown Options If the Type is set to Dropdown List, enter the options in this field.
    Note: Use commas to separate multiple options. For example, option1,option2.
Basic authentication
This method authenticate requests using credentials, such as username and password or an API key. In this case, every HTTP request sent to the CRM will include a header field in the format of Authorization: Basic {{.basic_string}}, where {{.basic_string}} is the Base64-encoded combination of the username and password or API key specified during the integration.

  1. In the Authentication Method drop-down list, select Basic.
  2. In the Credential Type drop-down list, select Username and Password or API Key according to the CRM system's requirements.
  3. Configure the required fields for users to enter credentials, and add additional custom fields if needed.
    Note:
    • Supports up to 5 fields.
    • The values input by users during the integration authentication process can be used as variable values in the template.
    Setting Description
    Type Select the type of the custom field.
    • Text Input: A standard input field where users can enter plain text.
    • Password Input: A specialized input field for sensitive information, with text masked for privacy.
    • Dropdown List: A selectable list that allows users to choose from a pre-defined list of options.
    Name Specify the variable name for the field, which can be referenced within the template as needed.
    Title Specify the title for the field, which will be display above the input component.
    Dropdown Options If the Type is set to Dropdown List, enter the options in this field.
    Note: Use commas to separate multiple options. For example, option1,option2.
  4. In the Base64 Encoded Credential field, define the combination format of the credential variables, which will be used to generate the basic authentication string (basic_string).

    For example, {{.username:.password}} or {{.api_key:}}.

OAuth2 authentication

This method uses tokens to grant access without sharing credentials. It requires obtaining the necessary header and other parameters (e.g. OAuth access token) using specific API requests to the CRM.

  1. In the Authentication Method drop-down list, select OAuth2.
  2. Configure the required fields for users to enter credentials.
    Note:
    • If more fields are required, you need to manually add custom fields in the template later. For more detailed descriptions about the template parameters in this scenario, see XML Description - Authentication Scenario.
    • The values input by users during the integration authentication process can be used as variable values in the template.
    Setting Description
    Type Select the type of the custom field.
    • Text Input: A standard input field where users can enter plain text.
    • Password Input: A specialized input field for sensitive information, with text masked for privacy.
    • Dropdown List: A selectable list that allows users to choose from a pre-defined list of options.
    Name Specify the variable name for the field, which can be referenced within the template as needed.
    Title Specify the title for the field, which will be display above the input component.
    Dropdown Options If the Type is set to Dropdown List, enter the options in this field.
    Note: Use commas to separate multiple options. For example, option1,option2.
  3. In the Authorization Endpoint field, enter the CRM authorization URL, to which users will be redirected for authorization during integration.

    For example,

    https://www.api.example.com/auth/v2/authorize?client_id={{.client_id}}
  4. In the Token Endpoint field, enter the CRM API request URL for getting access token and refresh token.

    For example,

    https://www.api.example.com/oauth/v2/token?client_id={{.client_id}}&client_secret={{.client_secret}}
  5. Optional: In the Scope (Optional) field, enter the scope to specify the data in the CRM that the PBX is allowed to access.
    Note: Use comma to separate multiple fields.

    For example,

    contacts.read,contacts.write,calls.read,calls.write,user.read,user.write
  6. Optional: If the CRM system authenticates requests using query parameters instead of scope, you can add the query parameters in the Additional Query String (Optional) field.

    For example, client_id={{.client_id}}&redirect_uri={{.redirect_uri}}.

After the template setting is saved, the authentication page of the CRM will automatically display the PBX authentication information, which can be used to create an application in the CRM system and retrieve the required authorization information from the CRM for the integration.

Configure contacts searching for synchronization and call popup

In the Synchronize Contacts Automatically section, specify the contacts type available for users to select when configuring integration features, and specify the API requests to search for the specified types of contacts. These configurations can be used to implement CRM contacts searching, automatic contact synchronization and call popup.
  1. Add and configure contact types and specify the corresponding API requests.

    • Contact Type: Enter the name of the contact type. For example Contacts.

      The name set here will appear as an option for automatic contact synchronization when users configure the integration features.

    • Contact Match Query URL: Enter the CRM API request URL used to search for contacts with specific criteria.

      In this scenario, the following variables can be used as the values of criteria parameters:

      • The variables obtained from user input during the integration authentication process.
      • {{.Phone}}: The phone number associated with inbound or outbound calls, or the number entered by users for contact searching.
      For example,
      https://www.api.example.com/crm/v1/Contacts/search?criteria=((Phone:equals:{{.Phone}})or(Home_Phone:equals:{{.Phone}})or(Mobile:equals:{{.Phone}})or(Asst_Phone:equals:{{.Phone}}))
  2. Configure the URL for call popup using one of the following methods.
    Specify URL Format
    Configure the call popup URL by specifying the URL format, where you can use variables to dynamically construct the URL.
    1. In the Contact Popup URL drop-down list, select Specify URL Format.
    2. In the URL Format field, enter the expression of the Contact URL.

      In this scenario, the following variables can be used, the values of which are obtained from the CRM contact search results.

      Note: If the provided variables do not meet your requirements, you can manually edit the template later to define additional custom variables and retrieve the corresponding values. For more detailed descriptions about the template parameters in this scenario, see XML Description - Retrieve Additional Variables.
      For example,
      {{.crm_url}}/crm/{{.CustomValue}}/tab/{{Capitalize .ContactSyncType}}/{{.ContactId}}
    Retrieve from Contact Fields
    Extract the Contact URL directly from a specific field in the contact search response, where the contact URL can be retrieved.

    1. In the Contact Popup URL drop-down list, select Retrieve from Contact Fields.
    2. In the Contact Field for URL field, specify the JSON path for the corresponding field in the response. For example, data.#.contactUrl.
  3. In the Contact Field Mapping section, map the CRM fields to the required PBX fields by specifying the JSON path (e.g. data.#(key=="value").field) for the corresponding fields in the CRM response.
    Note: If more than one variable need to be retrieved for a field, use commas to separate the variables. For example, data.#(phone=="{{.Phone}}")#.street,data.#(mobile=="{{.Phone}}")#.street.
    1. Map the following required fields.

      • Contact ID: The ID of the searched contact. For example, data.#.id.
      • First Name: The first name of the searched contact. For example, data.#.first_name.
    2. Enable and map the respective PBX fields according to your needs.
      Note: You need to enable and map at least one phone number.

    3. If the existing PBX fields do not provide the variables you need, enable and map the desired response field to the Custom Value field, which can be referenced in the template with the variable name {{.CustomValue}}.
      Note: This variable is specially used for constructing the Contact URL, and will not appear in the PBX contact details.

(Optional) Configure new contact creation

If you want to enable the creation of a new contact in the CRM when the caller’s number does not match any existing CRM contact, enable and configure the Create New Contact settings.

  1. Turn on the switch of Create New Contact.
  2. Add and configure the contact types available for users to select when configuring integration features.
    • Contact Type: Specify the type of the contact. For example, Contacts.
    • Contact Creation URL (POST): Enter the CRM API request URL used to create a new contact.
      For example,
      https://www.api.example.com/crm/v1/Contacts
    • Contact Creation Request Body: Enter the request body (in JSON format) to pass the contact information.
      In this scenario, the following variables can be used:
      • The variables obtained from user input during the integration authentication process.
      • {{.LastName}}: Required. The last name of the contact.
      • {{.FirstName}}: Required. The first name of the contact.
      • {{.BusinessNumber}}: Required. The phone number of the contact.
      Note: If the provided variables do not meet your requirements, you can manually edit the template later to define additional custom variables and retrieve the corresponding values. For more detailed descriptions about the template parameters in this scenario, see XML Description - Retrieve Additional Variables.
      For example,
      {
  "data": [
    {
      "Last_Name": "{{.LastName}}",
      "First_Name": "{{.FirstName}}",
      "Phone": "{{.BusinessNumber}}"
    }
  ]
}

(Optional) Configure call journaling

If you want to enable call journaling to automatically log call activities and details in the CRM, enable and configure the Call Journal feature.

  1. Turn on the switch of Call Journal.
  2. Configure the API request and body for call journaling.
    • Create Call Journal URL (POST): Enter the CRM API request URL used to create a call log in the CRM.
      For example, 
      https://www.api.example.com/crm/v2/Calls
    • Call Journal Creation Request Data: Enter the request body (in JSON format) to pass the call details.
      Note: For the variables supported in the request body, see XML Description - Call Journal Variables.
      For example,
      {
  "data": [
    {
      "{{.Owner}}{{.WhoModule}}": {
        "Description": "{{.Description}}",
        "Voice_Recording__s": "{{.RecordPath}}",
        "Call_Start_Time": "{{TimeFormat .StartTimeUnix 'yyyy-MM-ddTHH:mm:ss-z' '1'}}",
        "Subject": "{{.Subject}}",
        "Call_Type": "Inbound",
        "Call_Result": "{{.Call_Log_Status}}",
        "Call_Duration": "{{.Talk_Duration_Sec}}"
      }
    }
  ]
}
  3. If you want to allow users to customize specific settings for call journaling, including key attributes such as logging details and call recording playback option, enable the following options and configure the default values as needed.
    Note:
    • Subject: If enabled, enter a default subject for call journal. All call logs will be created with the specified subject.
    • Description: If enabled, specify the details of the call logs.
      For example, 
      Call: {{.Time}} {{.Call_Log_Status}} from {{.Call_From}} to {{.Call_To}} {{.Talk_Duration}}
    • Play Call Recording: Decide whether to allow users to configure the option for playing call recordings in the CRM.