Fromni Bots API

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

События

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

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

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

При передаче события в систему будет предпринята попытка найти связанную с ним Кампанию. Если таковая имеется, то она будет запущена, а в ответ будет возвращено ее 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
Schema not provided

Responses

Response samples

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

Кампании

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

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

Запустить кампанию (по шаблону и сценарию)

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

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

scenarioId
string,

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

required
Array of objects (Каналы кампании) [ items ]

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

templateId
required
number

ID шаблона первого сообщения. Если указанный сценарий связан с шаблоном в конструкторе сценариев, то этот параметр не обязателен

data
required
Array of objects (CampaignRecipientData) [ items ]

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

match
Array of strings

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

Responses

Callbacks

Request samples

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

Response samples

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

Callback payload samples

Callback
POST: Кампания завершена
Content type
application/json
{
  • "type": "campaign_completed",
  • "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
startDate
string

Начало периода

endDate
string

Конец периода

type
string or null
Enum: "event" "manual"

Тип кампании ("event" - кампании по событию, "manual" - кампании, запущенные напрямую)

Responses

Request samples

Content type
application/json
{
  • "startDate": "2021-01-21T00:00:00:000Z",
  • "endDate": "2021-02-21T00:00:00:000Z\"",
  • "type": "event"
}

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",
  • "liveTime": 48,
  • "channels": [
    ],
  • "scenarioId": "5eb882228fdef800142e87c2",
  • "templateId": 1,
  • "docs": [
    ],
  • "match": [
    ],
  • "headers": [
    ],
  • "createdAt": "2020-10-20T00:00:00.436Z"
}

Нотификации

Нотификации - возможность отправить пользователям односторонние сообщение с импользованием большинства имеющихся каналов. В рамках данного решения вы отправляете конкретное сообщение. Задача платформы - доставить это сообщение. При этом если для сообщения в вашем аккаунте будет найден шаблон, то сообщение автоматически уйдет теми каналами, для которых найденный шаблон был зарегистрирован/одобрен. Так может быть организована доставка сообщений, к примеру, через 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 (Сообщение кампании)

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

required
Array of objects (Каналы кампании) [ items ]

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

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": {
    }
}

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

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

Размер файла на данный момент ограничен 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
{}

Мессенджер

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

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

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

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

Request Body schema: application/json
name
required
string
required
object (Диалог)

Responses

Request samples

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

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

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

Responses

Request samples

Content type
application/json
{
  • "name": "conversation_message_created",
  • "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
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": [