PolygramDocs
Войти

Примеры

Интеграция с CRM

Сотрудник заводит клиенту аккаунт в вашей CRM прямо из чата, а CRM сообщает Polygram о заказах и менеджерах. Аккаунты клиента хранятся в поле-списке crm_accounts с колонками id (уникальная) и username.

Что происходит Кто вызывает Кого
Сотрудник создаёт аккаунт Polygram Вашу CRM
Меняется статус заказа Ваша CRM Polygram, POST /public/contacts/tag
Назначен менеджер Ваша CRM Polygram, POST /public/contacts/assign
CRM пишет клиенту Ваша CRM Polygram, POST /public/contacts/message
Сотрудник смотрит данные из CRM Polygram Вашу CRM

Подготовка

  1. Откройте Настройки, раздел Подключения к API, и добавьте подключение: базовый адрес https://crm.example.com/api/v1, авторизация Bearer-токен, ключ, который выдала ваша CRM.
  2. Создайте ключ доступа к API Polygram для вызовов из CRM, см. Ключ доступа.

Создать аккаунт из чата

Workflow:

  1. Запуск Кнопка в диалоге с названием Создать аккаунт.
  2. Шаг Запросить данные у того, кто нажал кнопку: поле login с типом Текст и поле tariff с типом Выбор из списка и вариантами из подключения: адрес /tariffs, подпись name, значение id.
  3. Шаг Внешний вызов: POST /accounts через подключение, тело Поля, заголовок X-Snippex-User-Id: $me.id.
  4. Сохранить из ответа: data.account.id и data.account.username в список контакта crm_accounts, колонки id и username.
  5. На выходе Ошибка шаг Уведомить сотрудника с текстом CRM ответила: $vars.http_error.

Сотрудник нажимает Действия в шапке диалога, выбирает Создать аккаунт и заполняет форму.

Когда форма открывается, Polygram запрашивает варианты для поля tariff:

GET https://crm.example.com/api/v1/tariffs
Authorization: Bearer <ключ>

[
  { "id": 3, "name": "Премиум" },
  { "id": 5, "name": "Базовый" }
]

Формат ответа описан в статье Варианты для форм.

Запрос на создание аккаунта:

POST https://crm.example.com/api/v1/accounts
Authorization: Bearer <ключ>
X-Snippex-User-Id: 3f2c…
Idempotency-Key: <id запуска>:<id шага>
Content-Type: application/json
Имя поля Значение Тип
login $vars.login Текст
tariff_id $vars.tariff Число
client.name $contact.name Текст
client.phone $contact.phone Текст 
{
  "login": "ivan.petrov",
  "tariff_id": 3,
  "client": { "name": "Иван Петров", "phone": "+7 700 000 00 00" }
}

Ответ CRM при успехе:

HTTP/1.1 201 Created
Content-Type: application/json

{ "data": { "account": { "id": 1042, "username": "ivan.petrov" } } }

Клиенту добавится запись { "id": "1042", "username": "ivan.petrov" } в поле crm_accounts. Второй аккаунт того же клиента добавится второй записью.

Ответ CRM при ошибке:

HTTP/1.1 409 Conflict
Content-Type: text/plain; charset=utf-8

Логин ivan.petrov уже занят

Сотрудник получит уведомление CRM ответила: Внешний сервис ответил 409: Логин ivan.petrov уже занят.

На стороне CRM:

  • проверяйте Idempotency-Key: если время ожидания выйдет, Polygram повторит запрос с тем же ключом;
  • сохраните X-Snippex-User-Id, если хотите потом назначать этому сотруднику диалоги.

Подробнее: Запросы Polygram к вашему API, Ответы: что Polygram сохраняет.

Статус заказа

Когда в CRM меняется статус заказа, CRM ставит клиенту тег из категории статусов. Клиента Polygram ищет по колонке списка crm_accounts.id.

curl -X POST https://api.polygram.chat/api/public/contacts/tag \
  -H "X-Api-Key: ak_..." \
  -H "Content-Type: application/json" \
  -d '{
    "match": { "field": "crm_accounts.id", "value": "1042" },
    "category": "Статус заказа",
    "tag": "Отправлено",
    "source": "CRM",
    "final": true
  }'

Для статусов, после которых заказ больше не движется, например Отправлено и Доставлено, передавайте final: true. Если у клиента несколько аккаунтов, такой статус не перекроет текущий статус другого аккаунта. Остальные теги категории снимаются. Поля, ответ и ошибки описаны в статье Поставить тег.

Менеджер

Когда в CRM клиенту назначают менеджера, CRM назначает на него диалоги клиента в Polygram. В assigneeId передайте ID сотрудника Polygram, например полученный из X-Snippex-User-Id.

curl -X POST https://api.polygram.chat/api/public/contacts/assign \
  -H "X-Api-Key: ak_..." \
  -H "Content-Type: application/json" \
  -d '{
    "match": { "field": "crm_accounts.id", "value": "1042" },
    "assigneeId": "3f2c…"
  }'

"assigneeId": null снимает назначение. Подробнее: Назначить чаты.

Сообщение клиенту

CRM пишет клиенту в его последнюю переписку.

curl -X POST https://api.polygram.chat/api/public/contacts/message \
  -H "X-Api-Key: ak_..." \
  -H "Content-Type: application/json" \
  -d '{
    "match": { "field": "crm_accounts.id", "value": "1042" },
    "text": "Ваш заказ № 5531 отправлен",
    "source": "CRM",
    "idempotencyKey": "order-5531-shipped"
  }'

Вызов с тем же idempotencyKey второй раз сообщение не отправляет. Подробнее: Написать клиенту.

Информация из CRM

Workflow:

  1. Запуск Кнопка в диалоге с названием Информация из CRM. В Показывать выбрано Если заполнено и поле crm_accounts, поэтому у клиента без аккаунта кнопки нет.
  2. Шаг Запросить данные: поле account с типом Выбор из списка и источником Варианты из списка контакта: поле crm_accounts, значение id, подпись username, поле обязательное. Если аккаунт у клиента один, он подставляется сам, и форма не показывается.
  3. Шаг Внешний вызов: GET /accounts/$vars.account/summary через подключение.
  4. Сохранить из ответа: пустой путь в переменную crm_info.
  5. Шаг Показать сотруднику с переменной $vars.crm_info.

Запрос:

GET https://crm.example.com/api/v1/accounts/1042/summary
Authorization: Bearer <ключ>

Ответ в формате карточки:

{
  "title": "ivan.petrov",
  "url": "https://crm.example.com/accounts/1042",
  "sections": [
    {
      "title": "Аккаунт",
      "items": [
        { "label": "Тариф", "value": "Премиум" },
        { "label": "Баланс", "value": "4 900 ₸" }
      ]
    },
    {
      "title": "Заказы",
      "table": {
        "columns": ["Номер", "Статус"],
        "rows": [["5531", "Отправлено"], ["5480", "Доставлено"]]
      }
    }
  ]
}

У сотрудника, который нажал кнопку, откроется окно с этими разделами. Формат карточки и правила для другого JSON описаны в статье Ответы: что Polygram сохраняет.