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

# SpeechSense integration with amoCRM

To set up SpeechSense integration with [amoCRM](https://www.amocrm.ru/):

1. [Get your cloud ready](#before-you-begin).
1. [Set up export from amoCRM to SpeechSense](#amocrm-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:

      * In the **Key** field, enter the field name to use when mapping fields in the exchange module settings. For example: `Call date` → `call_date`. Also, specify the name used in the system and add a description to display in SpeechSense forms and reports.
      * Currently, the **Type** field only supports the `String` value.

      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.

      To provide 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 amoCRM to SpeechSense {#amocrm-export}


### Install the app in amoCRM {#amocrm-app}

{% list tabs group=instructions %}

- amoCRM UI {#amocrm}

  1. Navigate to **amoMarket** in your amoCRM account.
  1. In the search bar, enter `Export to SpeechSense`.
  1. Click **Install for free**.
  1. Check the **I agree to the collection of personal data...** box.
  1. Click **Install**.
  1. In the **Description** tab, click **Save**.

      The app will be displayed in the **Installed** tab in **amoMarket**.

{% endlist %}


### Set up export from amoCRM {#amocrm-config}

{% list tabs group=instructions %}

- amoCRM UI {#amocrm}

  1. Navigate to **Settings** in your amoCRM account.
  1. Go to the **SpeechSense export settings** tab.
  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 %}

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

      * **Call direction**:

          * `All`: Export calls of all types.
          * `Outgoing`: Export only outgoing calls.
          * `Incoming`: Export only incoming calls.

      * **Re-export calls**: Enable this option if you need to re-export calls that were previously exported, e.g., to a new SpeechSense connection or workspace. When this option is on, the system will not check if the calls were previously exported and will export all calls once again.
      * Set the minimum and maximum conversation duration in seconds. To export all calls, leave the `0` values.
      * Configure field mapping in amoCRM and SpeechSense:

          1. In the **amoCRM** column, select the field key in amoCRM.
          1. In the **SpeechSense** column, enter the key of the field from the SpeechSense connection you created [earlier](#create-audio-connection).

          To add a new mapping, click ![image](../../../_assets/console-icons/plus.svg) **Add**.

          {% note info %}

          Calls can be associated with different amoCRM entities. Depending on the entity, i.e., a deal, contact, company, or call, the metadata provided with each call may vary. The associated entities are grouped into separate blocks.

          {% endnote %}

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

      Wait for the export to complete.

      {% note tip %}

      To force stop the export, click **Stop export**.

      {% endnote %}

{% 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.