Руccкий

Интерфейс программирования приложений (SMS API)

Пожалуйста, не забудьте заглянуть в раздел Как (Практическое руководство), прежде чем Вы зайдете куда-либо слишком далеко. Спасибо!

Послать SMS API

Функция: sendSms

Посылает GSM и Unicode SMS сообщения. Соединяет до 5 (765 символов) длинных сообщений автоматически.
Возвращает объект JSON, подтверждающий запрос (или сообщающий об ошибке).

Пример POST/GET

username=xxx&password=yyyy&function=sendSms &number=+491234567890&message=Have%20a%20nice%20day! &senderid=+44987654321&callbackurl=http://www.my-server.com/callback.php

Пример JSON

{
    "username":"xxx",
    "password":"yyy",
    "function":"sendSms",
    "number":"+491234567890",
    "message":"Have a nice day!",
    "senderid":"+449876543210",
    "callbackurl":"http://www.my-server.com/callback.php"
}

Обязательные параметры

Параметр Описание Тип
number Телефонный номер в международном формате. Например: 49123456789 или +49123456789 или 0049123456789 string
message Текст сообщения. My-Cool-SMS автоматически определяет кодировку вводных данных и обрабатывает SMS соответственно, как GSM или Unicode.
Вы можете использовать произвольный параметр Unicode чтобы получить определенную кодировку. Если значение Unicode верно, SMS будет передаваться как Unicode, и параметр сообщения должен быть предоставлен в обозначении Unicode UCS2. Если значение Unicode неверно, SMS будет отправлено, как GSM и параметр сообщения должен содержать только символы из алфавита GSM7.
Длинные сообщения автоматически соединяются. Максимальная длина - 765 символов для сообщений GSM или 335 для Unicode.
Обратите внимание, что вы всегда должны использовать параметр Unicode при отправке GET запросов.
string
Подсказка: Узнайте больше о GSM, Unicode и UCS2.

Произвольные параметры

Параметр Описание Тип
unicode Производит Unicode или GSM кодировку сообщения. Если установлено значение "верно", параметр сообщения должен быть предoставлен в обозначении UCS2. Если установлено значение "неверно", параметр сообщения должен содержать только символы из алфавита GSM7.
Если значение не установлено или установлено как "НОЛЬ", My-Cool-SMS будет автоматически определять входную кодировку.
boolean
senderid Мобильный номер в международном формате, например: +44123456789 или буквенно-цифровой ID отправителя в пределах 11 символов, например: Компания. string
scheduletime Пошлите сообщение в определенное время. Используйте ATOM формат и часовой пояс, например: "2011-04-17T17:59:36.67+08" или "2011-04-17 17:59:36-02" timestamp with timezone
callbackurl Обратный URL для получения сообщений о статусе и отчетов о доставке этого сообщения. Например: http://www.myserver.com/callback.php string
Подсказка: Узнайте больше о возвратах отчетов о доставке.

Пример успешного ответа

{
    "success":true,
    "smsid":"ce184cc0a6d1714d1ac763f4fe89f521",
    "body":"Have a nice day!",
    "bodyucs2":"0048006100760065002000610020006E00690063006500200064",
    "bodygsm7":"486176652061206E6963652064617921",
    "number":"+491234567890"
    "senderid":"+449876543210",
    "senderidenabled":true,
    "unicode":false,
    "numchars":321,
    "escapenumchars":0,
    "smscount":3,
    "charge":0.112,
    "balance":752.121,
    "countrycode":"DE",
    "prefix":"+49",
    "timestamp":"2013-04-02T22:27:22-07:00",
    "callbackurl":"http://www.my-server.com/callback.php"
}

Значения успешного ответа

Ключ Описание Тип
success Указывает может ли запрос быть успешно выполнен или нет. boolean
smsid Уникальный для этого SMS. Должны храниться у пользователя и использоваться в качестве ссылки для получения отчетов о доставке. string(32)
body Текст сообщения в Unicode string
bodyucs2 Текст сообщения в байткод обозначении GSM7 string
bodygsm7 Текст сообщения в байткод обозначении GSM7 (или НОЛЬ, если сообщение послано в Unicode) string || NULL
senderid Indicates the sender id used for the sent message. string
senderidenabled Указывает, поддерживает ли номер получателя динамичный ID отправителя boolean
unicode Указывает, было ли SMS отправлено как Unicode или GSM boolean
numchars Указывает количество символов в сообщении integer
escapenumchars Показывает, сколько символов необходимо избежать (и считается как два символа в GSM) integer
smscount Указывает, было ли сообщение соединено в длинное SMS и предоставляет количество соединенных SMS integer
charge Указывает сумму взымаемой оплаты за это SMS float
balance Оставшийся баланс на вашем счете. float
countrycode Indicates to which country the SMS was sent to (ISO Code) string
prefix Indicates the prefix of the country to which the SMS was sent to string
timestamp Timestamp of when the SMS was accepted (using the time zone you were on when you logged in to the web portal the last time or UTC if unknown). Given in DATE_ATOM Format (e.g. 2013-04-02T22:27:22-07:00). string
callbackurl Callback URL, на который будут доставлены отбновления о статусе и отчеты о доставке сообщения. string || NULL

Ошибки API определенной функции

Ошибочный код Описание ошибки
210 Номер не действителен
211 Отсутствует параметр сообщения
212 Слишком длинный параметр сообщения
213 Unicode параметр настроен на получение Unicode, но параметр сообщения не был представлен в UCS2 обозначении.
214 Unicode параметр настроен на получение GSM, но параметр сообщения не был представлен в UCS2 обозначении.
215 Unicode параметр настроен на получение GSM, но параметр сообщения содержит символы, не входящие в алфавит GSM7
216 The input for Sender ID is invalid. You may use a phone number or an alphanumeric text with up to eleven characters (A-Z, a-z, 0-9 and the dash symbol).
217 Короткие ID отправителя не разрешены
218 Параметр callback URL недействителен
219 Время в расписании недействительно. Используйте ATOM формат и часовой пояс, например: "2011-04-17T17:59:36.67+08" или "2011-04-17 17:59:36-02"
Подсказка: Также посмотрите раздел об общих ошибках

Входящие SMS API

Обратный звонок: pushIncomingSms

My-Cool-SMS автоматически выталкивает SMS данные на сервер, если callback URL для Вашего номера обозначен в настойках Ваших входящих. Вы можете редактировать свой callback URL в настойках вашего почтового ящика через веб-интерфейс My-Cool-SMS.

Пример callback

POST /your/callbackurl.php HTTP/1.1
Content-Type: application/json
Host: www.your-server.com
User-Agent: My-Cool-SMS Incoming SMS Callback
Content-Length: n
Cache-Control: no-cache
Connection: close

{
   "from":"+1230987654321",
   "fromcountrycode":"US",
   "to":"+440987654321",
   "unicode":false,
   "smscount":1,
   "body":"Have a nice day with incoming SMS!",
   "bodyucs2":"0048006100760065002000610020006e00690063006500200064",
   "bodygsm7":"5374616666206D6565746925",
   "numchars":54,
   "escapenumchars":0,
   "cost":"0.010"
}
Подсказка: Посмотрите здесь для получения дополнительной информации о том, как использовать JSON callbacks.

Callback значения

Ключ Описание Тип
from ID отправителя, с которым было послано сообщение, буквенно-цифровой или в международном формате. string
fromcountrycode Содержит двухзначный код ISO код страны отправителя, если параметр "от" состоит из цифр. Содержит NULL, если параметр буквенно-цифровой. string(2) || NULL
to Номер, на который было отправлено сообщение (Ваш виртуальный номер телефона) string
unicode Указывает, было ли отправлено в Unicode или GSM. boolean
smscount Указывает, было ли сообщение соединено в длинное SMS и предоставляет количество соединенных SMS integer
body Текст сообщения в Unicode string
bodyucs2 Текст сообщения в байткод обозначении GSM7 string
bodygsm7 Текст сообщения в байткод обозначении GSM7 (или НОЛЬ, если сообщение послано в Unicode) string
numchars Указывает количество символов в сообщении integer
escapenumchars Показывает, сколько символов необходимо избежать (и считается как два символа в GSM) integer
cost Указывает сумму взымаемой оплаты за это SMS float

Функция: getIncomingSms

Queries the server for received SMS text messages. Returns a status summary for the selected virtual number and an array containing inbound SMS. Can be customized by using the optional parameters.

Пример POST/GET

username=xxx&password=yyy&function=getIncomingSms&virtualnumber=+449876543201

Пример JSON

{
    "username":"xxx",
    "password":"yyy",
    "function":"getIncomingSms",
    "virtualnumber":"+449876543201"
}

Обязательные параметры

Параметр Описание Тип

Произвольные параметры

Параметр Описание Тип
thresholdid Only messages with a higher id should be returned. This parameter is required to only receive messages that have been received after the ones that were fetched already. Every message fetched with the getIncomingSms function contains a unique id, which should be stored on client side in order to use it here. Defaults to 0. integer
limit The maximum amount of messages to be returned. Defaults to 25. If set to 0, no limit will be applied. integer
order Specifies the order in which the results should be returned. Can be "ASC" or "DESC". Defaults to "DESC" string
thresholdoperator Specifies whether the returned messages should have higher or lower ids as compared to the id provided in thresholdid. Can be either "gt" (greater than) or "lt" (lower than). Defaults to "gt" string(2)
virtualnumber The virtual number for which sms text messages should be fetched. If no virtual number is provided inbound texts for all virtual numbers will be returned. string
unreadsmstosyncids This parameter is useful if you want to sync the read/unread status of your inbound SMS pipe on several devices. Provide the ids of the messages that are marked as unread on your device to receive a list of ids of messages that have been marked as read on a different device. You can use those ids to update the read/unread status on your device. If no messages were marked as read the list will be empty. array[int]

Пример успешного ответа

{
   "success":true,
   "total":"17",
   "fetched":1,
   "maxid":201,
   "minid":177,
   "messages":[
      {
         "id":201,
         "virtualnumber":"+449876543201",
         "senderid":"+886983029751",
         "body":"Have a nice day!",
         "bodyucs2":"AAAA",
         "bodygsm7":"AA",
         "unicode":false,
         "timestamp":"2011-08-10 00:08:37.488+08",
         "unixtimestamp":"1316531343.9",
         "numchars":16,
         "escapechars":0,
         "smscount":1,
         "charge":"0.015",
         "senderidcountrycode":"TW",
         "virtualnumbercountrycode":"HK"
      }
   ]
}

Значения успешного ответа

Ключ Описание Тип
success Указывает может ли запрос быть успешно выполнен или нет. boolean
total The total number of messages on this virtual number integer
fetched The number of messages that were fetched integer
maxid The "maxid" parameter indicates the highest unique id (last message) on this virtual number. This value should be stored and use for future queries as "thresholdid" parameter in order to just fetch new messages. integer
minid The lowest sms id found for this user. Can be used for client side reference. integer
messages Contains an array of SMS text objects (with self-explaining attribute names, see example). array

Ошибки API определенной функции

Ошибочный код Описание ошибки
232 Номер не действителен
233 The virtual number is either invalid or not registered with this user account. Please contact service@my-cool-sms.com for assistance.
234 The provided thresholdid is invalid
235 Неверный параметр ограничения
236 Invalid order parameter
242 No virtual numbers found.
Подсказка: Также посмотрите раздел об общих ошибках

Просмотр баланса API

Функция: getBalance

Возвращает JSON объект, содержащий информацию, об оставшемся балансе на вашем счете (или об ошибке).

Пример POST/GET

username=xxx&password=yyyy&function=getBalance

Пример JSON

{
    "username":"xxx",
    "password":"yyy",
    "function":"getBalance"
}

Пример успешного ответа

{
    "success":true,
    "balance":752.210
}

Значения успешного ответа

Ключ Описание Тип
success Указывает может ли запрос быть успешно выполнен или нет. boolean
balance Оставшийся баланс в евро float

Отчет о доставке API

Существует два способа получать отчеты о доставке из My-Cool-SMS. Вы можете послать запрос на сервер с getDeliveryReport или получать HTTP cllbacks на URL Вашего сервера, используя pushDeliveryReport. Обратите внимание, что отчеты о доставке для рассылок доступны только через getDeliveryReport.

Функция: getDeliveryReport

Возвращает отчет о доставке одного SMS (отправляются с sendSms) или группы рассылки (отправляется с sendMailing). Если запрашивается отчет о доставке для группы рассылки (путем установки дополнительного параметра groupkey как "верно"), возвращенный объект может содержать резюме (по умолчанию) или отдельные отчеты о доставке для каждого получателя (путем установки дополнительного параметра mailingdetails как "верно").

Пример POST/GET

username=xxx&password=yyyy&function=getDeliveryReport &id=ce184cc0a6d1714d1ac763f4fe89f521

Пример JSON

{
    "username":"xxx",
    "password":"yyy",
    "function":"getDeliveryReport",
    "id":"ce184cc0a6d1714d1ac763f4fe89f521"
}

Обязательные параметры

Параметр Описание Тип
id Референс ID . Либо SMS ID (возвращенный с sendSms) или ключ групповой рассылки (возвращенный с sendMailing). Если используется ключ, то дополнительный параметр groupkey должен быть установлен как "верно". string

Произвольные параметры

Параметр Описание Тип
groupkey Установите как "верно", если ключ группы была представлен ​​в параметре ID, и вы хотите получить отчет о доставке для рассылки (вместо одного SMS). Установливается, как "не верно", по умолчанию. string
mailingdetails Установите как "верно", если вы хотите получить отдельный отчет о доставке для каждого абонента, в дополнение к общему резюме. Установливается, как "не верно", по умолчанию. string

Пример успешного ответа: groupkey=false (По умолчанию)

{
    "success":true,
    "smsid":"ce184cc0a6d1714d1ac763f4fe89f521",
    "status":"SMS_STATUS_DELIVERED"
}

Значения успешного ответа: groupkey=false (По умолчанию)

Ключ Описание Тип
success Указывает может ли запрос быть успешно выполнен или нет. boolean
smsid ID SMS, к которому относится отчет о доставке string
status Указывает статус этого sms string
Подсказка: Посмотрите здесь для более подробной информации о статус кодах.

Пример успешного ответа: groupkey=true

{
    "success":true,
    "groupkey":"d3743cc0a6d1714d1ac763f4fe89f521",
    "total":12,
    "SMS_STATUS_QUEUED":0,
    "SMS_STATUS_AT_CARRIER":0,
    "SMS_STATUS_DELIVERED":12,
    "SMS_STATUS_BOUNCED":0,
    "SMS_STATUS_ERROR":0
}
Подсказка: Посмотрите здесь для более подробной информации о статус кодах.

Пример успешного ответа: groupkey=true&mailingdetails=true

{
    "success":true,
    "groupkey":"d3743cc0a6d1714d1ac763f4fe89f521",
    "total":12,
    "SMS_STATUS_QUEUED":0,
    "SMS_STATUS_AT_CARRIER":0,
    "SMS_STATUS_DELIVERED":12,
    "SMS_STATUS_BOUNCED":0,
    "SMS_STATUS_ERROR":0,
    "details":[
        {
            "recipient":"+1230987654321",
            "status":"SMS_STATUS_DELIVERED"
        },
        {
            "recipient":"+1230987654322",
            "status":"SMS_STATUS_DELIVERED"
        }, 
        (...)
    ]
}
Подсказка: Посмотрите здесь для более подробной информации о статус кодах.

Ошибки API определенной функции

Ошибочный код Описание ошибки
223 Неизвестный SMS ID
224 Ключ неизвестной группы
Подсказка: Также посмотрите раздел об общих ошибках

Функция: getDeliveryReports

Returns delivery reports for a list of messages.

Пример JSON

{
    "username":"xxx",
    "password":"yyy",
    "function":"getDeliveryReports",
    "ids":[
        "ce184cc0a6d1714d1ac763f4fe89f521",
        "d1ac763f4fe89f521ce184cc0a6d1714"
    ]
}

Обязательные параметры

Параметр Описание Тип
ids An array of sms ids to perform the delivery status lookup for. array[]

Пример успешного ответа:

{
    "success":true,
    "reports": [
        {
            "smsid":"ce184cc0a6d1714d1ac763f4fe89f521",
            "status":"SMS_STATUS_DELIVERED"
        },
        {
            "smsid":"d1ac763f4fe89f521ce184cc0a6d1714",
            "status":"SMS_STATUS_DELIVERED"
        }
    ]
}

Значения успешного ответа:

Ключ Описание Тип
success Указывает может ли запрос быть успешно выполнен или нет. boolean
reports[] Contains an array with delivery report objects. Each object contains the reference id (smsid) and the corresponding delivery status (status). array
reports[n].smsid Contains the reference sms id for this delivery report string
reports[n].status Contains the delivery status for this SMS. Possible states are: SMS_STATUS_QUEUED, SMS_STATUS_AT_CARRIER, SMS_STATUS_DELIVERY_DELAYED, SMS_STATUS_DELIVERED, SMS_STATUS_BOUNCED, SMS_STATUS_EXPIRED, SMS_STATUS_ERROR or UNKNOWN_ID. string
Подсказка: Посмотрите здесь для более подробной информации о статус кодах.

Ошибки API определенной функции

Ошибочный код Описание ошибки
240 The input for the "ids" parameter seems invalid. Please make sure to provide an array with valid sms ids.
241 The maximum number of delivery reports per request is 100.
Подсказка: Также посмотрите раздел об общих ошибках

Функция: getRecentReports

Возвращает объект JSON с доставкой отчетов для недавно отправленных сообщений.

Пример POST/GET

username=xxx&password=yyyy&function=getRecentReports&limit=10

Пример JSON

{
    "username":"xxx",
    "password":"yyy",
    "function":"getRecentReports",
    "limit":10
}

Обязательные параметры

Параметр Описание Тип
limit Указывает количество отчетов о доставке integer

Пример успешного ответа

{
   "success":true,
   "reports":[
      {
         "number":"+1230987654321",
         "senderid":"+449876543210",
         "body":"Have a nice day!",
         "bodyucs2":"0048006100760065002000610020006E006900630065002",
         "bodygsm7":"486176652061206E6963652064617921",
         "unicode":false,
         "timesent":"2011-04-19 12:08:37.233+08",
         "status":"SMS_STATUS_DELIVERED"
      },
      {
         "number":"+1230987654321",
         "senderid":"+449876543210",
         "body":"Have a nice day!",
         "bodyucs2":"0048006100760065002000610020006E006900630065002",
         "bodygsm7":"486176652061206E6963652064617921",
         "unicode":false,
         "timesent":"2011-04-19 12:01:03.338+08",
         "status":"SMS_STATUS_DELIVERED"
      },
      {
         "number":"+1230987654321",
         "senderid":"+449876543210",
         "body":"Have a nice day with long Unicode messages! \u7e41",
         "bodyucs2":"0048006100760065002000610020006e00690063006500",
         "bodygsm7":"",
         "unicode":true,
         "timesent":"2011-04-18 21:53:24.787+08",
         "status":"SMS_STATUS_DELIVERED"
      },
      (...)
   ]
}

Значения успешного ответа

Ключ Описание Тип
success Указывает может ли запрос быть успешно выполнен или нет. boolean
number Номер адресата string
senderid ID отправителя, с которым было отправлено сообщение string
body Текст сообщения в Unicode string
bodyucs2 Текст сообщения в байткод обозначении GSM7 string
bodygsm7 Текст сообщения в байткод обозначении GSM7 (или НОЛЬ, если сообщение послано в Unicode) string
unicode Указывает, было ли SMS отправлено как Unicode или GSM boolean
timesent Время когда было отправлено сообщение timestamp with time zone
status Указывает статус этого sms string
Подсказка: Посмотрите здесь для более подробной информации о статус кодах.

Ошибки API определенной функции

Ошибочный код Описание ошибки
225 Неверный параметр ограничения
Подсказка: Также посмотрите раздел об общих ошибках

Обратный звонок: pushDeliveryReport

My-Cool-SMS автоматически выталкивает отчет о доставке на ваш сервер при отправке через функцию sendSms, если настроен параметр URL callback. Callback посылается в виде необработанных данных JSON запроса.

Пример callback

POST /your/callbackurl.php HTTP/1.1
Content-Type: application/json
Host: www.your-server.com
User-Agent: My-Cool-SMS Delivery Report
Content-Length: n
Cache-Control: no-cache
Connection: close

{
    "smsid":"498673a1f58df975ab95da33884d9e14",
    "status":"SMS_STATUS_DELIVERED"
}
Подсказка: Посмотрите здесь для получения дополнительной информации о том, как использовать JSON callbacks.

Callback значения

Ключ Описание Тип
smsid Уникальный ID и ссылка для SMS. SMS ID был возвращен в ответе об успехе sendSms функции string(32)
status Указывает статус этого sms string

Ссылка о статусе

Status Описание
SMS_STATUS_QUEUED На очереди - Это сообщение на очереди и еще не было отправлено.
SMS_STATUS_AT_CARRIER У курьера - Сообщение было отправлено в сеть провайдера и должно отображаться как 'доставлено', как только оно поступит на телефон получателя.
Имейте в виду, что в некоторых случаях курьеры не предоставляют отчет о доставке. В таких случаях, сообщение будет оставаться в статусе "у курьера", даже когда оно успешно доставлено.
SMS_STATUS_DELIVERY_DELAYED Доставка задерживается - Задержка в доставке сообщения
SMS_STATUS_DELIVERED Доставлено - Сообщение было успешно доставлено на номер адресата
SMS_STATUS_BOUNCED Отклонено - Сообщение отклонено получателем. Возножными причинами могут быть недействительные номер телефона или ID отправителя, телефон получателя вне доступа сети долгое время или проблемы с сетью оператора.
SMS_STATUS_EXPIRED Истек срок действия - Срок этого сообщения истек и оно не может быть доставлено.
Эта проблема обычно возникает, если телефон абонента был отключен или был вне зоны сервиса долгое время.
SMS_STATUS_ERROR Отправка не удалась - Доставка не удалась (вы не оплачиваете это сообщение).
Возможные причины: My-Cool-SMS не может определить к какому провайдеру принадлежит номер телефона (пожалуйста, свяжитесь со службой поддержки, если вы уверены в правильности номера) или временная ошибка в сети.

Функция: getOutboundSms

This function is useful if you want to sync the outbound SMS streams in your account for different devices. It queries the server for outbound sms data and returns and array delivery statuses and additional information on the messages, such as content and timestamps.

Пример POST/GET

username=xxx&password=yyy&function=getOutboundSms

Пример JSON

{
    "username":"xxx",
    "password":"yyy",
    "function":"getOutboundSms"
}

Обязательные параметры

Параметр Описание Тип

Произвольные параметры

Параметр Описание Тип
thresholdid Use this parameter to specify the particular message for which you would like to check if messages were sent before or after. Combine with the thresholdoperator parameter to specify if you need messages with lower or greater ids. string(32)
limit The maximum amount of messages to be returned. Defaults to 25. integer
thresholdoperator Specifies whether the returned messages should have higher or lower ids as compared to the id provided in thresholdid. Can be either "gt" (greater than) or "lt" (lower than). Defaults to "gt" string
order Specifies the order in which the results should be returned. Can be "ASC" or "DESC". Defaults to "DESC" string

Пример успешного ответа

{
   "success":true,
   "total":"17",
   "fetched":1,
   "maxid":201,
   "minid":177,
   "messages":[
      {
        "smsid":"ce184cc0a6d1714d1ac763f4fe89f521",
        "body":"Have a nice day!",
        "bodyucs2":"0048006100760065002000610020006E00690063006500200064",
        "bodygsm7":"486176652061206E6963652064617921",
        "number":"+491234567890"
        "senderid":"+449876543210",
        "senderidenabled":"+449876543210",
        "unicode":false,
        "numchars":321,
        "escapenumchars":0,
        "smscount":3,
        "charge":0.112,
        "countrycode":"DE",
        "prefix":"+49",
        "timestamp":"2013-04-02T22:27:22-07:00",
        "callbackurl":"http://www.my-server.com/callback.php",
        "status":"SMS_STATUS_DELIVERED"
      }
   ]
}

Значения успешного ответа

Ключ Описание Тип
success Указывает может ли запрос быть успешно выполнен или нет. boolean
total The total number of SMS sent on this account. integer
fetched The total number of SMS returned by this query. integer
maxid Indicates the newest sms returned by this query. Can be used as new thresholdoperator parameter in a subsequent API call. integer
minid Indicates the oldest sms returned by this query. Can be used as new thresholdoperator parameter in a subsequent API call. integer
messages An array containing objects with the outbound SMS returned by this query. The SMS object attributes correspond to the return values of the sendSms function (please see that section for details). array

Ошибки API определенной функции

Ошибочный код Описание ошибки
234 The provided thresholdid is invalid
235 Неверный параметр ограничения
236 Invalid order parameter
Подсказка: Также посмотрите раздел об общих ошибках

Список рассылки API

Функция: sendMailing

Отправляет SMS на весь список рассылки. Подсказка: Вы можете создавать и управлять списками рассылки в вашем My-Cool-SMS веб-интерфейсе.
Возвращает объект JSON подтверждающий запрос (или ошибку).

Пример POST/GET

username=xxx&password=yyyy&function=sendMailing &uniqueid=75F3FAB&message=Staff%20meeting%20in%2020%20minutes. &senderid=MyCompany

Пример JSON

{
    "username":"xxx",
    "password":"yyy",
    "function":"sendMailing",
    "uniqueid":"75F3FAB",
    "message":"Staff meeting in 20 minutes. Balcony meeting room.",
    "senderid":"MyCompany"
}

Обязательные параметры

Параметр Описание Тип
uniqueid Уникальные ID списка рассылки. Вы найдете ваши уникальные ID в интерфейсе управления списками рассылки на веб-сайте. string
message Текст сообщения. My-Cool-SMS автоматически определяет кодировку вводных данных и обрабатывает SMS соответственно, как GSM или Unicode.
Вы можете использовать произвольный параметр Unicode чтобы получить определенную кодировку. Если значение Unicode верно, SMS будет передаваться как Unicode, и параметр сообщения должен быть предоставлен в обозначении Unicode UCS2. Если значение Unicode неверно, SMS будет отправлено, как GSM и параметр сообщения должен содержать только символы из алфавита GSM7.
Длинные сообщения автоматически соединяются. Максимальная длина - 765 символов для сообщений GSM или 335 для Unicode.
Обратите внимание, что вы всегда должны использовать параметр Unicode при отправке GET запросов.
string
Подсказка: Узнайте больше о GSM, Unicode и UCS2.

Произвольные параметры

Параметр Описание Тип
unicode Производит Unicode или GSM кодировку сообщения. Если установлено значение "верно", параметр сообщения должен быть предoставлен в обозначении UCS2. Если установлено значение "неверно", параметр сообщения должен содержать только символы из алфавита GSM7.
Если значение не установлено или установлено как "НОЛЬ", My-Cool-SMS будет автоматически определять входную кодировку.
boolean
senderid Мобильный номер в международном формате, например: +44123456789 или буквенно-цифровой ID отправителя в пределах 11 символов, например: Компания. string
scheduletime Пошлите сообщение в определенное время. Используйте ATOM формат и часовой пояс, например: "2011-04-17T17:59:36.67+08" или "2011-04-17 17:59:36-02" timestamp with time zone
Подсказка: Узнайте больше о возвратах отчетов о доставке.

Пример успешного ответа

{
    "success":true,
    "groupkey":"041d3b026a50669481695dcf9e1985e4",
    "body":"Staff meeting in 20 minutes. Balcony meeting room.",
    "bodyucs2":"005300740061006600660020006D0065006500740069",
    "bodygsm7":"5374616666206D656574696E672069",
    "uniqueid":"75F3FAB"
    "senderid":"MyCompany",
    "senderidenabled":true,
    "unicode":false,
    "numchars":62,
    "escapenumchars":0,
    "smscount":1,
    "subscribers":79,
    "charge":3.212,
    "balance":752.121
}

Значения успешного ответа

Ключ Описание Тип
success Указывает может ли запрос быть успешно выполнен или нет. boolean
groupkey Уникальный ключ для этой рассылки. Должен храниться у клиента и использоваться для получения отчетов о доставке string(32)
body Текст сообщения в Unicode string
bodyucs2 Текст сообщения в байткод обозначении GSM7 string
bodygsm7 Текст сообщения в байткод обозначении GSM7 (или НОЛЬ, если сообщение послано в Unicode) string || NULL
uniqueid string(7)
senderid Указывает, поддерживает ли номер получателя динамичный ID отправителя boolean
unicode Указывает, было ли SMS отправлено как Unicode или GSM boolean
numchars Указывает количество символов в сообщении integer
escapenumchars Показывает, сколько символов необходимо избежать (и считается как два символа в GSM) integer
smscount Указывает, было ли сообщение соединено в длинное SMS и предоставляет количество соединенных SMS integer
subscribers Количество абонентов, которым было отправлено сообщение integer
charge Указывает сумму взымаемой оплаты за это SMS float
balance Оставшийся баланс на вашем счете. float

Ошибки API определенной функции

Ошибочный код Описание ошибки
220 Уникальное ID не связано ни с каким из Ваших списков рассылки
Подсказка: Также посмотрите раздел об общих ошибках

Функция: addSubscriber

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

Пример POST/GET

username=xxx&password=yyyy&function=addSubscriber &uniqueid=75F3FAB&number=+1230987654321&title=Ms&firstname=Marylin &lastname=Monroe&company=Hollywood

Пример JSON

{
    "username":"xxx",
    "password":"yyy",
    "function":"addSubscriber",
    "uniqueid":"75F3FAB",
    "number":"+1230987654321",
    "title":"Ms",
    "firstname":"Marylin",
    "lastname":"Monroe",
    "company":"Hollywood"
}

Обязательные параметры

Параметр Описание Тип
number Номер абонента в международном формате: Например 49123456789 или +49123456789 или 0049123456789 string
uniqueid Уникальные ID списка рассылки. Вы найдете ваши уникальные ID в интерфейсе управления списками рассылки на веб-сайте. string

Произвольные параметры

Параметр Описание Тип
title Титул абонента varchar(16)
firstname Имя абонента varchar(32)
lastname Фамилия абонента varchar(32)
company Компания абонента varchar(64)

Пример успешного ответа

{
    "success":true,
    "number":"+1230987654321"
    "title":"Ms",
    "firstname":"Marylin",
    "lastname":"Monroe",
    "company":"Hollywood",
    "subscribercost":0.019,
    "senderidenabled":true,
    "maxcharsgsm":765,
    "maxcharsunicode":335,
    "countrycode":"US",
    "mailinglistcost":1.213
    "mailinglistsubscribers":74
}

Значения успешного ответа

Ключ Описание Тип
success Указывает может ли запрос быть успешно выполнен или нет. boolean
number Нормированный номер телефона нового абонента string
title Титул нового подписчика string
firstname Имя нового подписчика string
lastname Фамилия нового подписчика string
company Компания нового подписчика string
subscribercost Стоимость сообщения этому абоненту float
senderidenabled Указывает поддерживает ли абонент ID отправителя boolean
maxcharsgsm Показывает, сколько символов для GSM сообщений абонент поддерживает integer
maxcharsunicode Показывает, сколько символов для Unicode сообщений абонент поддерживает integer
countrycode Код страны абонентов (двухбуквенный стандартный формат ISO) string(2)
mailinglistcost Новая общая стоимость рассылки этому списку float
mailinglistsubscribers Новое количество абонентов на этом списке рассылки integer

Ошибки API определенной функции

Ошибочный код Описание ошибки
221 {field} Поле слишком длинное.
Подсказка: Также посмотрите раздел об общих ошибках

Функция: updateSubscriber

Смотреть Функция: addSubscriber

Функция: deleteSubscriber

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

Пример POST/GET

username=xxx&password=yyyy&function=deleteSubscriber &uniqueid=75F3FAB&number=+1230987654321

Пример JSON

{
    "username":"xxx",
    "password":"yyy",
    "function":"deleteSubscriber",
    "uniqueid":"75F3FAB",
    "number":"+1230987654321"
}

Обязательные параметры

Параметр Описание Тип
uniqueid Уникальные ID списка рассылки. Вы найдете ваши уникальные ID в интерфейсе управления списками рассылки на веб-сайте. string
number Количество абонентов, которое необходимо удалить из этого списка рассылки string

Пример успешного ответа

{
    "success":true,
    "number":"+1230987654321"
    "mailinglistcost":1.213
    "mailinglistsubscribers":74
}

Значения успешного ответа

Ключ Описание Тип
success Указывает может ли запрос быть успешно выполнен или нет. boolean
number Нормированный номер телефона удаленного абонента string
mailinglistcost Новая общая стоимость рассылки этому списку float
mailinglistsubscribers Новое количество абонентов на этом списке рассылки integer

Ошибки API определенной функции

Ошибочный код Описание ошибки
220 Уникальное ID не связано ни с каким из Ваших списков рассылки
222 Абонента с таким номеров в этом списке нет
Подсказка: Также посмотрите раздел об общих ошибках

API утилиты

Функция: doHlrLookup

Выполняет HLR (Опорный Регистр Местонахождения) поиск и предоставляет MSC, MCC, MNC, INSI этого номера, а также информацию об имени сети, находится ли номер в настоящее время в роуминге и был ли он перенесен в другую сеть.
Подсказка: Узнайте больше о HLR, IMSI, MCC, MNC и MSC.

Пример JSON

{
    "username":"xxx",
    "password":"yyy",
    "function":"doHlrLookup",
    "number":"+491234567890"
}

Обязательные параметры

Параметр Описание Тип
number Номер для выполнения поиска HLR в международном формате. Например: 49123456789 или +49123456789 или 0049123456789 string

Пример успешного ответа

{
    "success":true,
    "status":"HLR_STATUS_OK",
    "number":"+49178873xxxxx",
    "imsi":"262031350393955",
    "mcc":"262",
    "mnc":"03",
    "msin":"1350393955",
    "servingmsc":"88693542",
    "servinghlr":"491770112000",
    "originalnetworkname":"E-Plus",
    "originalnetworkprefix":"178",
    "originalcountryname":"Germany",
    "originalcountrycode":"DE",
    "originalcountryprefix":"+49",
    "roamingcountryname":"Taiwan",
    "roamingcountrycode":"TW",
    "roamingcountryprefix":"+886",
    "roamingnetworkname":"Taiwan Mobile",
    "portednetworkname": null,
    "isported":false,
    "iscorrect":true,
    "isroaming":true,
    "charge":0.010
}

Значения успешного ответа

Ключ Описание Тип
success Указывает может ли запрос быть успешно выполнен или нет. boolean
status Показывает статус поиска. Пожалуйста, обратитесь к таблице HLR поиска для деталей. string
number Номер, для которого проводился поиск HLR. string
imsi Международный идентификатор мобильного абонента (IMSI). Уникальное ID абонента. string
mcc Мобильный Код Страны (MCC) string
mnc Код Мобильной Сети (MNC), состоящий из 3х (Североамериканский стандарт) или 2х (Европейский стандарт) цифр. string
msin Мобильный идентификационный номер подписки (MSIN) в рамках клиентской базы сети. string
servingmsc Центр Мобильной Коммутации (MSC) отвечающий за маршрутизацию SMS. string
servinghlr Опорный Регистр Местонахождения (HLR), связанный с номером абонента. string
originalnetworkname Сеть мобильной связи, к которой принадлежит этот номер (или принадлежал первоначально, если это перенесенный номер) string
originalnetworkprefix Префикс мобильной сети, к которой принадлежит этот номер (или принадлежал первоначально если это перенесенный номер) string
originalcountryname Страна, которой принадлежит этот номер. string
originalcountrycode Вдухзначный код страны ISO, которой принадлежит этот номер string
originalcountryprefix Префикс страны, которой принадлежит этот номер string
roamingcountryname Страна, в которой, на данный момент, этот номер находится в роуминге. string
roamingcountrycode Вдухзначный код страны, в которой, на данный момент, этот номер находится в роуминге. string
roamingcountryprefix Префикс страны, в которой, на данный момент, этот номер находится в роуминге. string
roamingnetworkname The network the cell phone is currently roaming with string
portednetworkname The network the number has been ported to string
isported Указывает, перенесенный ли это номер boolean
iscorrect Указывает действительность номера boolean
isroaming Указывает, находится ли этот номер, на данный момент, в роуминге boolean
charge Стоимость данного HLR поиска (0.01 EUR) numeric
Подсказка: Узнайте больше о HLR, IMSI, MCC, MNC и MSC.

Ошибки API определенной функции

Ошибочный код Описание ошибки
210 Номер не действителен
226 Поиск HLR неудался. Оплата не взымается.
Подсказка: Также посмотрите раздел об общих ошибках

HLR Ссылка о статусе

Status Описание
HLR_STATUS_UNKNOWN_NUMBER Этот номер не существует или не может быть найден ни в одном HLR. SMS не будет доставлен.
HLR_STATUS_OK Это номер существует и HLR поиск прошел успешно. SMS будет доставлен.
HLR_STATUS_NOT_OK Этот номер находится вне сети долгое время или был отключен провайдером связи. SMS не будет доставлено.
HLR_STATUS_FAILED HLR поиск неудался. Оплата не взымается.
HLR_STATUS_AWAITING_RESPONSE Awaiting response from HLR.

Функция: toUCS2

UCS2 кодирует заданную Unicode строку
Важно: toUCS2 требует JSON запрос

Пример JSON

{
    "username":"xxx",
    "password":"yyy",
    "function":"toUCS2",
    "str":"繁体中文"
}

Обязательные параметры

Параметр Описание Тип
number Номер для выполнения поиска HLR в международном формате. Например: 49123456789 или +49123456789 или 0049123456789 string

Произвольные параметры

Параметр Описание Тип

Пример успешного ответа

{
    "success":true,
    "ucs2":"7E414F534E2D6587"
}

Значения успешного ответа

Ключ Описание Тип
success Указывает может ли запрос быть успешно выполнен или нет. boolean
ucs2 Введенная строка в значении UCS2 string

Ошибки API определенной функции

Пусто
Подсказка: Также посмотрите раздел об общих ошибках

Функция: fromUCS2

Декодирует заданную UCS2 строку

Пример POST/GET

username=xxx&password=yyyy&function=fromUCS2 &str=0048006100760065002000610020006E00690063006500200064

Пример JSON

{
    "username":"xxx",
    "password":"yyy",
    "function":"fromUCS2",
    "str":"7E414F534E2D6587"
}

Обязательные параметры

Параметр Описание Тип
str UCS2 строка для декодирования string

Пример успешного ответа

{
    "success":true,
    "decoded":"繁体中文"
}

Значения успешного ответа

Ключ Описание Тип
success Указывает может ли запрос быть успешно выполнен или нет. boolean
decoded Декодированная UCS2 строка в Unicode string

Ошибки API определенной функции

Ошибочный код Описание ошибки
201 Недействительный UCS2 данные
Подсказка: Также посмотрите раздел об общих ошибках

Функция: normalizeNumber

Normalizes a cell phone number in loose format into international standard MSISDN format. For example from +1(712)543-2321 into +17125432321

Пример POST/GET

username=xxx&password=yyyy&function=normalizeNumber&number=001(712)736-3423

Пример JSON

{
    "username":"xxx",
    "password":"yyy",
    "function":"normalizeNumber",
    "number":"001(712)736-3423"
}

Обязательные параметры

Параметр Описание Тип
number The phone number to normalize. Loose format, e.g. 00491787654321, 0049(178)765-4321 etc. string

Пример успешного ответа

{
    "success":true,
    "number":"+17127363423",
    "countrycode":"US"
}

Значения успешного ответа

Ключ Описание Тип
success Указывает может ли запрос быть успешно выполнен или нет. boolean
number The normalized number in international MSISDN standard format. string
countrycode The corresponding country code (international two-character ISO format) string(2)

Ошибки API определенной функции

Ошибочный код Описание ошибки
237 The number could not be normalized.

Ошибочные ответы

All API errors responses have a standardized JSON structure with a success, errorcode and errordescription attribute.

Пример ошибочного ответа

{
    "success":false,
    "errorcode":103,
    "errordescription":"Отсутствует обязательный параметр: senderid"
}

Значения ошибочного ответа

Ключ Описание Тип
success Указывает может ли запрос быть успешно выполнен или нет. boolean
errorcode Трехзначный код ошибки string(3)
errordescription Описание ошибки string

Ошибки API определенной функции

Некоторые функции имеют конкретные коды ошибок API, которые уникальны для данной функции. В таких случаях коды ошибок имеют формат 2xx. Пожалуйста, обратитесь к документации о функциях для индивидуальных кодов ошибок.

Общие API ошибки

В дополнение к функции конкретных ошибок, любой запрос к API может привести к общей ошибке API с ошибочным кодом в формате 1xx.

Общие коды ошибок

Ошибочный код Описание ошибки
101 Ошибка. Неверное имя пользователя или пароль.
102 Этот аккаунт еще не активирован.
103 Отсутствует обязательный параметр
104 Неверный запрос. GET, POST и необработанных данных JSON не найдено. Если вы пытаетесь отправить JSON, пожалуйста, проверьте, правильность кодирововки.
105 Неизвестная функция
106 Доступ запрещен
107 Общая ошибка API
108 Неверная структура запроса
109 Не достаточно кредита
Мы что-то пропустили? У Вас есть вопросы? У Вас есть совет или что-то, что мы могли бы здесь добавить? Если так, свяжитесь с нами!
© My-Cool-Webservices Ltd. 2008-2014
Deutsch
English
Español
Français
Nederlands
Polski
Português
繁体中文