API docs by Redocly

Fromni Bots API (1.0.0)

Download OpenAPI specification:Download

API для взаимодействия с платформой Fromni. В основном предназначено для запуска:

  • Кампаний - сценарии, при которых инициатором общения являетесь вы, т.е. бизнес. При этом ответ или возможное действие получателя заранее заложено в сценарии.
  • Нотификаций - вы хотите отправить пользователю сообщение и не ждете, что на него придет ответ. При этом отправка сообщения может вестись в том числе через WhatsApp Business API.

По своей сути Кампания - это обычный чат-бот. С той лишь разницей, что вы пишете Пользователю, а он вам отвечает. Поэтому для запуска любой Кампании важен Сценарий (какие сообщения отправлять, какие ответы могут прийти и т.д.), Каналы (через какие каналы передаются сообщения), Условия запуска (что должно случиться, чтобы кампания запустилась). Для удобства работы с платформой все Сценарии, Каналы и Условия запуска реализуются через WEB-интерфейс. По API же передаются События, которые должны запустить Кампанию, либо прямые команды на запуск Кампании.

Введение

Каждый метод является POST-запросом, который в случае успеха возвращает код 200, а в случае ошибки API - код 500.

Точка подключения: https://api.fromni.com/user

Формат данных: JSON

Кодировка: UTF-8

Заголовки

Authorization: Token xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx

Content-Type: application/json

Кампании

Кампании - исходящие коммуникации по определенному сценарию. Сценарий должен быть предварительно создан в конструкторе сценариев в WEB-интерфейсе. Там, в частности, "рисуется" логика работы Кампании и подключаются каналы, через которые отправляются сообщения.

Кампания завершена Webhook

Отправляет статистику завершенной кампании. Кампания считается завершенной, если все получатели прошли сценарий кампании (если он был) запущен или если истек liveTime кампании.

Request Body schema: application/json

Поле data совпадает с ответом метода /campaign/stat

type
required
string
required
object (CampaignResponse)

Responses

Request samples

Content type
application/json
{
  • "type": "campaign_completed",
  • "data": {
    }
}

Запущена автоматическая кампания Webhook

Отправляется при запуске автоматической кампании по сделкам / контактам. Статусы и каналы отправки в этом вебхуке не финальные, поэтому для получения результатов автоматической кампании стоит дождаться вебхук о завершении кампании.

Request Body schema: application/json
type
required
string
required
object

Request samples

Content type
application/json
{
  • "type": "auto_campaign_started",
  • "data": {
    }
}

Запустить кампанию

С помощью данного метода можно запускать кампании множеством способов.

По типу определения отправляемых сообщений:

  • по шаблону и сценарию (сценарий активируется после доставки шаблона);
  • по шаблону (для отправки достаточно передать ID шаблона и данные для вставки в поля шаблона);
  • по сценарию (сценарий должен быть связан с шаблоном, шаблон выберется автоматически);
  • с произвольным текстом для каждого канала (отправка любого текста в канал, где нет обязательной модерации сообщений);
  • по черновику (черновик содержит преднастроенные параметры кампании по одному из типов выше).

По типу определения получателей:

  • по списку номеров телефона и дополнительным данным о получателях;
  • по контактам, подходящим под фильтр контактов;
  • по контактам, имеющим сделки, подходящие под фильтр сделок, в указанном количестве;
  • по контактам, подходящим к обоим фильтрам выше.

По времени отправки:

  • мгновенная отправка;
  • отложенная отправка.
header Parameters
Content-Type
required
string
Example: application/json
Authorization
required
string
Example: Token xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx
Request Body schema: application/json
One of
name
required
string

Название кампании

customId
string

Ваш идентификатор кампании, который вернется вместе с колбэком о завершении кампании

liveTime
number [ 1 .. 48 ]
Default: 24

Время (в часах), в течение которого получатель может отвечать на кампанию

scenarioId
string,

ID сценария кампании, который будет запущен после получения пользователем первого сообщения

required
Array of objects (CampaignChannels)

Список каналов, по которым будет отправлятсья сообщение до первой доставки. Порядок каналов в массиве задает порядок отправки.

templateId
required
number

ID шаблона первого сообщения. Этот параметр не обязателен, если указанный сценарий связан с шаблоном в конструкторе сценариев или в параметре channels указан текст для каждого канала. Если передать отрицательное значение, то интерпретируется как ID группы шаблонов.

data
required
Array of objects (CampaignRecipientData)

Массив объектов с данными по каждому получателю. Объект может содержать произвольное количество полей, но должен иметь одинаковую структуру для каждого получателя

match
Array of strings (CampaignMatch)

Массив соответствий данных кампании (или события) и полей шаблона. Заголовок, соответствующий полю, в котором указан номер телефона получателя обязательно должен быть первым.

Responses

Request samples

Content type
application/json
Example
{
  • "name": "My campaign",
  • "customId": "123e4567-e89b-12d3-a456-426655440000",
  • "liveTime": 24,
  • "scenarioId": "5eb882228fdef800142e87c2",
  • "channels": [
    ],
  • "templateId": 1,
  • "data": [
    ],
  • "match": [
    ]
}

Response samples

Content type
application/json
{
  • "result": "success",
  • "id": "2c78e241008fedf822288be5"
}

Список отправленных кампаний

Возвращает список Кампаний, которые были запущены за указанный период. Метод может быть полезен для оценки количества кампаний, отправленных в определенный период и получения подробной статистики по конкретной Кампании.

header Parameters
Content-Type
required
string
Example: application/json
Authorization
required
string
Example: Token xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx
Request Body schema: application/json
object
offset
number
Default: 0

Отступ от начала списка

limit
number
Default: 10

Максимальное количество записей в ответе. Не указывайте этот параметр, если необходимо вернуть все записи.

order
Array of strings[ items ]

Параметры сортировки. Каждый элемент - массив, в котором 1-ый элемент - название поля, по которому идет сортировка, а 2-ой элмент - порядок сортировки (ASC или DESC)

object

Responses

Request samples

Content type
application/json
{
  • "filter": {
    },
  • "offset": 0,
  • "limit": 10,
  • "order": [
    ],
  • "options": {
    }
}

Response samples

Content type
application/json
{
  • "result": "success",
  • "data": [
    ]
}

Статистика по кампании

В отличие от возврата статистики на Callback-сервер, данный метод позволяет вам самостоятельно получить текущую статистику по кампании даже если она не завершена. Возвращает все параметры запущенной кампании, а также модифицированный список получателей в поле docs.

header Parameters
Content-Type
required
string
Example: application/json
Authorization
required
string
Example: Token xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx
Request Body schema: application/json
id
required
string

ID кампании

Responses

Request samples

Content type
application/json
{
  • "id": "2c78e241008fedf822288be5"
}

Response samples

Content type
application/json
{
  • "result": "success",
  • "id": "2c78e241008fedf822288be5",
  • "name": "My campaign",
  • "type": "STANDARD",
  • "liveTime": 48,
  • "channels": [
    ],
  • "scenarioId": "5eb882228fdef800142e87c2",
  • "templateId": 1,
  • "docs": [
    ],
  • "match": [
    ],
  • "headers": [
    ],
  • "customId": "123e4567-e89b-12d3-a456-426655440000",
  • "presetId": "65350f2b09c0fc0012d91715",
  • "createdAt": "2020-10-20T00:00:00.436Z"
}

Создать автоматическую кампанию / кампанию по событию

С помощью этого метода можно создать:

  • автоматическую кампанию с условием запуска по полям сделок или контактов;
  • автоматическую кампанию, запускающуюся каждый день в указанное время;
  • кампанию, запускающуюся по событию;
  • черновик кампании.
header Parameters
Content-Type
required
string
Example: application/json
Authorization
required
string
Example: Token xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx
Request Body schema: application/json
One of
name
required
string

Название кампании

liveTime
number [ 1 .. 48 ]
Default: 24

Время (в часах), в течение которого получатель может отвечать на кампанию

templateId
number

ID шаблона первого сообщения. Этот параметр не обязателен, если указанный сценарий связан с шаблоном в конструкторе сценариев или в параметре channels указан текст для каждого канала. Если передать отрицательное значение, то интерпретируется как ID группы шаблонов.

scenarioId
string,

ID сценария кампании, который будет запущен после получения пользователем первого сообщения

required
Array of Каналы кампании (objects) or Array of Каналы кампании с произвольными текстами (objects)
required
object

Параметры автоматической кампании

Responses

Request samples

Content type
application/json
Example
{
  • "name": "My campaign",
  • "liveTime": 24,
  • "templateId": 1,
  • "scenarioId": "5eb882228fdef800142e87c2",
  • "channels": [
    ],
  • "autoCampaign": {
    }
}

Response samples

Content type
application/json
Example
{
  • "result": "success",
  • "id": "655b4c21d122e90012a72834",
  • "name": "My campaign",
  • "liveTime": 24,
  • "templateId": 1,
  • "scenarioId": "5eb882228fdef800142e87c2",
  • "channels": [
    ],
  • "autoCampaign": {
    },
  • "active": true,
  • "lang": "ru",
  • "createdAt": "2021-04-09T09:55:09.782Z",
  • "updatedAt": "2021-04-09T09:55:09.782Z"
}

Получить список автоматических кампаний

header Parameters
Content-Type
required
string
Example: application/json
Authorization
required
string
Example: Token xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx
Request Body schema: application/json
Schema not provided

Responses

Response samples

Content type
application/json
{
  • "result": "success",
  • "data": [
    ]
}

Обновить автоматическую кампанию

Достаточно передать параметры, которые необходимо обновить. Например, для активации / деактивации достаточно передать ID автоматической кампании и параметр active.

header Parameters
Content-Type
required
string
Example: application/json
Authorization
required
string
Example: Token xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx
Request Body schema: application/json
One of
id
required
string

ID автоматической кампании

name
required
string

Название кампании

liveTime
number [ 1 .. 48 ]
Default: 24

Время (в часах), в течение которого получатель может отвечать на кампанию

templateId
number

ID шаблона первого сообщения. Этот параметр не обязателен, если указанный сценарий связан с шаблоном в конструкторе сценариев или в параметре channels указан текст для каждого канала. Если передать отрицательное значение, то интерпретируется как ID группы шаблонов.

scenarioId
string,

ID сценария кампании, который будет запущен после получения пользователем первого сообщения

required
Array of Каналы кампании (objects) or Array of Каналы кампании с произвольными текстами (objects)
required
object

Параметры автоматической кампании

active
boolean

Активна ли автоматическая кампания

Responses

Request samples

Content type
application/json
Example
{
  • "id": "655b4c21d122e90012a72834",
  • "name": "My campaign",
  • "liveTime": 24,
  • "templateId": 1,
  • "scenarioId": "5eb882228fdef800142e87c2",
  • "channels": [
    ],
  • "autoCampaign": {
    },
  • "active": true
}

Response samples

Content type
application/json
Example
{
  • "result": "success",
  • "id": "655b4c21d122e90012a72834",
  • "name": "My campaign",
  • "liveTime": 24,
  • "templateId": 1,
  • "scenarioId": "5eb882228fdef800142e87c2",
  • "channels": [
    ],
  • "autoCampaign": {
    },
  • "active": true,
  • "lang": "ru",
  • "createdAt": "2021-04-09T09:55:09.782Z",
  • "updatedAt": "2021-04-09T09:55:09.782Z"
}

Удалить автоматическую кампанию

header Parameters
Content-Type
required
string
Example: application/json
Authorization
required
string
Example: Token xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx
Request Body schema: application/json
id
required
string

ID автоматической кампании

Responses

Request samples

Content type
application/json
{
  • "id": "2c78e241008fedf822288be5"
}

Response samples

Content type
application/json
{
  • "result": "success"
}

Нотификации

Нотификации - возможность отправить пользователям односторонние сообщение с импользованием большинства имеющихся каналов. В рамках данного решения вы отправляете конкретное сообщение. Задача платформы - доставить это сообщение. При этом если для сообщения в вашем аккаунте будет найден шаблон, то сообщение автоматически уйдет теми каналами, для которых найденный шаблон был зарегистрирован/одобрен. Так может быть организована доставка сообщений, к примеру, через WhatsApp Business API. Если же шаблоны не будут обнаружены, сообщение автоматически переотправляется через SMS (необходимо, чтобы данный канал был подключен в аккаунте).

Отправить нотификацию

Если параметр channels не указан, то нотификация будет отправлена в соответствии с заданными настройками в аккаунте.

Отправка возможна по номеру телефона или по ID контакта. В любом случае сперва будет предпринята попытка найти цифровой профиль пользователя во Fromni. Затем по имеющимся идентификаторам в различных мессенджерах будет произведена попытка доставки нотификации в указанные каналы (до 1-ой успешной отправки).

Некоторые каналы позволяют прикреплять вложения (например, в Instagram и Viber - бизнес-сообщения доступно только 1 изображение; Notify и SMS не могут содержать вложений).

header Parameters
Content-Type
required
string
Example: application/json
Authorization
required
string
Example: Token xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx
Request Body schema: application/json
One of
phone
string

Номер получателя. Если не указан contactId, то поле обязательно.

contactId
string

ID контакта в CRM. Если не указан phone, то поле обязательно.

required
object (CampaignMessage)

Сообщение, отправляемое через канал(-ы)

required
Array of objects (CampaignChannels)

Список каналов, по которым будет отправлятсья сообщение до первой доставки. Порядок каналов в массиве задает порядок отправки.

Responses

Callbacks

Request samples

Content type
application/json
Example
{
  • "phone": 79000000000,
  • "contactId": "5f3cd834e8aadd00137359aa",
  • "message": {},
  • "channels": [
    ]
}

Response samples

Content type
application/json
{
  • "result": "success",
  • "id": "6062fdc861914f0013e793a2"
}

Callback payload samples

Callback
POST: Обновлен статус Нотификации
Content type
application/json
{
  • "type": "notification_message_updated",
  • "data": {
    }
}

События

События позволяют запускать Кампании автоматически. События могут быть созданы с помощью API-запроса или через WEB-интерфейс.

Каждое создаваемое событие имеет вычисляемый параметр tag. Все события, которые вы самостоятельно создадите, имеют tag "custom".

Список доступных событий

header Parameters
Content-Type
required
string
Example: application/json
Authorization
required
string
Example: Token xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx
Request Body schema: application/json
Schema not provided

Responses

Response samples

Content type
application/json
{
  • "result": "success",
  • "data": [
    ]
}

Создать событие

header Parameters
Content-Type
required
string
Example: application/json
Authorization
required
string
Example: Token xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx
Request Body schema: application/json
name
required
string

Имя события для передачи по API. Учтите, что имя НЕ должно содержать заглавные буквы и точки

displayName
string

Видимое в личном кабинете название события

Array of objects

Параметры события

Responses

Request samples

Content type
application/json
{
  • "name": "added_to_cart",
  • "displayName": "Добавлено в корзину",
  • "vars": [
    ]
}

Response samples

Content type
application/json
{
  • "result": "success",
  • "id": 1,
  • "name": "added_to_cart",
  • "displayName": "Добавлено в корзину",
  • "tag": "custom",
  • "vars": [
    ]
}

Передать событие

При передаче события в систему будет предпринята попытка найти связанную с ним Кампанию. Если таковая имеется, то она будет запущена, а в ответ будет возвращено ее id. Важно, чтобы номер телефона получателя также передавался в данных События, а путь до него был определен в переменных Кампании.

header Parameters
Content-Type
required
string
Example: application/json
Authorization
required
string
Example: Token xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx
Request Body schema: application/json
name
required
string

Имя события. Учтите, что имя НЕ должно содержать заглавные буквы

data
object

Любой объект, содержащий данные события

Responses

Request samples

Content type
application/json
{
  • "name": "added_to_cart",
  • "data": {
    }
}

Response samples

Content type
application/json
{
  • "result": "success",
  • "id": "2c78e241008fedf822288be5"
}

Шаблоны текстов

Шаблоны текстов необходимы для того, чтобы компания могла писать первой в каналах, где не разрешены произвольные текста.

Получить список шаблонов

header Parameters
Content-Type
required
string
Example: application/json
Authorization
required
string
Example: Token xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx
Request Body schema: application/json
offset
number
Default: 0

Отступ от начала списка

limit
number
Default: 10

Максимальное количество записей в ответе. Не указывайте этот параметр, если необходимо вернуть все записи.

order
Array of strings[ items ]

Параметры сортировки. Каждый элемент - массив, в котором 1-ый элемент - название поля, по которому идет сортировка, а 2-ой элмент - порядок сортировки (ASC или DESC)

Responses

Request samples

Content type
application/json
{
  • "offset": 0,
  • "limit": 10,
  • "order": [
    ]
}

Response samples

Content type
application/json
{
  • "result": "success",
  • "data": [
    ]
}

Создать шаблон

header Parameters
Content-Type
required
string
Example: application/json
Authorization
required
string
Example: Token xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx
Request Body schema: application/json
displayName
string

Название шаблона

text
required
string

Текст сообщения

name
String

Название шаблона в API

Array of objects

Массив каналов, через которые планируется отправлять данный шаблон

Responses

Request samples

Content type
application/json
{
  • "displayName": "Тестовый шаблон",
  • "text": "Привет! Это образец сообщения",
  • "name": "before_visit_10_min",
  • "channels": []
}

Response samples

Content type
application/json
{
  • "result": "success",
  • "id": 1,
  • "displayName": "Тестовый шаблон",
  • "text": "Тестовый шаблон от компании #COMPAY_NAME#.",
  • "regexpText": "^Тестовый шаблон от компании (.+).$",
  • "name": "before_visit_10_min",
  • "channels": [
    ]
}

Обновить текст шаблона

header Parameters
Content-Type
required
string
Example: application/json
Authorization
required
string
Example: Token xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx
Request Body schema: application/json
id
required
number

ID шаблона

text
required
string

Текст шаблона

Responses

Request samples

Content type
application/json
{
  • "id": 1,
  • "text": "Новый текст шаблона"
}

Response samples

Content type
application/json
{
  • "result": "success"
}

Добавить канал для шаблона

header Parameters
Content-Type
required
string
Example: application/json
Authorization
required
string
Example: Token xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx
Request Body schema: application/json
templateId
required
number

ID шаблона

required
object

Responses

Request samples

Content type
application/json
{
  • "templateId": 1,
  • "channel": {
    }
}

Response samples

Content type
application/json
{
  • "result": "success",
  • "templateId": 1,
  • "channel": "telegram",
  • "status": "moderate",
  • "updated_at": "2022-07-07T19:52:15.023Z"
}

Удалить канал из шаблона

header Parameters
Content-Type
required
string
Example: application/json
Authorization
required
string
Example: Token xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx
Request Body schema: application/json
templateId
required
number

ID шаблона

channel
required
string

Идентификатор канала

Responses

Request samples

Content type
application/json
{
  • "templateId": 1,
  • "channel": "telegram"
}

Response samples

Content type
application/json
{
  • "result": "success"
}

Создать группу шаблонов

Один шаблон может состоять только в одной группе. В группу нельзя объединить шаблоны, имеющие хотя бы один схожий канал.

header Parameters
Content-Type
required
string
Example: application/json
Authorization
required
string
Example: Token xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx
Request Body schema: application/json
name
required
string

Название группы

templates
required
Array of numbers

ID шаблонов, входяших в группу

Responses

Request samples

Content type
application/json
{
  • "name": "Тестовая группа шаблонов",
  • "templates": [
    ]
}

Response samples

Content type
application/json
{
  • "result": "success",
  • "id": 1,
  • "name": "Тестовая группа шаблонов",
  • "created_at": "2022-03-09T00:00:00.000Z",
  • "updated_at": "2022-03-09T00:00:00.000Z"
}

Обновить группу шаблонов

header Parameters
Content-Type
required
string
Example: application/json
Authorization
required
string
Example: Token xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx
Request Body schema: application/json
id
required
number

ID группы

name
required
string

Название группы

Responses

Request samples

Content type
application/json
{
  • "id": 1,
  • "name": "Новое название группы шаблонов"
}

Response samples

Content type
application/json
{
  • "result": "success",
  • "id": 1,
  • "name": "Новое название группы шаблонов",
  • "created_at": "2022-03-09T00:00:00.000Z",
  • "updated_at": "2022-03-09T00:00:00.000Z"
}

Добавить шаблон в группу

header Parameters
Content-Type
required
string
Example: application/json
Authorization
required
string
Example: Token xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx
Request Body schema: application/json
templateId
required
number

ID шаблона

templateGroupId
required
number

ID группы шаблонов

Responses

Request samples

Content type
application/json
{
  • "templateId": 1,
  • "templateGroupId": 1
}

Response samples

Content type
application/json
{
  • "result": "success"
}

Удалить шаблон из группы

header Parameters
Content-Type
required
string
Example: application/json
Authorization
required
string
Example: Token xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx
Request Body schema: application/json
templateId
required
number

ID шаблона

Responses

Request samples

Content type
application/json
{
  • "templateId": 1
}

Response samples

Content type
application/json
{
  • "result": "success"
}

Удалить шаблон

header Parameters
Content-Type
required
string
Example: application/json
Authorization
required
string
Example: Token xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx
Request Body schema: application/json
templateId
required
number

ID шаблона

Responses

Request samples

Content type
application/json
{
  • "templateId": 1
}

Response samples

Content type
application/json
{
  • "result": "success"
}

Медиа хранилище

Медиа-хранилище позволяет загружать файлы для получения прямой ссылки на них, которую можно указать для вложения при отправке сообщения. Также в хранилище сохраняются вложения из входящих сообщений пользователей.

Размер файла на данный момент ограничен 10Мб.

Получить параметры сервера для загрузки

Чтобы загрузить файл в хранилище, сначала необходимо получить параметры сервера для загрузки. Ответ содержит поле url - адрес, на который необходимо отправить POST-запрос с телом в формате FromData, ссылка действительна 1 час. Для каждого нового загружаемого элемента необходимо получать новые параметры.

Также ответ содержит объект fields, каждый ключ которого необходимо передать в исходном виде вместе с запросом как пару ключ-значение в FormData. Сам файл передается по ключу file и обязательно должен быть указан самым последним. В ответе возвращается поле mediaUrl, содержащее прямую ссылку на будущий загруженный файл, используйте ее для вставки в сообщение.

header Parameters
Content-Type
required
string
Example: application/json
Authorization
required
string
Example: Token xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx
Request Body schema: application/json
contentType
string

Тип файла, желательно указать во избежание ошибок

filename
required
string

Имя файла обязательно с расширением

Responses

Request samples

Content type
application/json
{
  • "contentType": "application/pdf",
  • "filename": "contract.pdf"
}

Response samples

Content type
application/json
{}

Контакты

Контакты - все пользователи, с которыми когда-либо велось взаимодействие. Для каждого из них во Fromni создается цифровой профиль, который включает в себя их идентификаторы в различных мессенджерах, публичные данные из мессенджеров, а также значения переменных.

Переменные контактов могут иметь следующие типы (поле type):

Тип Описание
STRING Строка
NUMBER Число
DATE Строка. Содержит дату в формате ISO
EMAIL Строка. Содержит email
SELECT Выбор. К переменной добавляется поле options - массив из возможных значений в виде строк

Создан новый контакт Webhook

Даже если был создан один контакт, то он все равно будет прислан в массиве.

Request Body schema: application/json
type
required
string
required
Array of objects (Контакт)

Responses

Request samples

Content type
application/json
{
  • "type": "contact_created",
  • "data": [
    ]
}

Обновлен контакт Webhook

Объект data содержит все поля контакта, а не только обновленные.

Request Body schema: application/json
type
required
string
required
object (Contact)

Responses

Request samples

Content type
application/json
{
  • "type": "contact_updated",
  • "data": {
    }
}

Контакты объединены Webhook

Контакты объединены, т.к. идентификаторы в одном из каналов совпали. Поле preservedContact содержит контакт, сохраненный после слияния, поле deletedContact - удаленный контакт.

Request Body schema: application/json
type
required
string
required
object

Responses

Request samples

Content type
application/json
{
  • "type": "contact_merged",
  • "data": {
    }
}

Список контактов

Для информации о том, как формировать фильтр контактов, см. Правила формирования фильтров контактов и сделок.

header Parameters
Content-Type
required
string
Example: application/json
Authorization
required
string
Example: Token xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx
Request Body schema: application/json
object (ContactsFilter)
offset
number
Default: 0

Отступ от начала списка

limit
number
Default: 10

Максимальное количество записей в ответе. Не указывайте этот параметр, если необходимо вернуть все записи.

order
Array of strings[ items ]

Параметры сортировки. Каждый элемент - массив, в котором 1-ый элемент - название поля, по которому идет сортировка, а 2-ой элмент - порядок сортировки (ASC или DESC)

Responses

Request samples

Content type
application/json
{
  • "filter": {
    },
  • "offset": 0,
  • "limit": 10,
  • "order": [
    ]
}

Response samples

Content type
application/json
{
  • "result": "success",
  • "data": [
    ],
  • "total": 100
}

Получить контакт по ID

Возвращает список контактов (телефон, профили, переменные и пр.).

header Parameters
Content-Type
required
string
Example: application/json
Authorization
required
string
Example: Token xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx
Request Body schema: application/json
id
required
string

ID контакта

Responses

Request samples

Content type
application/json
{
  • "id": "608044bd4eeb3c0013c2e21e"
}

Response samples

Content type
application/json
{
  • "result": "success",
  • "id": "5f3cd6d49ed4e10013083db0",
  • "phone": 79990000000,
  • "blacklisted": true,
  • "externalId": "12345",
  • "source": "booking_service",
  • "profiles": [
    ],
  • "createdAt": "2021-04-09T09:55:09.782Z",
  • "updatedAt": "2021-04-09T09:55:09.782Z",
  • "variables": [
    ]
}

Создать контакт

Создает контакты в CRM с указанным номером телефона и переменными.

header Parameters
Content-Type
required
string
Example: application/json
Authorization
required
string
Example: Token xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx
Request Body schema: application/json
Array
phone
required
string

Номер телефона контакта (номер начинается с '+')

blacklisted
bool
Default: false

Внесен ли контакт в черный список (если внесен, то контакт не будет получать ручные и автоматические рассылки, но ему все также можно написать через мессенджер)

externalId
string

ID контакта из внешнего источника

source
string

Название источника контакта

Array of objects

Список переменных

Responses

Request samples

Content type
application/json
[
  • {
    }
]

Response samples

Content type
application/json
{
  • "result": "success",
  • "data": [
    ]
}

Обновить контакт

Необходимо передавать только те параметры, которые нужно обновить. Если у контакта уже есть профиль с такими же profileId и channel, то обновится info, иначе создастся новый профиль.

header Parameters
Content-Type
required
string
Example: application/json
Authorization
required
string
Example: Token xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx
Request Body schema: application/json
contactId
required
string

ID контакта

phone
string

Номер телефона контакта (номер начинается с '+')

blacklisted
bool
Default: false

Внесен ли контакт в черный список (если внесен, то контакт не будет получать ручные и автоматические рассылки, но ему все также можно написать через мессенджер)

externalId
string

ID контакта из внешнего источника

source
string

Название источника контакта

object (ContactProfile)

Профиль контакта в соц. сети / мессенджере

Responses

Request samples

Content type
application/json
{
  • "contactId": "6062fdc861914f0013e793a2",
  • "phone": 79990000000,
  • "blacklisted": true,
  • "externalId": "12345",
  • "source": "booking_service",
  • "profile": {
    }
}

Response samples

Content type
application/json
{
  • "result": "success"
}

Список переменных

По умолчанию Вам доступны следующие переменные: Имя (строка), Фамилия (строка), День рождения (дата), Город (строка), Страна (строка), Пол (строка), Email (строка), Тег 1 (строка), Тег 2 (выбор). Значения этих переменных профиля заполняются данными из соц. сетей (например, ВКонтакте и Facebook), однако вы можете изменять эти значения.

header Parameters
Content-Type
required
string
Example: application/json
Authorization
required
string
Example: Token xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx
Request Body schema: application/json
any

Responses

Request samples

Content type
application/json
null

Response samples

Content type
application/json
{
  • "result": "success",
  • "data": [
    ]
}

Создать переменную

header Parameters
Content-Type
required
string
Example: application/json
Authorization
required
string
Example: Token xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx
Request Body schema: application/json
name
required
string

Имя переменной

type
string
Default: "STRING"
Enum: "STRING" "NUMBER" "DATE" "SELECT"
apiName
string

Название переменной (только a-z, 0-9 и _), которое нельзя изменить через интерфейс и которое используется для вставки значения переменной в текст шаблона (например, #contact.city#). Значение по умолчанию будет сгенерировано на основе name с использованием транслитерации

options
Array of strings or numbers or null

Список опций для переменной с типом SELECT и MULTISELECT

Responses

Request samples

Content type
application/json
{
  • "name": "Город",
  • "type": "STRING",
  • "apiName": "gorod",
  • "options": null
}

Response samples

Content type
application/json
{
  • "result": "success",
  • "id": "60b7f9b6163fec0007ecdaf0"
}

Обновить переменную

header Parameters
Content-Type
required
string
Example: application/json
Authorization
required
string
Example: Token xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx
Request Body schema: application/json
id
required
string

ID переменной

name
required
string

Имя переменной

type
required
string
Default: "STRING"
Enum: "STRING" "NUMBER" "DATE" "SELECT"
apiName
required
string

Название переменной (только a-z, 0-9 и _), которое нельзя изменить через интерфейс и которое используется для вставки значения переменной в текст шаблона (например, #contact.city#). Значение по умолчанию будет сгенерировано на основе name с использованием транслитерации

Responses

Request samples

Content type
application/json
{
  • "id": "60b7f9b6163fec0007ecdaf0",
  • "name": "Город",
  • "type": "STRING",
  • "apiName": "gorod"
}

Response samples

Content type
application/json
{
  • "result": "success"
}

Удалить переменную

header Parameters
Content-Type
required
string
Example: application/json
Authorization
required
string
Example: Token xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx
Request Body schema: application/json
id
required
string

ID переменной

Responses

Request samples

Content type
application/json
{
  • "id": "60b7f9b6163fec0007ecdaf0"
}

Response samples

Content type
application/json
{
  • "result": "success"
}

Установить переменные контакта

header Parameters
Content-Type
required
string
Example: application/json
Authorization
required
string
Example: Token xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx
Request Body schema: application/json
contactId
required
string

ID контакта

required
Array of objects

Список переменных

Responses

Request samples

Content type
application/json
{
  • "contactId": "608044bd4eeb3c0013c2e21e",
  • "variables": [
    ]
}

Response samples

Content type
application/json
{
  • "result": "success"
}

Проверить номера телефонов

Метод позволяет проверить правильность мобильных номеров в соответствии с региональными правилами и получить их в отформатированном виде.

header Parameters
Content-Type
required
string
Example: application/json
Authorization
required
string
Example: Token xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx
Request Body schema: application/json
phones
required
Array of strings

Массив номеров телефонов

Responses

Request samples

Content type
application/json
{
  • "phones": [
    ]
}

Response samples

Content type
application/json
{
  • "result": "success",
  • "data": [
    ]
}

Сделки

Сделки - раздел в CRM, в котором хранится история сделок с вашими клиентами. По созданным сделкам Вы можете отправлять автоматические кампании для уведомления клиентов или своих сотрудников.

Создать сделку

Метод поддерживает как одиночное, так и пакетное добавление сделок. При пакетном добавлении созданные сделки возвращаются в массиве data. Если при добавлении сделок в пакетном режиме произошла ошибка при создании какой-либо сделки, то в ответном массиве элемент с соответсвующим индексом будет содержать поле error с описанием ошибки.

header Parameters
Content-Type
required
string
Example: application/json
Authorization
required
string
Example: Token xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx
Request Body schema: application/json
One of
name
required
string

Название сделки

required
Array of objects (AttributeSimple)

Массив атрибутов сделки, у которых поле entity равно 'deal'

Array of objects

Список товаров/услуг, относящихся к сделке

contactId
required
string

ID контакта в системе Fromni, связанного со сделкой

externalId
string

ID сделки из внешнего источника

source
string

Название источника сделки

Responses

Request samples

Content type
application/json
Example
{
  • "name": "Название сделки",
  • "attributes": [
    ],
  • "products": [
    ],
  • "contactId": "6011cd57f1a1932d984f2bcc",
  • "externalId": "12345",
  • "source": "booking_service"
}

Response samples

Content type
application/json
{
  • "result": "success",
  • "id": "627c483de18d850013027b7b",
  • "name": "Название сделки",
  • "attributes": [
    ],
  • "products": [
    ],
  • "contactId": "6011cd57f1a1932d984f2bcc",
  • "externalId": "12345",
  • "source": "booking_service",
  • "createdAt": "2022-05-10T00:00:00.000Z",
  • "updatedAt": "2022-05-10T00:00:00.000Z"
}

Список сделок

Для информации о том, как формировать фильтр сделок, см. Правила формирования фильтров контактов и сделок.

header Parameters
Content-Type
required
string
Example: application/json
Authorization
required
string
Example: Token xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx
Request Body schema: application/json
object (DealsFilter)
offset
number
Default: 0

Отступ от начала списка

limit
number
Default: 10

Максимальное количество записей в ответе. Не указывайте этот параметр, если необходимо вернуть все записи.

order
Array of strings[ items ]

Параметры сортировки. Каждый элемент - массив, в котором 1-ый элемент - название поля, по которому идет сортировка, а 2-ой элмент - порядок сортировки (ASC или DESC)

Responses

Request samples

Content type
application/json
{
  • "filter": {
    },
  • "offset": 0,
  • "limit": 10,
  • "order": [
    ]
}

Response samples

Content type
application/json
{
  • "result": "success",
  • "data": [
    ],
  • "total": 1
}

Получить сделку по ID

header Parameters
Content-Type
required
string
Example: application/json
Authorization
required
string
Example: Token xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx
Request Body schema: application/json
id
required
string

ID сделки

Responses

Request samples

Content type
application/json
{
  • "id": "627c483de18d850013027b7b"
}

Response samples

Content type
application/json
{
  • "result": "success",
  • "id": "627c483de18d850013027b7b",
  • "name": "Название сделки",
  • "attributes": [
    ],
  • "products": [
    ],
  • "contactId": "6011cd57f1a1932d984f2bcc",
  • "externalId": "12345",
  • "source": "booking_service",
  • "createdAt": "2022-05-10T00:00:00.000Z",
  • "updatedAt": "2022-05-10T00:00:00.000Z"
}

Удалить сделку

Метод поддерживает как одиночное, так и пакетное удаление сделок. При пакетном удалении результат возвращается в массиве data. Если при удалении сделки в пакетном режиме произошла ошибка, то в ответном массиве элемент с соответсвующим индексом будет содержать поле error с описанием ошибки.

header Parameters
Content-Type
required
string
Example: application/json
Authorization
required
string
Example: Token xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx
Request Body schema: application/json
One of
id
required
string

ID сделки

Responses

Request samples

Content type
application/json
Example
{
  • "id": "627c483de18d850013027b7b"
}

Response samples

Content type
application/json
{
  • "result": "success",
  • "data": true
}

Обновить сделку

Учтите, что важно передать все атрибуты ранее созданной сделки, в противном случае значение атрибута будет отвязано от сделки (удалено). Вы можете указать новые атрибуты, в таком случае они добавятся к списку существующих атрибутов сделки.

Также обратите внимание, что для обновления атрибутов товаров/услуг сделки необходимо передать ID товара/сделки (поле id), полученные в ответе при создании сделки

header Parameters
Content-Type
required
string
Example: application/json
Authorization
required
string
Example: Token xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx
Request Body schema: application/json
name
required
string

Название сделки

required
Array of objects (AttributeSimple)

Массив атрибутов сделки, у которых поле entity равно 'deal'

Array of objects

Список товаров/услуг, относящихся к сделке

contactId
required
string

ID контакта в системе Fromni, связанного со сделкой

externalId
string

ID сделки из внешнего источника

source
string

Название источника сделки

Responses

Request samples

Content type
application/json
{
  • "name": "Название сделки",
  • "attributes": [
    ],
  • "products": [
    ],
  • "contactId": "6011cd57f1a1932d984f2bcc",
  • "externalId": "12345",
  • "source": "booking_service"
}

Response samples

Content type
application/json
{
  • "result": "success",
  • "id": "627c483de18d850013027b7b",
  • "name": "Название сделки",
  • "attributes": [
    ],
  • "products": [
    ],
  • "contactId": "6011cd57f1a1932d984f2bcc",
  • "externalId": "12345",
  • "source": "booking_service",
  • "createdAt": "2022-05-10T00:00:00.000Z",
  • "updatedAt": "2022-05-10T00:00:00.000Z"
}

Создать атрибут сделок

Атрибуты сделок могут иметь различный тип. Также атрибут относится к одной из сущностей: Сделка (deal) или Товар/услуга (product).

header Parameters
Content-Type
required
string
Example: application/json
Authorization
required
string
Example: Token xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx
Request Body schema: application/json
name
required
string

Название атрибута

type
required
string
Default: "STRING"
Enum: "STRING" "NUMBER" "DATE" "DATETIME" "BOOLEAN" "SELECT" "MULTISELECT"

Тип атрибута

options
Array of strings or numbers or null

Список опций для атрибутов с типом SELECT и MULTISELECT

required
bool
Default: false

Является ли атрибут обязательным при создании сделки

entity
string
Default: "deal"
Enum: "deal" "product"

Обозначение, к какой сущности относится атрибут. deal - общий атрибут сделок, product - атрибут товаров/услуг сделок

apiField
string

Путь до значения атрибута в исходном JSON-объекте сделки

active
bool
Default: true

Является ли атрибут активным. Если false, то атрибут не будет показан при создании сделки, но при этом значение атрибута будет отображаться для уже созданных сделок

apiName
string

Название атрибута (только a-z, 0-9 и _), которое нельзя изменить через интерфейс и которое используется для вставки значения атрибута в текст шаблона (например, #deal.city#). Значение по умолчанию будет сгенерировано на основе name с использованием транслитерации

Responses

Request samples

Content type
application/json
{
  • "name": "Город",
  • "type": "STRING",
  • "options": null,
  • "required": true,
  • "entity": "deal",
  • "apiField": "order.city",
  • "active": true,
  • "apiName": "gorod"
}

Response samples

Content type
application/json
{
  • "result": "success",
  • "id": "627c39f0e18d850013026ec5",
  • "name": "Город",
  • "type": "STRING",
  • "options": null,
  • "required": true,
  • "entity": "deal",
  • "apiField": "order.city",
  • "active": true,
  • "apiName": "gorod",
  • "isDefault": false,
  • "updatedAt": "2022-05-10T00:00:00.000Z"
}

Список атрибутов

По умолчанию Вам доступны следующие атрибуты: Статус (сущность - Сделка, тип - Выбор), Сумма (Сделка, Число), Наименование (Товар/услуга, Строка), Стоимость (Товар/услуга, Число).

header Parameters
Content-Type
required
string
Example: application/json
Authorization
required
string
Example: Token xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx
Request Body schema: application/json
object

Responses

Request samples

Content type
application/json
{ }

Response samples

Content type
application/json
{
  • "result": "success",
  • "data": [
    ]
}

Обновить атрибут

Для обновления достаточно передать только ID атрибута и обновляемые поля

header Parameters
Content-Type
required
string
Example: application/json
Authorization
required
string
Example: Token xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx
Request Body schema: application/json
id
required
string

ID атрибута

name
required
string

Название атрибута

type
required
string
Default: "STRING"
Enum: "STRING" "NUMBER" "DATE" "DATETIME" "BOOLEAN" "SELECT" "MULTISELECT"

Тип атрибута

options
Array of strings or numbers or null

Список опций для атрибутов с типом SELECT и MULTISELECT

required
bool
Default: false

Является ли атрибут обязательным при создании сделки

entity
string
Default: "deal"
Enum: "deal" "product"

Обозначение, к какой сущности относится атрибут. deal - общий атрибут сделок, product - атрибут товаров/услуг сделок

apiField
string

Путь до значения атрибута в исходном JSON-объекте сделки

active
bool
Default: true

Является ли атрибут активным. Если false, то атрибут не будет показан при создании сделки, но при этом значение атрибута будет отображаться для уже созданных сделок

apiName
string

Название атрибута (только a-z, 0-9 и _), которое нельзя изменить через интерфейс и которое используется для вставки значения атрибута в текст шаблона (например, #deal.city#). Значение по умолчанию будет сгенерировано на основе name с использованием транслитерации

isDefault
bool

Является ли атрибут атрибутом по умолчанию. Если true, то атрибут создан системой, если false - создан пользователем

updatedAt
string

Дата последнего обновления значения атрибута

Responses

Request samples

Content type
application/json
{
  • "id": "627c39f0e18d850013026ec5",
  • "name": "Город",
  • "type": "STRING",
  • "options": null,
  • "required": true,
  • "entity": "deal",
  • "apiField": "order.city",
  • "active": true,
  • "apiName": "gorod",
  • "isDefault": false,
  • "updatedAt": "2022-05-10T00:00:00.000Z"
}

Response samples

Content type
application/json
{
  • "result": "success",
  • "id": "627c39f0e18d850013026ec5",
  • "name": "Город",
  • "type": "STRING",
  • "options": null,
  • "required": true,
  • "entity": "deal",
  • "apiField": "order.city",
  • "active": true,
  • "apiName": "gorod",
  • "isDefault": false,
  • "updatedAt": "2022-05-10T00:00:00.000Z"
}

Удалить атрибут

header Parameters
Content-Type
required
string
Example: application/json
Authorization
required
string
Example: Token xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx
Request Body schema: application/json
id
required
string

ID атрибута

Responses

Request samples

Content type
application/json
{
  • "id": "627c39f0e18d850013026ec5"
}

Response samples

Content type
application/json
{
  • "result": "success"
}

Обновить значение атрибута сделки

Учтите, что с помощью этого метода можно только обновить значение атрибута, а не добавить новый или удалить старый.

header Parameters
Content-Type
required
string
Example: application/json
Authorization
required
string
Example: Token xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx
Request Body schema: application/json
dealId
string

ID сделки

attributeId
string

ID атрибута

productId
string or null

ID товара/услуги или null, если атрибут принадлежит сущности 'deal'

value
string or number or null

Новое значение атрибута

Responses

Request samples

Content type
application/json
{
  • "dealId": "627c483de18d850013027b7b",
  • "attributeId": "627c39f0e18d850013026ec5",
  • "productId": "627c483de18d850013027b85",
  • "value": "Санкт-Петербург"
}

Response samples

Content type
application/json
{
  • "result": "success"
}

Каналы и подключения

Каналы и их обозначения во Fromni:

Канал Обозначение
ВКонтакте vk
Instagram instagram
Telegram telegram
Viber - чат-боты viber-bots
Facebook fb
Whatsapp Business whatsapp-business
Whatsapp WEB whatsapp
Viber - бизнес-сообщения viber
SMS sms
Notify notify
Веб-чат webchat

Получить список подключений к каналам

header Parameters
Content-Type
required
string
Example: application/json
Authorization
required
string
Example: Token xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx
Request Body schema: application/json
any

Responses

Request samples

Content type
application/json
null

Response samples

Content type
application/json
{
  • "result": "success",
  • "data": {
    }
}

Callback-сервер

Callback-сервер также можно изменить в личном кабинке в разделе Настройки API.

Если попытка отправки уведомления потерпела неудачу (код ответа < 200 или >= 400 или ответ не был получен в отведенный таймаут), то будет произведено еще несколько попыток отправки. Количество попыток = 7. Интервал между попытками увеличивается следующим образом: 10 сек, 30 сек, 1.5 мин, 4.5 мин, 13.5 мин, 40.5 мин и 1 час.

Каждый запрос на callback-сервер имеет одинаковую структуру:

Поле Описание
type тип события
data данные события
secret строка, заданная при настройке адреса callback-сервера, для проверки подлинности запроса
attempt номер попытки (номер увеличивается на 1 после каждой неуспешной попытки)

Установить callback-сервер

header Parameters
Content-Type
required
string
Example: application/json
Authorization
required
string
Example: Token xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx
Request Body schema: application/json
callbackUrl
required
string

Адрес колбэк-сервера

secret
string

Произвольная строка, которая передается с каждым запросом на колбэк-сервер в отдельном поле secret. Позволяет удостовериться, что уведомление пришло от нашего сервера.

Responses

Request samples

Content type
application/json
{}

Response samples

Content type
application/json
{
  • "result": "success"
}

Получить параметры callback-сервера

header Parameters
Content-Type
required
string
Example: application/json
Authorization
required
string
Example: Token xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx
Request Body schema: application/json
any

Responses

Request samples

Content type
application/json
null

Response samples

Content type
application/json
{}

Мессенджер

В разделе описаны способы прямой связи с живыми операторами. Механизм запускается в момент, когда от Пользователя поступает такой тип входящего сообщения, который по Сценарию должен быть обработан специалистом на стороне Заказчика и через информационную систему Заказчика. Информация о входящем сообщении придет на Сallback-сервер (тип запроса - Инициирован новый диалог с оператором в Мессенджере). Далее вы сможете запросить историю сообщений диалога, используя метод Сообщения диалога.

Инициирован новый диалог с оператором Webhook

Объект data содержит основную информацию о диалоге.

Поле contact содержит известные идентификаторы контакта в различных мессенджерах (phone, vkId, instagramId и т.п.). Поле connection содержит информацию о подключении, в рамках которого был начат диалог, в том числе идентификатор канала (vk, whatsapp-business, fb, viber и т.д.)

Request Body schema: application/json
name
string
required
object (Conversation)

Responses

Request samples

Content type
application/json
{
  • "name": "conversation_operator_requested",
  • "data": {
    }
}

Получено новое сообщение от пользователя в рамках открытого диалога Webhook

Request Body schema: application/json
name
string
required
object

Responses

Request samples

Content type
application/json
{
  • "name": "conversation_message_created",
  • "data": {
    }
}

Список диалогов Deprecated

header Parameters
Content-Type
required
string
Example: application/json
Authorization
required
string
Example: Token xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx
Request Body schema: application/json
offset
number
Default: 0

Отступ от начала списка

limit
number
Default: 10

Максимальное количество записей в ответе. Не указывайте этот параметр, если необходимо вернуть все записи.

Responses

Request samples

Content type
application/json
{
  • "offset": 0,
  • "limit": 10
}

Response samples

Content type
application/json
{
  • "result": "success",
  • "data": [
    ]
}

Сообщения диалога Deprecated

Метод может быть полезен, чтобы подгрузить историю общения Пользователя с Ботом после подключения оператора к диалогу.

header Parameters
Content-Type
required
string
Example: application/json
Authorization
required
string
Example: Token xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx
Request Body schema: application/json
conversationId
string

ID диалога

Responses

Request samples

Content type
application/json
{
  • "conversationId": "5f3cd834e8aadd00137359aa"
}

Response samples

Content type
application/json
{
  • "result": "success",
  • "data": [
    ]
}

Отправить сообщение в диалог

Оператор может отправить сообщение в диалог, только если operatorMode диалога не истек.

header Parameters
Content-Type
required
string
Example: application/json
Authorization
required
string
Example: Token xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx
Request Body schema: application/json
conversationId
string

ID диалога

object

Responses

Callbacks

Request samples

Content type
application/json
{
  • "conversationId": "5f3cd834e8aadd00137359aa",
  • "message": {}
}

Response samples

Content type
application/json
{
  • "result": "success",
  • "messageId": 2,
  • "status": "sent",
  • "conversationId": "5f3cd834e8aadd00137359aa"
}

Callback payload samples

Callback
POST: Обновлен статус сообщения, отправленного пользователю через Мессенджер
Content type
application/json
{
  • "name": "conversation_message_updated",
  • "data": {
    }
}

Получить список доступных каналов

Позволяет получить имеющиеся у владельца номера телефона каналы, в которые можно написать первым.

header Parameters
Content-Type
required
string
Example: application/json
Authorization
required
string
Example: Token xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx
Request Body schema: application/json
phone
required
string

Номер телефона (номер начинается с '+')

Responses

Request samples

Content type
application/json
{
  • "phone": "+79990000000"
}

Response samples

Content type
application/json
{
  • "result": "success",
  • "data": [
    ]
}

Правила формирования фильтров контактов и сделок

Фильтры состоят из групп условий. Количество групп и условий внутри них неограничено. Группы условий и условия внутри них можно объединять с помощью параметра union:

Оператор Описание
and Соответствует всем условиям
or Соответствует любому условию

В условиях можно использовать следующие операторы (op) сравнения:

Оператор Описание Тип переменной/атрибута
eq Равно Все
neq Не равно Все
contains Содержит Строка
ncontains Не содержит Строка
lt Меньше Число
gt Больше Число
lte Меньше или равно Число
gte Больше или равно Число
before После Дата
after Перед Дата
has Содержит Массив
nhas Не содержит Массив
between Интервал Массив
period Период времени относительно времени применения фильтра Дата

Для всех операторов кроме between и period в поле value должно быть указано одно единственное значение для сравнения.

Для between в value должен быть указан массив, где первый элемент - дата начала интервала, второй элемент - конец.

  {
    "field": "...",
    "op": "between",
    "value": ["2023-10-01T00:00:00.000Z", "2023-10-15T23:59:59.999Z"]
  }

Для period поле value приобретает более сложную структуру. value должен быть объектом, который содержит 2 поля: from и to, каждое из которых задает смещение относительно времени применения фильтра. Поля from и to - массивы, 1-ым элементов которого является количество единиц времени (допускаются отрицательные значения), а 2-ым - сами единицы времени ("day", "week", "month"). Для даты, полученной из from, будет взято начало дня, для даты из to - конец дня. Примеры:

  // 5 дней назад
  {
    "field": "...",
    "op": "period",
    "value": { 
      "from": [-5, "day"],
      "to": [-5, "day"]
    }
  }

  // в течение месяца (следующие 30/31 дней)
  {
    "field": "...",
    "op": "period",
    "value": {
      "from": [0, "month"],
      "to": [1, "month"]
    }
  }

  // дата в будущем
  {
    "field": "...",
    "op": "period",
    "value": {
      "from": [0, "day"],
      "to": null
    }
  }

Возможные статусы сообщений

Статус Описание
sent Сообщение отправлено, ожидается финальный статус
unknown Статус неизвестен
rejected Сообщение отклонено Оператором
undelivered Сообщение не было доставлено
expired Время доставки истекло
delivered Сообщение доставлено
read Сообщение прочитано
unsupported Не поддерживается (только Notify)
error Отправка завершилась ошибкой
blocked_by_user Пользователь запретил отправку сообщений (только VK)
window_timeout Закрыто 24-часовое окно для общения с пользователем (только WABA)

История изменений

02.05.2024

  • Добавлен метод для создания событий.
  • Добавлен метод для проверки и форматирования номеров телефонов.
  • Добавлен метод для получения сделки по ID.
  • Добавлен фильтр параметров события (параметр eventFilter) для автоматических кампаний по событию.

22.11.2023

17.11.2023

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

03.05.2023

  • Добавлено поле apiName в переменные контактов и атрибуты сделок (см. Создать атрибут сделок и Создать переменную). Теперь для вставки значения переменной или атрибута в шаблон используется это поле вместо name (например, раньше - #deal.Название услуги#, сейчас - #deal.service_title#). Значение поля по умолчанию формируется на основе name и лишь в момент создания переменной или атрибута, при этом используется транслитерация, т.е. если name = Название услуги, то apiName = nazvanie_uslugi (при вставке в шаблон - #deal.nazvanie_uslugi#).

09.04.2023

  • Изменен формат данных контакта (добавлены поля profiles, blacklisted, externalId и source), в связи с чем изменены методы для создания, обновления и получения контактов.

01.12.2022

  • Добавлены вложения и клавиатура в качестве необязательных параметров при создании шаблонов

22.08.2022

07.07.2022

  • Добавлено описание всех методов для работы с шаблонами

12.05.2022

09.03.2022

25.02.2022

10.02.2022

07.02.2022

09.11.2021

01.11.2021

  • Обновлен метод Отправка нотификации. Теперь нотификация может содержать вложение, которое будет отправлено, если поддерживается каналом.
  • Тип поля "Тип переменной в цифровом профиле" изменен с числа на строку (0, 1, 2 заменено на STRING, NUMBER, DATE соответственно).

27.10.2021