Campaign API

Campaign API — это определенный программный интерфейс, который даёт возможность пользователям управлять массовыми и каскадными рассылками в приложении: создавать персонализированные цепочки сообщений, управлять контактными списками, отслеживать статистику доставки и т.д.

API для массовых и каскадных рассылок имеет широкое применение в различных отраслях и сферах деятельности. Он может быть использован для мобильного маркетинга, информирования клиентов о заказах и доставках, отправки уведомлений о событиях, проведения опросов и многое другое. Также API для массовых рассылок может быть интегрирован с CRM-системами, мобильными приложениями, веб-сервисами и другими платформами для создания полноценной коммуникационной стратегии.

Campaign API Exolve предлагает пользователям следующие методы для управления массовыми и каскадными рассылками:

  • Create — создает рассылку;

  • GetList — получает список созданных рассылок по заданным параметрам;

  • GetInfo — получает информацию об одной рассылке;

  • Update — обновляет имя и статус рассылки;

  • GetHistory — показывает все коммуникации в рассылке по заданным параметрам;

  • DownloadFileTemplate — скачивает шаблон файла со списком контактов;

  • UploadContactFile — загружает файл с контактами для рассылки;

  • GetFileInfo — получает информацию о загруженном файле со списком контактов;

  • DownloadFileError — загружает файл с контактами для рассылки;

  • DeleteFile — удаляет файл со списком контактов;

  • CreateCallListFromFile — создаёт список контактов из провалидированного файла;

  • GetCallList — получает информацию о списке контактов.

Метод Create

Примените этот метод для создания массовой каскадной или SMS-рассылки. Каскадная рассылка — это автоматизированная последовательная отправка уведомлений через голосовой и текстовый каналы. Например, можно запустить обзвон, а тем, до кого не получилось дозвониться, отправить SMS. Так вы быстрее сможете донести нужную информацию до ваших клиентов удобным для них способом.

Для создания рассылки выполните POST-запрос с входными параметрами к точке подключения, указанными ниже.

Точка подключения:

POST: https://api.exolve.ru/campaign/v1/Create

Авторизация

Передайте следующие Заголовки HTTP для успешной авторизации.

Имя Тип Описание
Authorization string API-ключ приложения с Bearer перед ним. Пример: Bearer e***s0, где e***s0 замените на API-ключ вашего приложения

Входные параметры

Передайте следующие параметры в теле запроса в JSON-формате. Параметры, отмеченные жирным шрифтом, являются обязательными.

Параметр Тип Описание
name string наименование рассылки
timezone boolean параметр учёта часового пояса. По умолчанию False - рассылка отправляется по московскому времени (UTC+3), True — учитывать часовой пояс, указанный в списке контактов
schedule Schedule расписание рассылки
oneof Channel один из каналов рассылки (текстовое SMS, голосовое SMS или каскадная рассылка)

Channel

Параметр Тип Описание
sms Sms канал рассылки — текстовое SMS
voice_message VoiceMessage канал рассылки — голосовое SMS (исходящий обзвон с предзаписанным аудио)
cascade Cascade каскадная рассылка (комбинация текстового и голосового каналов для последовательного уведомления абонентов)

Sms

Параметр Тип Описание
props SmsProps атрибуты сценария текстового SMS

SmsProps

Параметр Тип Описание
alpha_name string согласованное операторами имя, от которого отправляются текстовые SMS
text string текст сообщения

VoiceMessage

Параметр Тип Описание
props VoiceMessageProps атрибуты сценария голосового SMS

VoiceMessageProps

Параметр Тип Описание
voice_message_id string идентификатор ресурса голосового SMS
from string номер телефона Exolve, с которого отправляются голосовые SMS

Cascade

Параметр Тип Описание
elements CascadeElement структура каскадной рассылки. Один элемент (шаг) — один канал рассылки (текстовое или голосовое SMS). Максимум — 10 шагов

CascadeElement

Параметр Тип Описание
sms Sms канал рассылки — текстовое SMS
voice_message VoiceMessageChannel канал рассылки — голосовое SMS
condition enum Condition условие перехода к следующему каналу рассылки

SmsChannel

Параметр Тип Описание
props SmsProps атрибуты сценария текстового SMS
ttl string период времени в формате ’60s’, по истечении которого будет запрошен статус SMS (от 10 до 300 секунд).

VoiceMessageChannel

Параметр Тип Описание
props VoiceMessageProps атрибуты сценария голосового SMS

Condition

Параметр Тип Описание
1 enum звонок не принят/SMS не доставлено
2 enum звонок принят/SMS доставлено
3 enum в любом случае

Schedule

Параметр Тип Описание
days CallIntervalDays настройка интервалов рассылки по дням недели

CallIntervalDays

Параметр Тип Описание
mon CallInterval интервал понедельника
tue CallInterval интервал вторника
wed CallInterval интервал среды
thu CallInterval интервал четверга
fri CallInterval интервал пятницы
sat CallInterval интервал субботы
sun CallInterval интервал воскресенья

CallInterval

Параметр Тип Описание
from From/To время начала рассылки
to From/To время завершения рассылки

From/To

Параметр Тип Описание
hours uint32 час интервала
minutes uint32 минута интервала
seconds uint32 секунда интервала
nanos uint32 наносекунда интервала

Примечание

Если вы создаёте рассылку во время одного из указанных интервалов, рассылка будет запущена только при наступлении следующего интервала. Например, если вы создаете рассылку с расписанием с понедельника по среду с 10:00 по 13:00 МСК в понедельник в 10:30 МСК, то первая рассылка будет запущена только на следующий день, то есть во вторник в 10:00 МСК.

Если при создании рассылки вы не укажете интервалы расписания, рассылка будет запускаться по расписанию по умолчанию - с понедельника по пятницу с 9:00 до 18:00 МСК.

Выходные параметры

Параметр Тип Описание
campaign_id uint64 идентификатор рассылки

Возможные ошибки

Код Статус Пример сообщения Описание
404 Not Found Not Found некорректный URL запроса
401 Unauthorized invalid token невалидный API-ключ
400 Bad Request token is empty в запросе не передан API-ключ
400 Bad Request couldn’t parse incoming jwt token: couldn’t parse token: invalid character ‘[character]’ looking for beginning of value невалидный API-ключ
404 Not Found invalid alpha name: alpha name is not found введённое имя отправителя (альфа-имя) для текстовой SMS не принадлежит приложению
404 Not Found invalid number: number not found введённый номер телефона для голосовой SMS не принадлежит приложению
404 Not Found couldn’t find voice message scenario [voice_message_id]: scenario not found введённый идентификатор ресурса голосового SMS не принадлежит приложению
409 Conflict couldn’t create campaign: campaign already exists рассылка с указанными параметрами уже существует
400 Bad Request invalid SmsProps.AlphaName: value length must be between 3 and 11 runes, inclusive поле alpha_name содержит некорректное количество символов (корректно от 3 до 11 символов)
400 Bad Request invalid VoiceMessageProps.From: value length must be between 1 and 14 runes, inclusive поле from содержит некорректное количество символов (корректно от 1 до 14 символов)
400 Bad Request invalid CreateRequest.Name: value length must be between 3 and 40 runes, inclusive поле name содержит некорректное количество символов (корректно от 3 до 40 символов)
400 Bad Request invalid value for string type: [value] невалидное значение в одном из полей
400 Bad Request invalid character " after object key:value pair в запросе пропущена запятая в одном из параметров

Примеры

Входные параметры:

Канал рассылки - текстовое SMS

{
    "name": "test",
    "timezone": true,
    "sms": {
        "props": {
            "alpha_name": "shop",
            "text": "Приходите к нам в магазин!"
        }
    }
}

Канал рассылки - голосовое SMS

{
    "name": "test",
    "timezone": true,
    "voice_message": {
        "props": {
            "voice_message_id": "41117356-c9d5-4c94-8c62-68d7d2dac285",
            "from": "79991112233"
        }
    }
}

Каскадная рассылка

{ 
    "name": "Рассылка с расписанием",
    "cascade": {
        "elements": [
            {
                "sms": {
                    "props": {
                        "alpha_name": "shop",
                        "text": "Приходите к нам!"
                    }
                },
                "condition": "1"
            },
            {
                "voice_message": {
                    "props": {
                        "voice_message_id": "353b86e0-a62c-47d4-9b94-8dba32c922fc",
                        "from": "79991112233"
                    }
                }
            }
        ]
    },
    "schedule": {
        "days": {
            "mon": {
                "intervals": [
                    {
                        "from": {
                            "hours": 10,
                            "minutes": 0,
                            "seconds": 0,
                            "nanos": 0
                        },
                        "to": {
                            "hours": 15,
                            "minutes": 30,
                            "seconds": 0,
                            "nanos": 0
                        }
                    }
                ]
            }
        }
    }
}

Выходные параметры:

{
    "campaign_id": "130370354778222592"
}

Метод GetList

Примените этот метод для получения списка созданных рассылок по заданным параметрам (если параметры не заданы, выводятся все созданные рассылки). Для этого выполните POST-запрос с входными параметрами к точке подключения, указанными ниже.

Точка подключения:

POST: https://api.exolve.ru/campaign/v1/GetList

Авторизация

Передайте следующие Заголовки HTTP для успешной авторизации.

Имя Тип Описание
Authorization string API-ключ приложения с Bearer перед ним. Пример: Bearer e***s0, где e***s0 замените на API-ключ вашего приложения

Входные параметры

Передайте следующие параметры в теле запроса в JSON-формате. Параметры, отмеченные жирным шрифтом, являются обязательными.

Параметр Тип Описание
campaign_type enum CampaignType тип (канла) рассылки
campaign_id uint64 идентификатор рассылки
name string наименование рассылки
status enum CampaignStatus статус рассылки
date_from string дата создания рассылки в формате RFC-3339 / ISO-8601, от которой начинать выборку
date_to string дата создания рассылки в формате RFC-3339 / ISO-8601, до которой продолжать выборку

CampaignType

Параметр Тип Описание
1 enum текстовые SMS
2 enum голосовые SMS
3 enum каскадная рассылка

CampaignStatus

Параметр Тип Описание
1 enum черновик
2 enum рассылка остановлена пользователем
3 enum рассылка остановлена из-за нехватки баланса
4 enum рассылка в процессе выполнения
5 enum рассылка завершена

Выходные параметры

Параметр Тип Описание
items CampaignItem список найденных рассылок

CampaignItem

Параметр Тип Описание
id uint64 идентификатор рассылки
name string наименование рассылки
scenario_id string идентификатор сценария
call_list_id uint64 идентификатор списка получателей
call_list_total uint64 количество записей в списке получателей
timezone boolean параметр учёта часового пояса. По умолчанию False — рассылка отправляется по московскому времени (UTC+3), True — учитывать часовой пояс, указанный в CallList
type enum CampaignType тип рассылки (канал рассылки)
status enum CampaignStatus статус рассылки
created_at дата создания рассылки в формате RFC-3339 / ISO-8601
oneof Channel один из каналов рассылки (текстовое SMS, голосовое SMS или каскадная рассылка)

Channel

Параметр Тип Описание
sms Sms канал рассылки — текстовое SMS
voice_message VoiceMessage канал рассылки — голосовое SMS
cascade Cascade каскадная рассылка (последовательное уведомление абонентов в разных каналах)

Sms

Параметр Тип Описание
props SmsProps атрибуты сценария текстового SMS

SmsProps

Параметр Тип Описание
alpha_name string имя отправителя (альфа-имя), от которого отправляются текстовые SMS
text string текст сообщения

VoiceMessage

Параметр Тип Описание
props VoiceMessageProps атрибуты сценария голосового SMS

VoiceMessageProps

Параметр Тип Описание
voice_message_id string идентификатор ресурса голосового SMS
from string номер телефона МТС Exolve, с которого отправляются голосовые SMS

Cascade

Параметр Тип Описание
elements CascadeElement структура каскадной рассылки. Один элемент — один канал рассылки (текстовое или голосовое SMS)

CascadeElement

Параметр Тип Описание
sms Sms канал рассылки - текстовое SMS
voice_message VoiceMessageChannel канал рассылки — голосовое SMS
condition enum Condition условие перехода к следующему каналу рассылки

SmsChannel

Параметр Тип Описание
props SmsProps атрибуты сценария текстового SMS
ttl string период времени, по истечении которого будет запрошен статус SMS (от 10 до 300 секунд)

VoiceMessageChannel

Параметр Тип Описание
props VoiceMessageProps атрибуты сценария голосового SMS

Condition

Параметр Тип Описание
1 enum звонок не принят/сSMSмс не доставлено
2 enum звонок принят/SMS доставлено
3 enum в любом случае

Возможные ошибки

Код Статус Пример сообщения Описание
404 Not Found Not Found некорректный URL-адрес запроса
401 Unauthorized invalid token невалидный API-ключ
400 Bad Request token is empty в запросе не передан API-ключ
400 Bad Request couldn’t parse incoming jwt token: couldn’t parse token: invalid character ‘[character]’ looking for beginning of value невалидный API-ключ
400 Bad Request invalid character ‘[character]’ looking for beginning of value невалидное или пустое значение в одном из полей
400 Bad Request invalid value for uint64 type: ‘[value]’ невалидное или пустое значение в одном из полей с типом uint64
400 Bad Request invalid character " after object key:value pair в запросе пропущена запятая в одном из параметров

Примеры

Входные параметры:

{
    "date_from" : "2023-12-01T12:40:23.832213Z",
    "date_to" : "2023-12-28T15:40:23.832213Z"
}

Выходные параметры:

{
    "items": [
        // Текстовая SMS рассылка
        {
            "id": "130366147371216896",
            "name": "SMS Campaign",
            "scenario_id": "e1b9ae25-f36c-44b8-a327-ac46d414e180",
            "call_list_id": "130366147266359296",
            "timezone": true,
            "type": "1",
            "status": "1",
            "created_at": "2023-12-26T17:48:31.619796Z",
            "sms": {
                "props": {
                    "alpha_name": "SHOP",
                    "text": "Приходите к нам!"
                }
            }
        },
        // Голосовая SMS рассылка
        {
            "id": "130334219200901120",
            "name": "Voice Message Campaign",
            "scenario_id": "bb33e01b-9ec3-4d44-955c-c4cac2d23971",
            "call_list_id": "130334219041517568",
            "timezone": true,
            "type": "CAMPAIGN_TYPE_VOICE",
            "status": "CAMPAIGN_STATUS_IS_STOP",
            "created_at": "2023-12-26T15:41:39.350391Z",
            "voice_message": {
                "props": {
                    "voice_message_id": "41117356-c9d5-4c94-8c62-68d7d2dac285",
                    "from": "79991112233"
                }
            }
        },
        // Каскадная рассылка
        {
            "id": "130369523110653952",
            "name": "Cascade",
            "scenario_id": "a466b60e-ca5a-4da8-b60c-bc9cb9e6fd8a",
            "call_list_id": "130369523102265344",
            "type": "CAMPAIGN_TYPE_CASCADE",
            "status": "CAMPAIGN_STATUS_IS_RUN",
            "created_at": "2023-12-26T18:01:56.458047Z",
            "cascade": {
                "elements": [
                    {
                        "sms": {
                            "props": {
                                "alpha_name": "Shop",
                                "text": "Скидка 10% на все товары!"
                            },
                            "ttl": "10s"
                        },
                        "condition": "1"
                    },
                    {
                        "voice_message": {
                            "props": {
                                "voice_message_id": "353b86e0-a62c-47d4-9b94-8dba32c922fc",
                                "from": "79998889900"
                            }
                        }
                    }
                ]
            }
        }
    ]
}

Метод GetInfo

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

Точка подключения:

POST: https://api.exolve.ru/campaign/v1/GetInfo

Авторизация

Передайте следующие Заголовки HTTP для успешной авторизации.

Имя Тип Описание
Authorization string API-ключ приложения с Bearer перед ним. Пример: Bearer e***s0, где e***s0 замените на API-ключ вашего приложения

Входные параметры

Передайте следующие параметры в теле запроса в JSON-формате. Параметры, отмеченные жирным шрифтом, являются обязательными.

Параметр Тип Описание
id uint64 идентификатор рассылки

Выходные параметры

Параметр Тип Описание
campaign_info CampaignInfo информация о рассылки
schedule Schedule расписание рассылки по дням недели

CampaignInfo

Параметр Тип Описание
id uint64 идентификатор рассылки
name string наименование рассылки
scenario_id string идентификатор сценария
call_list CallListInfo информация о списке получателей

CallListInfo

Параметр Тип Описание
id uint64 идентификатор списка получателей
file_infos ContactFileInfo информация о файле со списком получателей
total uint64 количество контактов в файле
timezone boolean параметр учёта часового пояса. По умолчанию False - рассылка отправляется по московскому времени (UTC+3), True - учитывать часовой пояс, указанный в CallList
type enum CampaignType тип рассылки (канал рассылки)
status enum CampaignStatus статус рассылки
created_at string дата создания рассылки в формате RFC-3339 / ISO-8601
oneof Channel один из каналов рассылки (текстовое SMS, голосовое SMS или каскадная рассылка)

CampaignType

Параметр Тип Описание
1 enum текстовые SMS
2 enum голосовые SMS
3 enum каскадная рассылка

CampaignStatus

Параметр Тип Описание
1 enum черновик
2 enum рассылка остановлена пользователем
3 enum рассылка остановлена из-за нехватки баланса
4 enum рассылка в процессе выполнения
5 enum рассылка завершена

Channel

Параметр Тип Описание
sms Sms канал рассылки — текстовое SMS
voice_message VoiceMessage канал рассылки — голосовое SMS
cascade Cascade каскадная рассылка (последовательное уведомление абонентов в разных каналах)

Sms

Параметр Тип Описание
props SmsProps атрибуты сценария текстового SMS

SmsProps

Параметр Тип Описание
alpha_name string имя отправителя (альфа-имя), от которого отправляются текстовые SMS
text string текст сообщения

VoiceMessage

Параметр Тип Описание
props VoiceMessageProps атрибуты сценария голосового SMS

VoiceMessageProps

Параметр Тип Описание
voice_message_id string идентификатор ресурса голосового SMS
from string номер телефона МТС Exolve, с которого отправляются голосовые SMS

Cascade

Параметр Тип Описание
elements CascadeElement структура каскадной рассылки. Один элемент — один канал рассылки (текстовое или голосовое SMS)

CascadeElement

Параметр Тип Описание
sms Sms канал рассылки — текстовое SMS
voice_message VoiceMessageChannel канал рассылки — голосовое SMS
condition enum Condition условие перехода к следующему каналу рассылки

SmsChannel

Параметр Тип Описание
props SmsProps атрибуты сценария текстового SMS
ttl string период времени, по истечении которого будет запрошен статус SMS (от 10 до 300 секунд)

VoiceMessageChannel

Параметр Тип Описание
props VoiceMessageProps атрибуты сценария голосового SMS

Condition

Параметр Тип Описание
1 enum звонок не принят/SMS не доставлено
2 enum звонок принят/SMS доставлено
3 enum в любом случае

ContactFileInfo

Параметр Тип Описание
name string имя файла
total uint64 количество контактов в файле
created_at string дата создания файла в формате RFC-3339 / ISO-8601

Schedule

Параметр Тип Описание
days CallIntervalDays настройка интервалов рассылки по дням недели

CallIntervalDays

Параметр Тип Описание
mon CallInterval интервал понедельника
tue CallInterval интервал вторника
wed CallInterval интервал среды
thu CallInterval интервал четверга
fri CallInterval интервал пятницы
sat CallInterval интервал субботы
sun CallInterval интервал воскресенья

CallInterval

Параметр Тип Описание
from From/To время начала рассылки
to From/To время завершения рассылки

From/To

Параметр Тип Описание
hours uint32 час интервала
minutes uint32 минута интервала
seconds uint32 секунда интервала
nanos uint32 наносекунда интервала

Возможные ошибки

Код Статус Пример сообщения Описание
404 Not Found Not Found некорректный URL-адрес запроса
401 Unauthorized invalid token невалидный API-ключ
400 Bad Request token is empty в запросе не передан API-ключ
400 Bad Request couldn’t parse incoming jwt token: couldn’t parse token: invalid character ‘[character]’ looking for beginning of value невалидный API-ключ
404 Not Found couldn’t get info from campaign by id = [id]: campaign not found в приложении не найдена рассылка с указанным ID
400 Bad Request invalid GetInfoRequest.Id: value must be greater than 0 поле ID и его значение отсутствуют в запросе
400 Bad Request invalid character ‘[character]’ looking for beginning of value невалидное значение в поле id
400 Bad Request invalid value for uint64 type: ‘[value]’ невалидное или пустое значение в поле id с типом uint64

Примеры

Входные параметры:

{
    "id": 129931120807677952
}

Выходные параметры:

{
    "campaign_info": {
        "id": "129931120807677952",
        "name": "Каскадна рассылка",
        "scenario_id": "4cdf14bb-a23f-470b-a0a5-0e201cd5ca52",
        "call_list": {
            "id": "129931120799289344",
            "file_infos": [
                {
                    "name": "receivers.csv",
                    "total": "2",
                    "created_at": "2023-12-25T13:00:16.849Z"
                }
            ],
            "total": "2"
        },
        "type": "3",
        "status": "4",
        "created_at": "2023-12-25T12:59:53.204100Z",
        "cascade": {
            "elements": [
                {
                    "sms": {
                        "props": {
                            "alpha_name": "SHOP",
                            "text": "Скидка 10% на все!"
                        },
                        "ttl": "10s"
                    },
                    "condition": "1"
                },
                {
                    "voice_message": {
                        "props": {
                            "voice_message_id": "353b86e0-a62c-47d4-9b94-8dba32c922fc",
                            "from": "79998889900"
                        }
                    }
                }
            ]
        }
    },
    "schedule": {
        "days": {
            "mon": {
                "intervals": [
                    {
                        "from": {
                            "hours": 9
                        },
                        "to": {
                            "hours": 18
                        }
                    }
                ]
            },
            "tue": {
                "intervals": [
                    {
                        "from": {
                            "hours": 9
                        },
                        "to": {
                            "hours": 18
                        }
                    }
                ]
            },
            "wed": {
                "intervals": [
                    {
                        "from": {
                            "hours": 9
                        },
                        "to": {
                            "hours": 18
                        }
                    }
                ]
            },
            "thu": {
                "intervals": [
                    {
                        "from": {
                            "hours": 9
                        },
                        "to": {
                            "hours": 18
                        }
                    }
                ]
            },
            "fri": {
                "intervals": [
                    {
                        "from": {
                            "hours": 9
                        },
                        "to": {
                            "hours": 18
                        }
                    }
                ]
            },
            "sat": {},
            "sun": {}
        }
    }
}

Метод Update

Примените этот метод для обновления имени и статуса рассылки. Для этого выполните POST-запрос с входными параметрами к точке подключения, указанными ниже.

Точка подключения:

POST: https://api.exolve.ru/campaign/v1/Update

Авторизация

Передайте следующие Заголовки HTTP для успешной авторизации.

Имя Тип Описание
Authorization string API-ключ приложения с Bearer перед ним. Пример: Bearer e***s0, где e***s0 замените на API-ключ вашего приложения

Входные параметры

Передайте следующие параметры в теле запроса в JSON-формате. Параметры, отмеченные жирным шрифтом, являются обязательными.

Параметр Тип Описание
id uint64 идентификатор рассылки
name string наименование рассылки
status enum CampaignStatus статус рассылки

CampaignStatus

Параметр Тип Описание
2 enum остановить рассылку
4 enum начать выполнение рассылки
5 enum завершить рассылку

Примечание

  • Невозможно начать выполнение рассылки при отсутствии списка получателей.
  • Нельзя изменить статус завершённой рассылки.

Выходные параметры

Пустой JSON с 200 OK статусом.

Возможные ошибки

Код Статус Пример сообщения Описание
404 Not Found Not Found некорректный URL-адрес запроса
401 Unauthorized invalid token невалидный API-ключ
400 Bad Request token is empty в запросе не передан API-ключ
400 Bad Request couldn’t parse incoming jwt token: couldn’t parse token: invalid character ‘[character]’ looking for beginning of value невалидный API-ключ
404 Not Found couldn’t get info from campaign by id = [id]: campaign not found в приложении не найдена рассылка с указанным ID
400 Bad Request invalid character ‘[character]’ looking for beginning of value невалидное значение в одном из полей
400 Bad Request invalid UpdateRequest.Id: value must be greater than 0 поле id и его значение отсутствуют в запросе
400 Bad Request invalid value for uint64 type: ‘[value]’ невалидное или пустое значение в поле id с типом uint64
400 Bad Request invalid character " after object key:value pair в запросе пропущена запятая в одном из параметров

Примеры

Входные параметры:

{
    "id": "129883751852937216",
    "name": "SHOP",
    "status": 2
}

Выходные параметры:

{}

Метод GetHistory

Примените этот метод для просмотра всех коммуникаций в рассылке по заданным параметрам (если параметры не указаны, выводятся все коммуникации в рамках рассылки). Для этого выполните POST-запрос с входными параметрами к точке подключения, указанными ниже.

Точка подключения:

POST: https://api.exolve.ru/campaign/v1/GetHistory

Авторизация

Передайте следующие Заголовки HTTP для успешной авторизации.

Имя Тип Описание
Authorization string API-ключ приложения с Bearer перед ним. Пример: Bearer e***s0, где e***s0 замените на API-ключ вашего приложения

Входные параметры

Передайте следующие параметры в теле запроса в JSON-формате. Параметры, отмеченные жирным шрифтом, являются обязательными.

Параметр Тип Описание
campaign_id uint64 идентификатор рассылки
ids array of uint64 идентификаторы коммуникаций
to string номер получателя
limit uint32 лимит выводимых данных
offset uint32 номер строки, с которой начинать выборку (начинается с 0)

Выходные параметры

Параметр Тип Описание
campaign_id uint64 идентификатор рассылки
call_list_id uint64 идентификатор списка получателей
items HistoryItem параметры коммуникации
limit uint32 лимит выводимых данных
offset uint32 номер строки, с которой начинается выборка (начинается с 0)
total uint64 количество коммуникаций

HistoryItem

Параметр Тип Описание
id string идентификатор коммуникации
to string номер получателя
timezone uint32 часовой пояс получателя (по умолчанию 3 - UTC+3)
status enum CallListStatus статус коммуникации

CallListStatus

Параметр Тип Описание
CALL_LIST_STATUS_DRAFT enum черновик
CALL_LIST_STATUS_IS_PROGRESS enum в процессе выполнения
CALL_LIST_STATUS_IS_STOP enum остановлена пользователем
CALL_LIST_STATUS_IS_QUEUE enum в очереди
CALL_LIST_STATUS_IS_RUN enum начата
CALL_LIST_STATUS_IS_FINISHED enum закончена
CALL_LIST_STATUS_FAILED enum неуспешна
CALL_LIST_STATUS_PROHIBITED enum недостаточно средств для выполнения коммуникации
CALL_LIST_STATUS_EXTERNAL enum ошибка отправки на сервисе
CALL_LIST_STATUS_REMOTELY enum отменена пользователем

Возможные ошибки

Код Статус Пример сообщения Описание
404 Not Found Not Found некорректный URL-адрес запроса
401 Unauthorized invalid token невалидный API-ключ
400 Bad Request token is empty в запросе не передан API-ключ
400 Bad Request couldn’t parse incoming jwt token: couldn’t parse token: invalid character ‘[character]’ looking for beginning of value невалидный API-ключ
404 Not Found couldn’t get info from campaign by id = [id]: campaign not found в приложении не найдена рассылка с указанным ID
400 Bad Request invalid GetHistoryRequest.CampaignId: value must be greater than 0 поле campaign_id и его значение отсутствуют в запросе
400 Bad Request invalid character ‘[character]’ looking for beginning of value невалидное значение в поле campaign_id
400 Bad Request invalid value for uint64 type: ‘[value]’ невалидное или пустое значение в поле campaign_id с типом uint64

Примеры

Входные параметры:

{
    "campaign_id": 129886921253588992
}

Выходные параметры:

{
    "campaign_id": "129886921253588992",
    "call_list_id": "129886921245200384",
    "items": [
        {
            "id": "129928904844120064",
            "to": "79991112233",
            "timezone": 3,
            "status": "CALL_LIST_STATUS_IS_PROGRESS"
        },
        {
            "id": "129928904844120065",
            "to": "79995556677",
            "timezone": 3,
            "status": "CALL_LIST_STATUS_IS_FINISHED"
        }
    ],
    "limit": 3000,
    "total": "2"
}

Метод DownloadFileTemplate

Примените этот метод для получения шаблона файла со списком контактов. Для этого выполните POST-запрос с входными параметрами к точке подключения, указанными ниже.

Точка подключения:

POST: https://api.exolve.ru/campaign/v1/DownloadFileTemplate

Авторизация

Передайте следующие Заголовки HTTP для успешной авторизации.

Имя Тип Описание
Authorization string API-ключ приложения с Bearer перед ним. Пример: Bearer e***s0, где e***s0 замените на API-ключ вашего приложения

Входные параметры

Пустой JSON.

Выходные параметры

Параметр Тип Описание
file File файл с шаблоном для списка контактов

File

Параметр Тип Описание
name string название шаблона
mime_type string тип объекта для браузера
content bytes шаблон файла в формате base64 с указанием обязательных заголовков

Возможные ошибки

Код Статус Пример сообщения Описание
404 Not Found Not Found некорректный URL-адрес запроса
401 Unauthorized invalid token невалидный API-ключ
400 Bad Request token is empty в запросе не передан API-ключ
400 Bad Request couldn’t parse incoming jwt token: couldn’t parse token: invalid character ‘[character]’ looking for beginning of value невалидный API-ключ

Примеры

Входные параметры:

{}

Выходные параметры:

{
    "file": {
        "name": "template.csv",
        "mime_type": "text/csv",
        "content": "bnVtYmVyO3RpbWUgem9uZQo="
    }
}

Метод UploadContactFile

Примените этот метод для загрузки файла с контактами для рассылки. Для этого выполните POST запрос с входными параметрами к точке подключения, указанными ниже.

Точка подключения:

POST: https://api.exolve.ru/campaign/v1/UploadContactFile

Авторизация

Передайте следующие Заголовки HTTP для успешной авторизации.

Имя Тип Описание
Authorization string API-ключ приложения с Bearer перед ним. Пример: Bearer e***s0, где e***s0 замените на API-ключ вашего приложения

Входные параметры

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

Параметр Тип Описание
campaign_id uint64 идентификатор рассылки
file File файл с контактами

File

Параметр Тип Описание
name string название файла
mime_type string тип объекта для браузера (text/csv, text/x-csv, text/plain, application/csv, application/x-csv)
content bytes список контактов в формате base64

Выходные параметры

Параметр Тип Описание
file_id uint64 идентификатор загруженного файла

Возможные ошибки

Код Статус Пример сообщения Описание
404 Not Found Not Found некорректный URL запроса
401 Unauthorized invalid token невалидный API-ключ
400 Bad Request token is empty в запросе не передан API-ключ
400 Bad Request couldn’t parse incoming jwt token: couldn’t parse token: invalid character ‘[character]’ looking for beginning of value невалидный API-ключ
400 Bad Request couldn’t upload contact file: format file not csv формат загружаемого файла не является .csv
400 Bad Request couldn’t upload info contact file: empty campaign id отсутствует поле campaign_id
400 Bad Request couldn’t upload info contact file: empty file content отсутствует поле content
400 Bad Request invalid character ‘[character]’ looking for beginning of value невалидное значение в одном из полей
400 Bad Request invalid value for uint64 type: ‘[value]’ невалидное или пустое значение в поле id с типом uint64
400 Bad Request invalid character " after object key:value pair в запросе пропущена запятая в одном из параметров

Примеры

Входные параметры:

{
    "campaign_id": "12345",
    "file": {
        "content": "bnVtYmVyO3RpbWUgem9uZQ0KNzk5OTExMTIyMzM7VVRDKzINCjc5OTk0NDQ1NTY2O1VUQys1",
        "mime_type": "text/csv",
        "name": "contacts.csv"
    }
}

Выходные параметры:

{
    "file_id": "119362165802627072"
}

Метод GetFileInfo

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

Точка подключения:

POST: https://api.exolve.ru/campaign/v1/GetFileInfo

Авторизация

Передайте следующие Заголовки HTTP для успешной авторизации.

Имя Тип Описание
Authorization string API-ключ приложения с Bearer перед ним. Пример: Bearer e***s0, где e***s0 замените на API-ключ вашего приложения

Входные параметры

Передайте следующие параметры в теле запроса в JSON-формате. Параметры, отмеченные жирным шрифтом, являются обязательными.

Параметр Тип Описание
campaign_id uint64 идентификатор рассылки
file_id uint64 идентификатор загруженного файла

Выходные параметры

Параметр Тип Описание
id uint64 идентификатор загруженного файла
name string наименование загруженного файла
status enum FileStatus статус загрузки файла
amount_contacts uint64 количество загруженных контактов (значение передаётся только в статусе FILE_STATUS_VERIFIED)

FileStatus

Параметр Тип Описание
1 enum идёт загрузка файла
2 enum файл загружен
3 enum файл в стадии валидации
4 enum ошибка валидации (ошибки в полях number/timezone, доступно скачивание файла с ошибками)
5 enum ошибка загрузки файла (неверный формат файла, некорректные заголовки)
6 enum файл загружен, валидация завершена
7 enum файл удалён

Возможные ошибки

Код Статус Пример сообщения Описание
404 Not Found Not Found некорректный URL-адрес запроса
401 Unauthorized invalid token невалидный API-ключ
400 Bad Request token is empty в запросе не передан API-ключ
400 Bad Request couldn’t parse incoming jwt token: couldn’t parse token: invalid character ‘[character]’ looking for beginning of value невалидный API-ключ
400 Bad Request invalid GetFileInfoRequest.CampaignId: value must be greater than 0 поле campaign_id и его значение отсутствуют в запросе
400 Bad Request invalid GetFileInfoRequest.FileId: value must be greater than 0 поле file_id и его значение отсутствуют в запросе
400 Bad Request invalid character ‘[character]’ looking for beginning of value невалидное или пустое значение в одном из полей
400 Bad Request invalid value for uint64 type: ‘[value]’ невалидное или пустое значение в одном из полей с типом uint64
400 Bad Request invalid character " after object key:value pair в запросе пропущена запятая в одном из параметров

Примеры

Входные параметры:

{
    "campaign_id": 129931120807677952,
    "file_id": 130798251019812864
}

Выходные параметры:

{
    "id": "130798251019812864",
    "name": "contacts.csv",
    "status": "3",
    "amount_contacts": "2"
}

Метод DownloadFileError

Примените этот метод для скачивания файла с ошибками валидации. Для этого выполните POST запрос с входными параметрами к точке подключения, указанными ниже.

Точка подключения:

POST: https://api.exolve.ru/campaign/v1/DownloadFileError

Авторизация

Передайте следующие Заголовки HTTP для успешной авторизации.

Имя Тип Описание
Authorization string API-ключ приложения с Bearer перед ним. Пример: Bearer e***s0, где e***s0 замените на API-ключ вашего приложения

Входные параметры

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

Параметр Тип Описание
campaign_id uint64 идентификатор рассылки
file_id uint64 идентификатор загруженного файла

Выходные параметры

Параметр Тип Описание
file File файл с результатами валидации

File

Параметр Тип Описание
name string название файла
mime_type string тип объекта для браузера
content bytes список контактов и ошибок валидации в формате base64

Возможные ошибки

Код Статус Пример сообщения Описание
404 Not Found Not Found некорректный URL запроса
401 Unauthorized invalid token невалидный API-ключ
400 Bad Request token is empty в запросе не передан API-ключ
400 Bad Request couldn’t parse incoming jwt token: couldn’t parse token: invalid character ‘[character]’ looking for beginning of value невалидный API-ключ
404 Not Found file not found файл с указанным ID в поле file_id не найден
403 Forbidden permission denied данные введены в неверном формате
400 Bad Request invalid DownloadFileErrorRequest.CampaignId: value must be greater than 0 поле campaign_id и его значение отсутствуют в запросе
400 Bad Request invalid DownloadFileErrorRequest.FileId: value must be greater than 0 поле file_id и его значение отсутствуют в запросе
400 Bad Request invalid character ‘[character]’ looking for beginning of value невалидное или пустое значение в одном из полей
400 Bad Request invalid value for uint64 type: ‘[value]’ невалидное или пустое значение в одном из полей с типом uint64
400 Bad Request invalid character " after object key:value pair в запросе пропущена запятая в одном из параметров

Примеры

Входные параметры:

{
    "campaign_id": "12345",
    "file_id": "119362165802627072"
}

Выходные параметры:

{
    "file": {
        "name": "report_contacts.csv",
        "mime_type": "text/csv",
        "content": "bnVtYmVyO3RpbWUgem9uZTtlcnJvciAobnVtYmVyKQo3OTEzMTIwMjEyMjs7Cjc5MTMxMjAyMTIyO1VUQysyO2R1cGxpY2F0ZQo3OTA1MTIzNDU2NztVVEMrNTsK"
    }
}

Метод DeleteFile

Примените этот метод для удаления файла со списком контактов. Для этого выполните POST запрос с входными параметрами к точке подключения, указанными ниже.

Точка подключения:

POST: https://api.exolve.ru/campaign/v1/DeleteFile

Авторизация

Передайте следующие Заголовки HTTP для успешной авторизации.

Имя Тип Описание
Authorization string API-ключ приложения с Bearer перед ним. Пример: Bearer e***s0, где e***s0 замените на API-ключ вашего приложения

Входные параметры

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

Параметр Тип Описание
campaign_id uint64 идентификатор рассылки
file_id uint64 идентификатор загруженного файла

Выходные параметры

Пустой JSON с 200 OK статусом.

Возможные ошибки

Код Статус Пример сообщения Описание
404 Not Found Not Found некорректный URL запроса
401 Unauthorized invalid token невалидный API-ключ
400 Bad Request token is empty в запросе не передан API-ключ
400 Bad Request couldn’t parse incoming jwt token: couldn’t parse token: invalid character ‘[character]’ looking for beginning of value невалидный API-ключ
403 Forbidden permission denied данные введены в неверном формате
400 Bad Request couldn’t delete contact file: the file does not belong to the campaign файл со списком контактов не принадлежит рассылки
400 Bad Request invalid DeleteFileRequest.CampaignId: value must be greater than 0 поле campaign_id и его значение отсутствуют в запросе
400 Bad Request invalid DeleteFileRequest.FileId: value must be greater than 0 поле file_id и его значение отсутствуют в запросе
400 Bad Request invalid character ‘[character]’ looking for beginning of value невалидное или пустое значение в одном из полей
400 Bad Request invalid value for uint64 type: ‘[value]’ невалидное или пустое значение в одном из полей с типом uint64
400 Bad Request invalid character " after object key:value pair в запросе пропущена запятая в одном из параметров

Примеры

Входные параметры:

{
    "campaign_id": "12345",
    "file_id": "119362165802627072"
}

Выходные параметры:

{}

Метод CreateCallListFromFile

Примените этот метод для создания списка контактов из провалидированного файла. Для этого выполните POST-запрос с входными параметрами к точке подключения, указанными ниже.

Точка подключения:

POST: https://api.exolve.ru/campaign/v1/CreateCallListFromFile

Авторизация

Передайте следующие Заголовки HTTP для успешной авторизации.

Имя Тип Описание
Authorization string API-ключ приложения с Bearer перед ним. Пример: Bearer e***s0, где e***s0 замените на API-ключ вашего приложения

Входные параметры

Передайте следующие параметры в теле запроса в JSON-формате. Параметры, отмеченные жирным шрифтом, являются обязательными.

Параметр Тип Описание
campaign_id uint64 идентификатор рассылки
file_id uint64 идентификатор загруженного файла

Выходные параметры

Параметр Тип Описание
call_list_id uint64 идентификатор списка контактов

Возможные ошибки

Код Статус Пример сообщения Описание
404 Not Found Not Found некорректный URL-адрес запроса
401 Unauthorized invalid token невалидный API-ключ
400 Bad Request token is empty в запросе не передан API-ключ
400 Bad Request couldn’t parse incoming jwt token: couldn’t parse token: invalid character ‘[character]’ looking for beginning of value невалидный API-ключ
404 Not Found file not found файл с указанным ID в поле file_id не найден
400 Bad Request invalid CreateCallListFromFileRequest.CampaignId: value must be greater than 0 поле campaign_id и его значение отсутствуют в запросе
400 Bad Request invalid CreateCallListFromFileRequest.FileId: value must be greater than 0 поле file_id и его значение отсутствуют в запросе
400 Bad Request invalid character ‘[character]’ looking for beginning of value невалидное или пустое значение в одном из полей
400 Bad Request invalid value for uint64 type: ‘[value]’ невалидное или пустое значение в одном из полей с типом uint64
400 Bad Request invalid character " after object key:value pair в запросе пропущена запятая в одном из параметров

Примеры

Входные параметры:

{
    "campaign_id": 128462752095809536,
    "file_id": 128466384803266560
}

Выходные параметры:

{
    "call_list_id": "128462752087420928"
}

Метод GetCallList

Примените этот метод для получения информации о списке контактов. Для этого выполните POST-запрос с входными параметрами к точке подключения, указанными ниже.

Точка подключения:

POST: https://api.exolve.ru/campaign/v1/GetCallList

Авторизация

Передайте следующие Заголовки HTTP для успешной авторизации.

Имя Тип Описание
Authorization string API-ключ приложения с Bearer перед ним. Пример: Bearer e***s0, где e***s0 замените на API-ключ вашего приложения

Входные параметры

Передайте следующие параметры в теле запроса в JSON-формате. Параметры, отмеченные жирным шрифтом, являются обязательными.

Параметр Тип Описание
campaign_id uint64 идентификатор рассылки
call_list_id uint64 идентификатор списка получателей
limit uint32 лимит выводимых данных (3000 по умолчанию)
offset uint32 номер строки, с которой начинается выборка (начинается с 0)

Выходные параметры

Параметр Тип Описание
campaign_id uint64 идентификатор рассылки
campaign_id string наименование рассылки
call_list_id uint64 идентификатор списка получателей
call_list_total uint64 количество записей в списке получателей
file_name string имя файла со списком контактов
file_upload_at string дата загрузки файла в формате RFC-3339 / ISO-8601
call_list_items CallListItem информация о получателях

CallListItem

Параметр Тип Описание
to string номер получателя
timezone uint32 часовой пояс получателя
status enum CallListStatus статус списка контактов
created_at string дата создания списка контактов
updated_at string дата обновления списка контактов

CallListStatus

Параметр Тип Описание
1 enum черновик
2 enum в процессе выполнения
3 enum остановлена пользователем
4 enum в очереди
5 enum начата
6 enum закончена
7 enum неуспешна
8 enum недостаточно средств для выполнения коммуникации
9 enum ошибка отправки на сервисе
10 enum отменена пользователем

Возможные ошибки

Код Статус Пример сообщения Описание
404 Not Found Not Found некорректный URL-адрес запроса
401 Unauthorized invalid token невалидный API-ключ
400 Bad Request token is empty в запросе не передан API-ключ
400 Bad Request couldn’t parse incoming jwt token: couldn’t parse token: invalid character ‘[character]’ looking for beginning of value невалидный API-ключ
404 Not Found couldn’t get campaign by id = [campaign_id], app = ‘[app_id]’ : campaign not found рассылка по заданным параметрам не найдена
400 Bad Request invalid GetCallListRequest.CampaignId: value must be greater than 0 поле campaign_id и его значение отсутствуют в запросе
400 Bad Request invalid GetCallListRequest.CallListId: value must be greater than 0 поле call_list_id и его значение отсутствуют в запросе
400 Bad Request invalid character ‘[character]’ looking for beginning of value невалидное или пустое значение в одном из полей
400 Bad Request invalid value for uint64 type: ‘[value]’ невалидное или пустое значение в одном из полей с типом uint64
400 Bad Request invalid character " after object key:value pair в запросе пропущена запятая в одном из параметров

Примеры

Входные параметры:

{
    "campaign_id": 128484451264724992,
    "call_list_id": 130334219041517568,
    "limit":10
}

Выходные параметры:

{
    "campaign_id": "130334219200901120",
    "campaign_name": "test",
    "call_list_id": "130334219041517568",
    "call_list_total": "2",
    "file_name": "contacts.csv",
    "file_upload_at": "2023-12-28T11:25:38.428Z",
    "call_list_items": [
        {
            "to": "79991112233",
            "timezone": 2,
            "status": "1",
            "created_at": "2023-12-28T11:25:49.428275Z",
            "updated_at": "1970-01-01T00:00:00Z"
        },
        {
            "to": "79994445566",
            "timezone": 5,
            "status": "1",
            "created_at": "2023-12-28T11:25:49.428337Z",
            "updated_at": "1970-01-01T00:00:00Z"
        }
    ],
    "limit": 10
}

Содержание статьи