Работа с amoCRM

В функциях Sipuni можно делать вызовы к любым API при поимощи библиотеки axios. Но для amoCRM мы создали библиотеку @sipuni/amocrm (opens new window), упрощающую работу с amoCRM. Ниже несколько примеров работы с этой библиотекой.

Добавление IP адреса Sipuni функций в белый список

Если вы используете ограничение доступа к amoCRM API по IP адресам разрешите доступ адресу 193.227.98.1

Авторизация amoCRM

Библиотека работы с amoCRM поддердживает два способа авторизации: по ключу accessToken и по login/hash

Выбрать вариант авторизации нельзя, это зависит от того, как давно подключена ваша интеграция к Sipuni. Все интеграции, подключенные или переподключенные после июля 2020 года используют новую авторизацию по ключу. Ниже показаны примеры, для обоих вариантов.

Как узнать какая авторизация в вашем аккаунте Sipuni?

  • Создайте любую функцию для amocrm
  • Перейдите на вкладку «Параметры пробного запуска»
  • Найдите внизу поле crm_auth:
    • Если поле равно null – у вас login/hash авторизация.
    • Если поле содержит длинную строку – у вас авторизация по ключу accessToken.

В обоих случаях вам не нужно беспокоится о значениях для авторизации. Необходимая информация подается в параметры функции:

  • accessToken в поле args.crm_auth
  • login/hash в args.settings.login и args.settings.hash

Авторизация по ключу accessToken:

const amoApi = new SipuniAmoCrm({
  domain: args.settings.domain, 
  accessToken: args.crm_auth
});

Авторизация при помощи login/hash

const amoApi = new SipuniAmoCrm({
  domain: args.settings.domain, 
  login: args.settings.login, 
  hash: args.settings.hash
});

Далее во всех примерах будет использоваться accessToken авторизация. Заменяйте ее на login/hash авторизацию если у вас не поддерживается accessToken авторизация.

Создание сделки в amoCRM при входящем звонке

В ответ на событие входящего звонка создадим сделку в amoCRM. Название сделки будет содержать номер абонента.

const SipuniAmoCrm = require('@sipuni/amocrm');

module.exports = async (args) => {

  const amoApi = new SipuniAmoCrm({
    domain: args.settings.domain, 
    accessToken: args.crm_auth
  });

  const leadName = args.call_args.src_num;

  const lead = await amoApi.leads.create({ name: leadName });
};

Первая строка в примере, подключение модуля @sipuni/amocrm. Он упрощает работу с API amoCRM.

В конструктор SipuniAmoCrm подаем домен amoCRM и ключ доступа. Этот ключ приходит с параметрами вызова функции. См. раздел Авторизация ниже.

В параметры leads.create можно подать любые поля из документации amoCRM. В данном случае подается только имя сделки.

Метод leads.create вызывается при помощи await. Вместо него вы можете использовать и синтаксис с .then(). Это на ваше усмотрение.

Доступные поля для создания сделки (opens new window).

Создание контакта при входящем звонке

Этот пример аналогичен созданию сделки, только мы используем метод createContact.

Важно отключить создание контактов в личном кабинете Sipuni при использовании своей функции, чтобы не создавались дубли контактов.

const SipuniAmoCrm = require('@sipuni/amocrm');

module.exports = async (args) => {

  const amoApi = new SipuniAmoCrm({
    domain: args.settings.domain, accessToken: args.crm_auth
  });

  // Формируем имя контакта из схемы и номера телефона
  const { tree_name, src_num } = args.call_args;
  const contactName = `${tree_name} ${src_num}`;
  
  // Создаем контакт с именем и номером телефона
  const contact = await amoApi.contacts.create({ 
    name: contactName,
    custom_fields_values: [
      amoApi.preparePhoneField(src_num, 'WORK'),
    ] 
  });
};

При создании контакта используется функция preparePhoneField. Она упрощает формирование параметров для номера телефона, и аналогична такой записи:

const contact = await amoApi.contacts.create({ 
  name: contactName,
  custom_fields_values: [
    {
      field_code: 'PHONE',
      values: [
        {
          value: src_num,
          enum_code: 'WORK'
        }
      ]
    }
  ] 
});

Доступные поля для создания контакта (opens new window).

Добавление записей о звонках

Метод привязывает запись о звонке по номеру телефона. Важно, чтобы в CRM уже был контакт с таким номером телефона.

const call = await amoApi.calls.create({
    duration: 32,
    source: 'yandex',
    phone: '74996470051',
    link: 'https://example.com/audio.mp3',
    direction: 'inbound',
    call_result: 'Успешный разговор',
    call_status: 4
});

Произвольные запросы к API amoCRM

Поскольку не для всех сущностей реализованы методы, такие как leads.create можно вызывать API методы amoCRM напрямую при помощи метода request.

const result = await amoApi.request('POST', '/leads/pipelines', {
    name: "Воронка доп продаж",
    is_main: false,
    is_unsorted_on: true,
    sort: 20,
    request_id: "123",
});

Первый параметр – HTTP метод, GET, POST, PATCH, DELETE.

Второй параметр – путь API метода без версии. Например, если в документации указан путь /api/v4/leads/pipelines то подавайте /leads/pipelines, если указан /api/v4/contacts подавайте /contacts.

Третий параметр – объект с полями и значениями. В документации часто подается массив объектов. В метод request нужно подавать только объект. Например, если в документации указаны параметры:

[
    {
        "name": "Воронка доп продаж",
        "is_main": false,
        "is_unsorted_on": true,
        ...
    }
]

то вам нужно подавать лишь объект:

{
    "name": "Воронка доп продаж",
    "is_main": false,
    "is_unsorted_on": true,
    ...
}

Используйте документацию по API amoCRM (opens new window), чтобы узнать HTTP метод, путь и параметры.