[Yandex Cloud documentation](../../../index.md) > [Tutorials](../../index.md) > [Machine learning and artificial intelligence](../index.md) > Speech analytics > SpeechSense integration with Bitrix24

# SpeechSense integration with Bitrix24

To set up SpeechSense integration with Bitrix24:

1. [Get your cloud ready](#before-you-begin).
1. [Set up export from Bitrix24 to SpeechSense](#bitrix24-export).
1. [Check the result](#check-result).

## Get your cloud ready {#before-you-begin}

1. Navigate to the [management console](https://console.yandex.cloud) and log in to Yandex Cloud, or sign up if you have not already. For information, see [Getting started with Yandex Cloud](../../../getting-started/index.md).
1. Accept the user agreement.
1. In [Yandex Cloud Billing](https://center.yandex.cloud/billing/accounts), make sure you have a [billing account](../../../billing/concepts/billing-account.md) linked and its status is `ACTIVE`. If you do not have a billing account yet, [create one](../../../billing/quickstart/index.md#create_billing_account). If your billing account has the `TRIAL_ACTIVE` status, [activate its paid version](../../../billing/operations/activate-commercial.md).
1. [Assign](../../../iam/operations/roles/grant.md) the `speech-sense.spaces.creator` role to your Yandex Cloud account.

    {% note info %}
    
    If you cannot manage roles, contact your cloud or organization administrator.
    
    {% endnote %}

### Required paid resources {#paid-resources}

The cost of the infrastructure for integration with external systems includes the SpeechSense fee: duration of each two-channel audio file (see [SpeechSense pricing](https://aistudio.yandex.ru/docs/en/speechsense/pricing)).

### Create a service account {#create-sa}

Create a service account with the `speech-sense.data.editor` [role](https://aistudio.yandex.ru/docs/en/speechsense/security/#speechsense-data-editor) for amoCRM to access the SpeechSense project.

{% list tabs group=instructions %}

- Management console {#console}

  1. In the [management console](https://console.yandex.cloud), select the relevant folder.
  1. Navigate to **Identity and Access Management**.
  1. Click **Create service account**.
  1. Name the [service account](../../../iam/concepts/users/service-accounts.md): `speechsense`.
  1. Click ![image](../../../_assets/console-icons/plus.svg) **Add role** and select `speech-sense.data.editor`.
  1. Click **Create**.

{% endlist %}


### Create an API key for the service account {#create-key}

{% list tabs group=instructions %}

- Management console {#console}

  1. In the [management console](https://console.yandex.cloud), select the folder the service account was created in.
  1. Navigate to **Identity and Access Management**.
  1. In the left-hand panel, select ![FaceRobot](../../../_assets/console-icons/face-robot.svg) **Service accounts**.
  1. Select the `speechsense` service account.
  1. In the top panel, click ![image](../../../_assets/console-icons/plus.svg) **Create new key** and select **Create API key**.
  1. In the window that opens, select the `yc.speech-sense.use` [scope](../../../iam/concepts/authorization/api-key.md#scoped-api-keys) in the **Scope** field.
  1. Click **Create**.
  1. Save the ID and secret key for later.

      {% note alert %}

      After you close this dialog, the key value will no longer be available.

      {% endnote %}

{% endlist %}


### Create a space and link a billing account {#create-space}

{% list tabs group=instructions %}

- SpeechSense UI {#speechsense}

  1. Open the SpeechSense [home page](https://speechsense.yandex.cloud/).
  1. Click **Create space**.
  1. Enter a name for the [space](https://aistudio.yandex.ru/docs/en/speechsense/concepts/resources-hierarchy#space).
  1. Click **Create**.
  1. [Link a billing account](https://aistudio.yandex.ru/docs/en/speechsense/operations/space/link-ba) to the space to pay for SpeechSense.

      {% note info %}
      
      The user must have the `billing.accounts.editor`, `billing.accounts.admin`, or `billing.accounts.owner` role [assigned](../../../billing/security/index.md#set-role) to the billing account to manage it.
      
      {% endnote %}

{% endlist %}


### Add the service account to the space {#add-sa-to-space}

{% list tabs group=instructions %}

- SpeechSense UI {#speechsense}

  1. Navigate to the [new space](#create-space) in the SpeechSense [interface](https://speechsense.yandex.cloud/).
  1. Click ![image](../../../_assets/console-icons/person-plus.svg) **Add participant** → ![image](../../../_assets/console-icons/persons.svg) **Add from organization**.
  1. Copy the ID of the `speechsense` [service account you created earlier](#create-sa) and paste it to the search bar.
  1. Select the `speechsense` service account and specify the [Data editor](https://aistudio.yandex.ru/docs/en/speechsense/security/#speechsense-data-editor) role. This role will allow the service account to upload data to SpeechSense.
  1. Click **Add**.

{% endlist %}


### Create a connection {#create-connection}

{% list tabs group=instructions %}

- SpeechSense UI {#speechsense}

  1. In the SpeechSense [UI](https://speechsense.yandex.cloud/), go to the space of your choice.
  1. Go to the **Connections** tab and select a template to create a connection or click **Create connection**.

     * **Blank form**: Connection that allows adding your own keys for metadata.
     * **Bitrix24**: Connection with a pre-installed set of keys for Bitrix24. Additionally, you can add your own keys.
     * **AmoCRM**: Connection with a pre-installed set of keys for amoCRM. Additionally, you can add your own keys.

  1. Enter the connection name.
  1. Select the `Two-channel audio` data type.
  1. Under **Agent** and **Customer**, specify:

      1. Channels with the agent's and customer's voices.
      1. Agent and customer keys from the metadata file. This file contains the call information collected from CRM systems, PBXs, or other sources.

        By default, connections include keys with the name and ID of the agent and the customer. In the **Name in the system** field, enter the name the key will have in SpeechSense.

        To specify additional metadata for the agent and the customer, click **Add key**.

  1. Under **Shared metadata**, provide the keys from the metadata file that are not related to the agent or the customer.

      By default, connections include keys with the date, direction, and language of the call. In addition, you can specify the keys you want to receive from the external system. In the **Name in the system** field, enter the name the key will have in SpeechSense.

      {% cut "List of available fields" %}

      This list is valid for the current application version.

      ```json
      {
          "id",
          "portal_user_id",
          "portal_number",
          "phone_number",
          "call_id",
          "external_call_id",
          "call_category",
          "call_duration",
          "call_start_date",
          "call_record_url",
          "call_vote",
          "cost",
          "cost_currency",
          "call_failed_code",
          "call_failed_reason",
          "crm_entity_type",
          "crm_entity_id",
          "crm_activity_id",
          "rest_app_id",
          "rest_app_name",
          "transcript_id",
          "transcript_pending",
          "session_id",
          "redial_attempt",
          "comment",
          "record_duration",
          "record_file_id",
          "call_type"
      }
      ```

      {% endcut %}

      To specify additional metadata, click **Add key**.

  1. Click **Create connection**.
  1. Click **ID** ![image](../../../_assets/console-icons/copy-transparent.svg) in the top-left corner of the connection page to copy the connection ID. Save it as you will need it later.

{% endlist %}


### Create a project {#create-project}

{% list tabs group=instructions %}

- SpeechSense UI {#speechsense}

  1. In the SpeechSense [UI](https://speechsense.yandex.cloud/), go to the space of your choice.
  1. Click ![create](../../../_assets/console-icons/folder-plus.svg) **Create project**.
  1. Enter a name for your project.
  1. Under **Connection**, click **Add connection** and select the connection you [created earlier](#create-connection).
  1. Click **Create project**.

{% endlist %}


## Set up export from Bitrix24 to SpeechSense {#bitrix24-export}


### Install the app in Bitrix24 {#bitrix24-app}

{% list tabs group=instructions %}

- Bitrix24 UI {#bitrix24}

  1. Navigate to **Market** in your Bitrix24 account.
  1. In the search bar, enter `Yandex SpeechSense`.
  1. Click **Install**.
  1. Check the **I have read and agree to...** boxes and click **Install**.
  1. Click **Open app**.

{% endlist %}


### Set up export from Bitrix24 {#bitrix24-config}

{% list tabs group=instructions %}

- Bitrix24 UI {#bitrix24}

  1. Set up a connection:
     
     1. **Language**: Select the language for recognition.
     1. **SpeechSense connection ID**: Enter the ID of the connection you created [previously](#create-audio-connection).
     1. **API key**: Enter the secret part of the API key you created [previously](#create-key).
     1. Click **Check connection**.
     
         If the API key and connection ID are correct, you will see the following message:
     
         ```text
         Successful request to SpeechSense
         ```

  1. Configure other settings:

      * Specify the period to export the calls for.

          {% note info %}

          The export will include the start and end dates.

          {% endnote %}

          To export all the calls you have so far, do not specify dates.

      * **User list**: Specify a comma-separated list of Bitrix24 users whose calls you want to export (a list of your agents). To export calls for all users, leave the list empty.

      * **Call direction**: Select one or more options:

          * `All`: Exports calls of all types.
          * `Outgoing`: Export all outgoing calls.
          * `Incoming`: Export all incoming calls.
          * `Incoming, forwarded to mobile`: Export incoming calls that were
          redirected to the agent's mobile phone number.
          * `Callback`: Export calls requested by customers after filling out the CRM form.

      * **Minimum conversation time**: Specify the conversation duration in seconds. We recommend exporting calls that took 30 seconds or longer.
      * **Last processed call ID**: Non-editable field indicating which call was processed last. 

          To reset the field value, click **Reset**.

  1. Click **Save**.
  1. Click **Start export**.

      Wait for the export to complete.

{% endlist %}


## Check the result {#check-result}

{% list tabs group=instructions %}

- SpeechSense UI {#speechsense}

  1. In the SpeechSense [UI](https://speechsense.yandex.cloud/), go to the space of your choice.
  1. Select the project you created [earlier](#create-project).

      On the project panel, you will see the imported calls and transcripts. After that, you will be able to [configure reports](https://aistudio.yandex.ru/docs/en/speechsense/operations/data/manage-reports).

{% endlist %}

If you have any problems, [contact](#contact-form) Yandex Cloud.