Вход для клиентов: Логин Пароль Забыли пароль? Зарегистрироваться
Стоимость SMS
0,10 рубРоссия
0,48 рубУкраина
0,78 рубКазахстан
0,95 рубСША
1,55 рубВеликобритания
Подробнее о тарифах и скидках на СМС рассылки
Мы не практикуем спам сообщения!


Здесь находится аттестат нашего WM идентификатора 171491728649

Версия для печати

Описание HTTP/HTTPS API

Далее описывается интерфейс взаимодействия (API) с сервером BYTEHAND для интеграции функций рассылки SMS-сообщений в свои проекты и сервисы.

Взаимодействие происходит по протоколам HTTP (порт 3800) или HTTPS (порт 8443).

Авторизация

Отправка сообщения

Отправка нескольких сообщений

Проверка статуса сообщения

Детальная информация о сообщении

Проверка состояния баланса

Подписи отправителя

Детальная информация о подписи

Отправка подписи на модерацию

Удаление подписи

Передача статусов сообщений на обработчик клиента

Получение входящих сообщений

Открытие USSD сессии

Получить информацию о USSD сессии

Получить информацию о USSD запросе

Обработчик статусов для USSD сессий

Обработчик запросов для USSD сессий

Коды ошибок


Авторизация

Для выполнения всех запросов API требуется авторизация клиента, для этого в запросе передаются два параметра id=<ID> и key=<KEY>.

Параметр Описание
id Идентификатор клиента.
key Ключ клиента.

Значения этих параметров можно получить в пользовательском Web интерфейсе на странице Аккаунт → Настройки.

Аккаунт → Настройки
Сохраняйте значение ключа в тайне и не передавайте его другим лицам. Используйте ссылку Пересоздать ключ если ключ был скомпрометирован и вам требуется изменить его значение.

Отправка сообщения

Для отправки SMS сообщения необходимо вызвать методом GET адрес:

http://bytehand.com:3800/send?id=<ID>&key=<KEY>&to=<PHONE>&from=<SIGNATURE>&text=<TEXT>

Описание параметров:

Параметр Описание
to Один номер мобильного телефона в международном формате, на который отправляется сообщение.
Номера могут передаваться без знака "+". Если номер передан без знака "+", то он может быть исправлен автоматическим форматированием и приведен к правильному международному формату. Таким образом, некоторые ошибки при вводе номеров телефонов могут быть исправлены автоматически. Для отключения автоисправления передайте номер со знаком "+". Пример, номер телефона "8 (495) 123-45-67" будет исправлен как "+74951234567". Обязательный параметр.
from Имя отправителя, отображаемое в телефоне получателя. Необходимо предварительно зарегистрировать имя отправителя в пользовательском Web интерфейсе. Динамическое имя отправителя включается по специальному запросу. Обязательный параметр.
text Текст отправляемого сообщения. Максимальный размер – 800 символов. Сообщение при необходимости будет разбито на несколько SMS, отправленных абоненту и оплаченных по отдельности. Размер одного SMS – 160 символов в латинице или 70 символов в кириллице. При разбивке сообщения на несколько SMS в каждую часть добавляется заголовок для объединения частей в одно сообщение на телефоне получателя, и максимальная длина становится 67 для кириллицы и 153 для латинских букв. Для переноса текста сообщения на новую строку используйте код %0D
Обязательный параметр.
send_after Дата и время когда требуется отправить сообщение. Часовой пояс GMT+0, формат yyyy-MM-dd HH:mm:ss. Необязательный параметр, если отсутствует, сообщение отправляется немедленно.

Все параметры, которые содержат специальные символы (плюс, пробел и т.д.), должны быть закодированы при помощи функции urlencode для передачи в HTTP-запросе.

После обработки данных сервер возвращает клиенту результат в формате JSON.

Пример

http://bytehand.com:3800/send?id=1234&key=5D01022D23AD33FE&to=79161234567&from=test&text=Hello%20world!

Ответ, сообщение отправлено успешно:

{"status": "0", "description": "9885176022016555"}

Описание параметров ответа:

Параметр Описание
status 0
description Идентификатор сообщения.


Отправка нескольких сообщений

Для отправки нескольких SMS сообщений необходимо вызвать методом POST адрес:

http://bytehand.com:3800/send_multi?id=<ID>&key=<KEY>

Описание параметров запроса:

Параметр Описание
send_after Дата и время когда требуется отправить сообщение. Часовой пояс GMT+0, формат yyyy-MM-dd HH:mm:ss. Необязательный параметр, если отсутствует, сообщение отправляется немедленно.

Все параметры, которые содержат специальные символы (плюс, пробел и т.д.), должны быть закодированы при помощи функции urlencode для передачи в HTTP-запросе.

Тело запроса содержит список из запросов на отправку SMS сообщений в формате JSON, каждый запрос содержит номер получателя, имя отправителя и текст сообщения; кодировка UTF-8.

Значение параметра Content-Type должно быть установлено в значение application/json;charset=UTF-8.

Описание параметров для передачи в теле запроса:

Параметр Описание
to Один номер мобильного телефона в международном формате, на который отправляется сообщение.
Номера могут передаваться без знака "+". Если номер передан без знака "+", то он может быть исправлен автоматическим форматированием и приведен к правильному международному формату. Таким образом, некоторые ошибки при вводе номеров телефонов могут быть исправлены автоматически. Для отключения автоисправления передайте номер со знаком "+". Пример, номер телефона "8 (495) 123-45-67" будет исправлен как "+74951234567". Обязательный параметр.
from Имя отправителя, отображаемое в телефоне получателя. Необходимо предварительно зарегистрировать имя отправителя в пользовательском Web интерфейсе. Динамическое имя отправителя включается по специальному запросу. Обязательный параметр.
text Текст отправляемого сообщения. Максимальный размер – 800 символов. Сообщение при необходимости будет разбито на несколько SMS, отправленных абоненту и оплаченных по отдельности. Размер одного SMS – 160 символов в латинице или 70 символов в кириллице. При разбивке сообщения на несколько SMS в каждую часть добавляется заголовок для объединения частей в одно сообщение на телефоне получателя, и максимальная длина становится 67 для кириллицы и 153 для латинских букв. Для переноса текста сообщения на новую строку используйте код %0D
Обязательный параметр.

После обработки данных сервер возвращает клиенту результат в формате JSON.

Пример

http://bytehand.com:3800/send_multi?id=1234&key=5D01022D23AD33FE

Тело запроса:

[{"to":"89161234567", "from":"test", "text":"Hello world!"}, {"to":"+79167654321", "from":"blablabla", "text":"TEST"}]

Ответ:

[{"status":0,"description":"33438930809215150"}, {"status":10,"description":"Invalid message sender."}]

Описание параметров ответа:

Параметр Описание
status 0
description Идентификатор сообщения.

Порядок элементов в ответе соответствует порядку элементов в запросе.



Проверка статуса сообщения

Для проверки статуса доставки SMS необходимо вызвать методом GET адрес:

http://bytehand.com:3800/status?id=<ID>&key=<KEY>&message=<MESSAGE_ID>

Описание параметров:

Параметр Описание
message Идентификатор сообщения.

Все параметры являются обязательными.

После обработки данных сервер возвращает клиенту результат в формате JSON.

Пример

http://bytehand.com:3800/status?id=1234&key=5D01022D23AD33FE&message=9885176022016555

Ответ, статус получен успешно:

{"status": "0", "description": "DELIVERED"}

Описание параметров ответа:

Параметр Описание
status 0
description Статус сообщения, возможные значения: "NEW", "DELIVERED", "EXPIRED", "DELETED", "UNDELIVERABLE", "ACCEPTED", "UNKNOWN", "REJECTED".


Детальная информация о сообщении

Для получения детальной информации о SMS необходимо вызвать методом GET адрес:

http://bytehand.com:3800/details?id=<ID>&key=<KEY>&message=<MESSAGE_ID>

Описание параметров:

Параметр Описание
message Идентификатор сообщения.

Все параметры являются обязательными.

После обработки данных сервер возвращает клиенту результат в формате JSON.

Пример

http://bytehand.com:3800/details?id=1234&key=5D01022D23AD33FE&message=9885176022016555

Ответ, информация получена успешно:

{"status": "0", "description": "DELIVERED", "posted_at": "2012-09-11 20:00:26.0", "updated_at": "2012-09-11 20:00:38.0", "parts": "5", "cost": "1.0000"}

Описание параметров ответа:

Параметр Описание
status 0
description Статус сообщения, возможные значения: "NEW", "DELIVERED", "EXPIRED", "DELETED", "UNDELIVERABLE", "ACCEPTED", "UNKNOWN", "REJECTED".
posted_at Дата и время отправки SMS сообщения, часовой пояс GMT+0, формат yyyy-MM-dd HH:mm:ss.
updated_at Дата и время последнего изменения статуса SMS сообщения, часовой пояс GMT+0, формат yyyy-MM-dd HH:mm:ss.
parts Количество частей в сообщении.
cost Стоимость сообщения в рублях.


Проверка состояния баланса

Для запроса баланса необходимо вызвать методом GET адрес:

http://bytehand.com:3800/balance?id=<ID>&key=<KEY>

Все параметры являются обязательными.

После обработки данных сервер возвращает клиенту результат в формате JSON.

Пример

http://bytehand.com:3800/balance?id=1234&key=5D01022D23AD33FE

Ответ, баланс получен успешно:

{"status": "0", "description": "48.8300"}

Описание параметров ответа:

Параметр Описание
status 0
description Текущее состояние баланса в рублях.


Подписи отправителя

Для получения списка всех подписей во всех статусах необходимо вызвать методом GET адрес:

http://bytehand.com:3800/signatures?id=<ID>&key=<KEY>&state=[NEW|ACCEPTED|REJECTED]

Описание параметров:

Параметр Описание
state Статус подписи, возможные значения: "NEW","ACCEPTED","REJECTED". Необязательный параметр, если отсутствует, то ответ будет содержать подписи во всех статусах

После обработки данных сервер возвращает клиенту результат в формате JSON.

Пример

http://bytehand.com:3800/signatures?id=1234&key=5D01022D23AD33FE

Ответ:

[{"id":11,"text":"TEST","description":"Some text","created_at":"2012-04-26 01:50:29","state":"ACCEPTED"},{"id":49,"text":"BYTEHAND","description":"Подробное описание поможет нам понять, с какой целью вы хотите использовать эту подпись и разрешить её применение.","created_at":"2012-05-01 19:16:43","state":"ACCEPTED"}]

Описание параметров ответа:

Параметр Описание
id Идентификатор подписи.
text Текст подписи.
description Описание подписи.
created_at Дата и время создания подписи.
state Статус подписи, возможные значения: "NEW", "ACCEPTED", "REJECTED".


Детальная информация о подписи

Для получения детальной информации подписи необходимо вызвать методом GET адрес:

http://bytehand.com:3800/signature?id=<ID>&key=<KEY>&signature=SIGNATURE

Описание параметров ответа:

Параметр Описание
signature идентификатор подписи.

Пример

GET http://bytehand.com:3800/signature?id=1234&key=5D01022D23AD33FE&signature=11

Ответ:

{"id":49,"text":"BYTEHAND","description":"Подробное описание поможет нам понять, с какой целью вы хотите использовать эту подпись и разрешить её применение.","created_at":"2012-05-01 19:16:43","state":"ACCEPTED"}

Описание параметров ответа:

Параметр Описание
id Идентификатор подписи.
text Текст подписи.
description Описание подписи.
created_at Дата и время создания подписи.
state Статус подписи, возможные значения: "NEW", "ACCEPTED", "REJECTED".


Отправка подписи на модерацию

Для отправки подписи на модерацию необходимо вызвать методом POST адрес:

http://bytehand.com:3800/signature?id=<ID>&key=<KEY>&text=<TEXT>&description=<DESCRIPTION>

Описание параметров:

Параметр Описание
text Текст подписи.
description Описание подписи.

Пример

http://bytehand.com:3800/signature?id=1234&key=5D01022D23AD33FE&text=xyz&description=abc

Ответ:

{"status":0,"description":"11"}

Описание параметров ответа:

Параметр Описание
status 0
description Идентификатор подписи.


Удаление подписи

Для удаления подписи необходимо вызвать методом DELETE адрес:

http://bytehand.com:3800/signature?id=<ID>&key=<KEY>&signature=SIGNATURE

Пример:

http://bytehand.com:3800/signature?id=1234&key=5D01022D23AD33FE&signature=11


Передача статусов сообщений на обработчик клиента

В пользовательском Web интерфейсе на странице Аккаунт → Настройки имеется возможность указания HTTP-адреса (URL) скрипта для обработки статусов доставки SMS-сообщений на стороне клиента. Указанный скрипт будет вызываться сервисом BYTEHAND после каждого получения статуса доставки ранее отправленного клиентом SMS-сообщения.

Описание параметров которые передаются клиенту:

Параметр Описание
id Идентификатор клиента.
key Последние 8 символов ключа.
action Операция, для статуса сообщения это значение: "outgoingStatus".
message Идентификатор сообщения.
description Статус сообщения, возможные значения: "NEW", "DELIVERED", "EXPIRED", "DELETED", "UNDELIVERABLE", "ACCEPTED", "UNKNOWN", "REJECTED".
parts Количество частей в сообщении.
cost Стоимость сообщения в рублях.
error_code Код ошибки.
updated_at Дата и время последнего изменения статуса SMS сообщения, часовой пояс GMT+0, формат yyyy-MM-dd HH:mm:ss.

Все параметры являются обязательными.

Пример

В качестве URL для получения статусов сообщений на странице Аккаунт → Настройки задано значение:

http://www.somesite.com/bytehand_callback

Сервис BYTEHAND будет передавать статусы сообщений в виде:

http://www.somesite.com/bytehand_callback?id=1234&key=23AD33FE&action=outgoingStatus&message=33328197206816238&description=DELIVERED&error_code0&updated_at=2013-01-20+17%3A50%3A03

При создании обработчика необходимо учитывать:



Получение входящих сообщений

Информацию о том, как настроить обработчик и принципах его работы смотрите в разделе Передача статусов сообщений на обработчик клиента.

Описание параметров которые передаются клиенту:

Параметр Описание
id Идентификатор клиента.
key Последние 8 символов ключа.
action Операция, для входящих сообщений это значение: "incomingSms".
message Идентификатор сообщения.
to Номер мобильного телефона в международном формате, на который отправляется сообщение.
from Номер телефона отправителя.
text Текст сообщения. Максимальный размер – 800 символов. Сообщение при необходимости будет разбито на несколько SMS. Размер одного SMS – 160 символов в латинице или 70 символов в кириллице. При разбивке сообщения на несколько SMS в каждую часть добавляется заголовок для объединения частей в одно сообщение на телефоне получателя, и максимальная длина становится 67 для кириллицы и 153 для латинских букв.
posted_at Дата и время отправки SMS сообщения, часовой пояс GMT+0, формат yyyy-MM-dd HH:mm:ss.

Все параметры являются обязательными.

Пример

В качестве URL для получения статусов сообщений на странице Аккаунт → Настройки задано значение:

http://www.somesite.com/bytehand_callback

Сервис BYTEHAND вызовет обработчик запросов в виде:

http://www.somesite.com/bytehand_callback?id=1234&key=23AD33FE&action=incomingSms&message=41180473802076790&to=79161234567&from=79167654321&text=TEST&posted_at=2013-04-21+15%3A01%3A13


Открытие USSD сессии

Для открытия USSD сессии необходимо вызвать методом POST адрес:

http://bytehand.com:3800/ussd?id=<ID>&key=<KEY>&to=<PHONE>&data=<DATA>

Обратите внимание, вы не передаёте текст USSD сообщения и его тип при открытии сессии, эти данные сервис BYTEHAND запросит у вас самостоятельно, через вызов Обработчика запросов для USSD сессий.

Описание параметров запроса:

Параметр Описание
to Один номер мобильного телефона в международном формате. Обязательный параметр.
data Любые пользовательские данные, которые будут переданы в обработчик пользователя. Не более 32 символов. Необязательный параметр.

После обработки данных сервер возвращает клиенту результат в формате JSON.

Пример

http://bytehand.com:3800/ussd?id=1234&key=5D01022D23AD33FE&to=79161234567

Ответ, сессия открыта успешно:

{"status":0,"description":"38343592782147885"}

Описание параметров ответа:

Параметр Описание
status 0
description Идентификатор USSD сессии.

Если в настройках пользователя не задан URL для обработчика, то вызов данного метода приведёт к ошибке 20 - The notification URL is not set.


Получить информацию о USSD сессии

Чтобы получить информацию о USSD сессии необходимо вызвать методом GET адрес:

http://bytehand.com:3800/ussd/<SESSION_ID>?id=<ID>

Описание параметров запроса:

Параметр Описание
session_id Идентификатор USSD сессии. Обязательный параметр.

После обработки данных сервер возвращает клиенту результат в формате JSON.

Пример

http://bytehand.com:3800/ussd/38343592782147885?id=1234&key=5D01022D23AD33FE

Ответ, информация получена успешно:

{"id":38343592782147885,"to":"79161234567","exchange":[38343592995421181,38343624104272883,38343650042383969]}

Описание параметров ответа:

Параметр Описание
id Идентификатор USSD сессии.
to Один номер мобильного телефона в международном формате.
exchange Список идентификаторов USSD запросов в этой сессии.


Получить информацию о USSD запросе

Чтобы получить информацию о USSD запросе необходимо вызвать методом GET адрес:

http://bytehand.com:3800/ussd/<SESSION_ID>/<REQUEST_ID>?id=<ID>

Описание параметров запроса:

Параметр Описание
session_id Идентификатор USSD сессии. Обязательный параметр.
request_id Идентификатор запроса в рамках указанной USSD сессии. Обязательный параметр.

После обработки данных сервер возвращает клиенту результат в формате JSON.

Пример

http://bytehand.com:3800/ussd/38343592782147885/38343592995421181?id=1234&key=5D01022D23AD33FE

Ответ, информация получена успешно:

{"cost":2.0, "currency":643, "data":"0", "response_text":"BYTE@HAND\n1> English\n2> Русский", "id":38343592995421181, "error_code":0, "updated_at":"2013-03-17 23:43:52", "requested_at":"2013-03-16 23:12:24", "request_data":"200", "request_input":null, "response_at":"2013-03-17 23:43:53", "state":"DELIVERED"}

Описание параметров ответа:

Параметр Описание
id Идентификатор USSD запроса.
state Статус запроса, возможные значения: "NEW", "DELIVERED", "EXPIRED", "DELETED", "UNDELIVERABLE", "ACCEPTED", "UNKNOWN", "REJECTED".
error_code Код ошибки.
updated_at Дата и время последнего изменения статуса USSD запроса, часовой пояс GMT+0, формат yyyy-MM-dd HH:mm:ss.
requested_at Дата и время создания USSD запроса, часовой пояс GMT+0, формат yyyy-MM-dd HH:mm:ss.
request_data Данные, которые были переданы в обработчик.
request_input Данные, которые ввел пользователь на своём телефоне.
response_at Дата и время ответа на USSD запрос, часовой пояс GMT+0, формат yyyy-MM-dd HH:mm:ss.
response_type Тип ответа, возможные значения "TEXT", "INPUT".
response_data Данные, которые будут переданы в следующий USSD запрос.
response_text Текст сообщения.
cost Стоимость запроса в рублях.
currency Код валюты.


Обработчик статусов для USSD сессий

Информацию о том, как настроить обработчик и принципах его работы смотрите в разделе Передача статусов сообщений на обработчик клиента.

Описание параметров которые передаются клиенту:

Параметр Описание
id Идентификатор клиента.
key Последние 8 символов ключа.
action Операция, для статуса USSD это значение: "ussdStatus".
ussd_id Идентификатор сессии, уникальное значение, которое остается неизменным на протяжении всей сессии.
request_id Идентификатор запроса в рамках указанной USSD сессии.
description Статус сессии, возможные значения: "NEW", "DELIVERED", "EXPIRED", "DELETED", "UNDELIVERABLE", "ACCEPTED", "UNKNOWN", "REJECTED".
updated_at Дата и время последнего изменения статуса USSD запроса, часовой пояс GMT+0, формат yyyy-MM-dd HH:mm:ss.

Пример

В качестве URL для получения статусов сообщений на странице Аккаунт → Настройки задано значение:

http://www.somesite.com/bytehand_callback

Сервис BYTEHAND вызовет обработчик запросов для USSD сессий в виде:

http://www.somesite.com/bytehand_callback?id=1234&key=23AD33FE&action=ussd&ussd_id=38343592782147885&request_id=38343592995421181&description=DELIVERED&updated_at=2013-01-20+17%3A50%3A03


Обработчик запросов для USSD сессий

Информацию о том, как настроить обработчик и принципах его работы смотрите в разделе Передача статусов сообщений на обработчик клиента.

Описание параметров которые передаются клиенту:

Параметр Описание
id Идентификатор клиента.
key Последние 8 символов ключа.
action Операция, для USSD это значение: "ussd".
ussd_id Идентификатор сессии, уникальное значение, которое остается неизменным на протяжении всей сессии.
request_id Идентификатор запроса в рамках указанной USSD сессии.
data Пользовательские данные. Не более 32 символов. Необязательный параметр.
input Данные которые ввёл абонент со своего мобильного устройства. Необязательный параметр.

Пример

В качестве URL для получения статусов сообщений на странице Аккаунт → Настройки задано значение:

http://www.somesite.com/bytehand_callback

Сервис BYTEHAND вызовет обработчик запросов для USSD сессий в виде:

http://www.somesite.com/bytehand_callback?id=1234&key=23AD33FE&action=ussd&ussd_id=38343592782147885&request_id=38343592995421181

Ответ обработчика

Обработчик должен вернуть HTTP код 200 (OK) и данные в формате JSON:

{"type" : "TEXT", "text" : "Hello world!", "data" : ""}

Описание параметров ответа:

Параметр Описание
type Тип ответа, определяет вид USSD сообщения, возможные значения:
  • "CANCEL" - сообщение пользователю не посылается, USSD сессия закрывается;
  • "TEXT" - текстовое сообщение, ввод данных от пользователя не требуется, после отправки USSD сессия закрывается;
  • "INPUT" - текстовое сообщение и поле для ввода данных от пользователя, после отправки USSD сессия остаётся открытой, и в следующем запросе будут переданы введенные данные.
data Данные, которые будут переданы в следующий USSD запрос.
text Текст сообщения.

Рекомендуем воспользоваться Примером USSD сервиса для понимания принципов создания обработчика запросов для USSD сессий.


Коды ошибок

Если запрос выполнился успешно, код состояния HTTP ответа 200 (OK), а поля ответа зависят от типа запроса.

Если запрос выполнился с ошибкой, код состояния HTTP ответа 400 (Bad Request «плохой, неверный запрос»), а поля status и description содержат описание ошибки:

Параметр Описание
status Код ошибки, отличный от нуля.
description Текстовое описание ошибки.

Описание кодов ошибок:

Код Описание
-1 Unknown error.
1 The server encountered an unexpected condition.
2 Authorization failed.
3 The server does not support the function required.
4 The request is for something forbidden.
5 Routing is not allowed.
6 Some of parameters are invalid.
7 The timeout period elapsed prior to completion of the operation or the server is not responding.
8 Unable to decode, an unsupported encoding was used.
9 The requested object was not found.
10 Invalid message sender.
11 Invalid message receiver.
12 The phone number does not exist.
13 The phone number is switched off or out of the coverage.
14 The phone number is blocked.
15 The operation is not supported.
16 Operation result is unknown.
17 Too many operations.
18 Potential spam message.
19 The operation is still being processed.
20 The notification URL is not set.
21 Text blocked by black list.
22 Receiver blocked by black list.

Пример

Ответ, произошла ошибка:

{"status": "2", "description": "Authorization failed."}