Разработчикам
Для использования API вы должны знать свой API KEY, который можно посмотреть в своем профиле.
Система проста — вы посылаете POST запрос с нужной информацией в формате JSON на специальный адрес. Все данные отправляются и возвращаются в кодировке UTF-8.
Адрес: http://api.client24.ru/METHOD_NAME?api_key=API_KEY
Пример: http://api.client24.ru/send_sms?api_key=T9q9j1FRd6Qn9DhkIDdBvotg
Вы можете воспользоваться нашим классом для отправки запросов, если используете PHP.
Для работы с API есть 7 методов:
send_sms — отправка SMS сообщений
status_sms — получение статуса SMS сообщений
send_email — отправки e-mail сообщений
status_email — получение статуса e-mail сообщений
create_delivery — создание новой рассылки по базе клиентов
send_delivery — запуск уже созданной рассылки
status_delivery — получение статистики рассылки
Метод send_sms ↑
Формат запроса
{
"info":{
"from":"MegaShop",
"tag":"user-register",
"shortlink":1
}
"data":[
{
"to":"79161234567",
"text":"Спасибо за регистрацию в MegaShop! Наши контакты: тел. (495) 123 45 67, megashop.ru",
"otherid":"reg8255"
},
{
"to":"+7 (916) 123-45-68",
"text":"Спасибо за регистрацию в MegaShop! Наши контакты: тел. (495) 123 45 67, megashop.ru",
"otherid":"reg8256"
}
]
}
Параметры:
info — необязательный блок параметров- from_name — имя отправителя, которое будет видно получателю (от 3 до 11 латинских символов или цифр), имя должно быть подтверждено в личном кабинете (необязательный параметр, если значение не указано, будет выбрано имя по умолчанию из профиля)
- from — имя отправителя, добавлено для поддержки старой версии API (параметр имеет меньший приоритет, чем from_name)
- tag — название тэга для группировки сообщений в одну рассылку, допускается также передача числового ID тэга (необязательный параметр, если значение не указано - все сообщения попадут в общую рассылку)
- shortlink — флаг, указывающий нужно ли сокращать ссылки для уменьшения текста SMS сообщения (необязательный параметр, если значение не указано - будет использоваться флаг из настроек профиля)
- to — номер телефона получателя, допускается передача в любом формате (при проверке будут исключены все символы, кроме цифр)
- text — текст SMS сообщения
- otherid — внешний идентификатор сообщения (необязательный параметр)
- shortlink — заменяет для данного сообщения значение параметра shortlink, указанного в блоке info либо в настройках профиля
Параметр shortlink служит для сокращения ссылок в вид cl24.ru/A1b2C3d4. При отключении сокращения ссылок статистика по переходам в SMS-сообщениях собираться не будет!
Формат ответа
{
"info":{
"from_name":"MegaShop",
"delivery_id":7681
},
"data":[
{
"to":"79161234567",
"id":2000071837054,
"otherid":"reg8255"
},
{
"to":"+7 (916) 123-45-68",
"id":2000071837212,
"otherid":"reg8256"
}
],
"status":"ok"
}
Результат запроса:
info — информационный блок- from_name — фактический адрес отправителя, который был использован
- delivery_id — идентификатор рассылки, в которую были помещены отправляемые сообщения
- to — номер телефона получателя в исходном формате
- id — идентификатор сообщения, назначенный в рамках Client24
- otherid — внешний идентификатор сообщения, если он был передан
error — текст ошибки (возвращается, если status принимает значение error, при этом список data будет пуст)
Внимание! Ранее вместо id использовался ключ sid!
В последствии, используя id или otherid (если идентификатор был указан при отправке), получить статус отправки сообщений. Получение статусов доступно для сообщений, отправленных в текущем и предыдущем календарном месяцах.
Внимание! Параметр otherid должен быть уникальным для каждого отправляемого сообщения и не может быть длиннее 50 символов. При запросе статуса по otherid будут возвращены все сообщения с otherid равным переданному значению без учета регистра. Используя этот параметр можно полностью синхронизировать работу вашей базы с Client24.
Метод status_sms ↑
Формат запроса
[
{
"id":2000071837054
},
{
"otherid":"reg8256"
}
]
Параметры:
список — каждый из элементов должен содержать только один из параметров:- id — идентификатор сообщения, назначенный в рамках Client24
- otherid — внешний идентификатор сообщения, если он был передан
В данном примере будет получен статус по otherid и по id одновременно. Возможны любые комбинации. При наличии обоих параметров будет использован id.
Формат ответа
{
"data":[
{
"id":"2000071837054",
"otherid":"reg8255",
"phone":"79161234567",
"delivered":"2013-01-01 12:00:00",
"status":1
},
{
"otherid":"reg8256",
"phone":"79161234568",
"delivered":"2013-01-01 12:00:00",
"clicked":"2013-01-01 12:01:00",
"status":4
}
],
"status":"ok"
}
Результат запроса:
список — каждый из элементов содержит статус отправки одного сообщения, состоящий из:- id — идентификатор сообщения, назначенный в рамках Client24 (если статус запрошен по id)
- otherid — внешний идентификатор сообщения (если был передан при отправке)
- phone — отформатированный номер телефона получателя
- delivered — дата и время доставки SMS (по данным от мобильного оператора)
- clicked — дата и время первого перехода по ссылке из SMS
- unsubscribed — дата и время первого перехода по ссылке отписки (если была добавлена в личном кабинете)
- status — код статуса сообщения (расшифровка представлена ниже)
error — текст ошибки (возвращается, если status принимает значение error, при этом список data будет пуст)
Расшифровка кодов статусов
0 — отправлено
1 — доставлено
2 — не доставлено
3 — ошибка
4 — кликнуто
5 — не отправлено
Метод send_email ↑
Формат запроса
{
"info":{
"from":"info@megashop.com",
"from_name":"MegaShop",
"tag":"email-reg",
},
"data":[
{
"to":"ivan.ivanov@mail.ru",
"to_name":"Иван Иванов",
"subject":"Регистрация на MegaShop успешно завершена!",
"text":"Иван, поздравляем!\\r\\nВаша регистрация на MegaShop успешно завершена!",
"otherid":"reg8255"
},
{
"to":"ivan.petrov@mail.ru",
"to_name":"Иван Петров",
"subject":"Регистрация на MegaShop успешно завершена!",
"text":"<h1>Иван, поздравляем!</h1><p>Ваша регистрация на MegaShop успешно завершена!</p><a href='http://megashop.com'>MegaShop</a>",
"otherid":"reg8256"
},
]
}
info — необязательный блок параметров- from_name — имя отправителя, которое будет видно получателю; имя должно быть подтверждено в личном кабинете (необязательный параметр, если значение не указано, будет выбрано имя по умолчанию из профиля)
- from — имя отправителя, добавлено для поддержки старой версии API (параметр имеет меньший приоритет, чем from_name)
- tag — название тэга для группировки сообщений в одну рассылку, допускается также передача числового ID тэга (необязательный параметр, если значение не указано - все сообщения попадут в общую рассылку)
- to — email-адрес получателя
- to_name — имя получателя (необязательный параметр)
- subject — тема сообщения
- text — текст сообщения
- otherid — внешний идентификатор сообщения (необязательный параметр)
Текст сообщений может передаваться как обычным текстом, так и в виде HTML. Во втором случае все ссылки, «обернутые» в тэг <a>, будут автоматически отслеживаться и учитываться в статистике.
Формат ответа
{
"info":{
"from":"info@megashop.com",
"from_name":"MegaShop",
"delivery_id":7684
},
"data":[
{
"to":"ivav.ivanov@mail.ru",
"id":2000071398521,
"otherid":"regsms8255"
},
{
"to":"ivav.petrov@mail.ru",
"id":2000071398672,
"otherid":"regsms8256"
}
],
"status":"ok"
}
Результат запроса:
info — информационный блок- from — фактическое имя отправителя, которое было использовано
- from_name — фактический адрес отправителя, который был использован
- delivery_id — идентификатор рассылки, в которую были помещены отправляемые сообщения
- to — email-адрес получателя в исходном формате
- id — идентификатор сообщения, назначенный в рамках Client24
- otherid — внешний идентификатор сообщения, если он был передан
error — текст ошибки (возвращается, если status принимает значение error, при этом список data будет пуст)
Метод status_email ↑
[
{
"id":2000071398521
},
{
"otherid":"regsms8256"
}
]
Параметры:
список — каждый из элементов должен содержать только один из параметров:- id — идентификатор сообщения, назначенный в рамках Client24
- otherid — внешний идентификатор сообщения, если он был передан
В данном примере будет получен статус по otherid и по id одновременно. Возможны любые комбинации. При наличии обоих параметров будет использован id.
Формат ответа
{
"data":[
{
"id":"2000071398521",
"otherid":"regsms8255",
"email":"ivav.ivanov@mail.ru",
"opened":"2013-01-01 12:00:00",
"status":1
},
{
"otherid":"regsms8256",
"email":"ivav.petrov@mail.ru",
"opened":"2013-01-01 12:00:00",
"clicked":"2013-01-01 12:01:00",
"status":2
}
],
"status":"ok"
}
Результат запроса:
список — каждый из элементов содержит статус отправки одного сообщения, состоящий из:- id — идентификатор сообщения, назначенный в рамках Client24 (если статус запрошен по id)
- otherid — внешний идентификатор сообщения (если был передан при отправке)
- email — email-адрес получателя
- opened — дата и время первого открытия сообщения (загрузка пикселя прочтения)
- clicked — дата и время первого перехода по одной из ссылок в письме
- unsubscribed — дата и время первого перехода по ссылке отписки
- status — код статуса сообщения (расшифровка представлена ниже)
error — текст ошибки (возвращается, если status принимает значение error, при этом список data будет пуст)
Расшифровка кодов статусов
E-mail
0 — отправлено
1 — прочитано
2 — кликнуто
3 — не доставлено
4 — получатель отписался
Метод create_delivery ↑
Метод для создания (подготовки) новой рассылки для последующей отправки. В ответе на этот запрос возвращается количество клиентов, email-адресов и телефонов, которые попадают под эту рассылку.
Формат запроса
{
"type":"email",
"params":{
"name":"Поздравление с Новым Годом",
"subject":"MegaShop поздравляет Вас с Новым Годом!",
"text":"<h1>[Имя]!</h1><p>MegaShop поздравляет Вас с Новым Годом!</p>",
"filter":{
"tagIds":[627,783,1873],
"fields":{
"first_name":{
"operator":"=",
"value":"Иван"
},
"email:{
"operator":"contains",
"value":"@mail.ru"
}
}
}
"sender_email_id":412,
"sender_name_id":425,
"template_id":1031,
"send_time":"2014-01-01 00-00-00"
}
}
Формат запроса
type — тип рассылки («sms» или «email») params — список параметров рассылки- name — название рассылки, которое будет отображаться в личном кабинете
- subject — тема письма (обязательно только для email-рассылок)
- text — текст сообщения
- sender_email_id — идентификатор email-адреса отправителя, подтвержденный в личном кабинете (только для email-рассылок)
- sender_name_id — идентификатор имени отправителя (для SMS или email соответственно), подтвержденный в личном кабинете
- template_id — идентификатор текста шаблона сообщения (необязательный параметр)
- send_time — запланированное время отправки рассылки (необязательный параметр)
- filter — параметры фильтрации клиентов:
- tagIds — список идентификаторов тэгов
- fields — условия фильтрации по значениям полей (для каждого поля отдельный блок):
- ключ — название поля (варианты: email, phone, last_name, first_name и т.д.)
- value — значение поля, используемое в условии
- operator — условие фильтрации (оператор сравнения) по значениям полей (необязательное поле, возможные варианты: "=", "<", ">", "<=", ">=", "!=", "starts", "contains", "ends")
Некоторые операторы недоступны для отдельных полей с определенными типами данных.
Формат ответа
{
"delivery":{
"delivery_id":1089,
"clients":231000,
"emails":233500,
"phones":235000
},
"status":"ok"
}
Формат ответа
delivery — информация о созданной рассылке- delivery_id — идентификатор рассылки
- clients — количество клиентов, соответствующих фильтру рассылки
- emails — количество email-сообщений у клиентов
- phones — количество номеров у клиентов
Метод send_delivery ↑
Метод отправки уже созданной (через API-запрос или личный кабинет) рассылки.
Формат запроса
{
"delivery_id":1089,
}
Формат запроса
delivery_id — идентификатор рассылкиФормат ответа
{
"data":{
"delivery_id":1089,
"status":"Processing",
},
"status":"ok"
}
Формат ответа
data — информация о запущенной рассылке- delivery_id — идентификатор рассылки
- status — новый статус рассылки
Метод status_delivery ↑
Получение статистики по отправленной или отправляемой в данный момент рассылке.
Формат запроса
{
"delivery_id":1089,
}
Формат запроса
delivery_id — идентификатор рассылкиФормат ответа
{
"stats":{
"full":{
"emails":233500,
"clients":231000,
"sent":233500,
"undelivered":500,
"opened":50000,
"clicked":25000,
"unsubscribed":1500
}
"clicks":{
"click_1":15500,
"click_2":5000,
"click_3":3500,
"click_5":2500
}
"detail":{
"opened":{
"2014-01-01":40000,
"2014-01-02":8000,
"2014-01-03":7000
},
"clicked":{
"2014-01-01":20000,
"2014-01-02":4000,
"2014-01-03":3000
},
"unsubscribed":{
"2014-01-01":1000,
"2014-01-02":300,
"2014-01-03":200
}
}
"status":"ok"
}
Формат ответа
stats — блок статистики запрошенной рассылки- full — количественные счетчики с информацией об объеме рассылки и статусах доставки сообщений
- clicks — счетчики количества переходов по каждой отдельной ссылке в письме
- detail — детализация по количеству открытий писем, писем с переходами по ссылкам и отписанных клиентов в разрезе по дням
Примеры использования нашего PHP класса
Отсылка двух e-mail сообщений на адрес address@gmail.com
$api = new client24api("880470ashINioo9sah92183");
$api->send_email(
array(
"info" => array(
"from" => "company2288@gmail.com",
"from_name" => "Company"
),
"data" => array(
array(
"to" => "address@gmail.com",
"subject" => "hello this is theme!",
"text" => "hello this is text!"
),
array(
"to" => "address@gmail.com",
"subject" => "hello this is theme!2",
"text" => "hello this is text!2"
),
)
)
);
Получение статусов смс сообщений
$api = new client24api("880470ashINioo9sah92183");
$api->status_sms(
array(
array(
"id" => 876
),
array(
"id" => 222
)
)
);