potoksms-logo

call 8 (800) 234 21 56

Звонок бесплатный для всех операторов на территории России.
call 8 (800) 234 21 56

API - рассылка СМС

1. Протокол HTTP

1.1. Передача исходящего СМС-трафика (СМС-рассылка)

1.2. Получение статусов (отчетов о доставке) отправленных СМС-сообщений

1.3. Автоматическое получение информации о состоянии баланса

1.4. Передача исходящего голосового трафика (голосовая рассылка, автоматический обзвон)

1.5. Прием входящего СМС-трафика (короткие и федеральные номера)

2. Протокол SMPP

3. Протокол SMTP (email2sms)

4. Отправка SMS-сообщений из 1С



1. Протокол HTTP

1.1. Передача исходящего SMS-трафика (SMS-рассылка)

Отправить SMS-сообщение абоненту Вы можете HTTP GET-запросом на наш скрипт.
Например, чтобы отправить сообщение с текстом "test message" абоненту +79260000000 с подписью (отправителем) "Magazin", Вы должны будете вызвать такой адрес:

https://our.server/somescript1?login=...&password=...&service=...&space_force=1&space=Magazin&subno=%2B79260000000&text=test+message

, где:
  • login, password, service, space_force – фиксированные (login, password, service мы Вам предоставим);
  • space - подпись смс "от кого", принимает до 11 символов латинского алфавита, некоторые знаки препинания, цифры;
  • subno - номер абонента в формате +7xxxxxxxxxx, URL-encoded;
  • text - текст сообщения в кодировке UTF8, URL-encoded

1.2. Получение статусов (отчетов о доставке) отправленных СМС-сообщений

Для получения отчетов о доставке нужно во время отправки SMS добавить еще два GET-параметра к вызову скрипта somescript1:
1) dlr-mask=3;
2) dlr-url - параметр, указывающий, какой именно скрипт будет вызван HTTP GET-запросом при получении от оператора отчета о доставке. В этом параметре поддерживаются переменные %d и %A, обозначающие соответственно тип отчета и его текст.
Пример: Вы отправляете SMS-сообщение, которое в Вашей внутренней базе имеет идентификатор 12345 и хотите получить про нее отчет о доставке. Тогда dlr-url может быть например таким:

http://your.server/dlr_receiver?id=12345&comment=SMS+TO+MYSELF&status=%d&text=%A


Предположим, что SMS-центр сгенерировал отчет, что SMS-сообщение доставлено до абонента, и в тексте отчета написано "Delivered at 12:25". Тогда будет выполнен такой HTTP GET запрос:

http://your.server/dlr_receiver?id=12345&comment=SMS+TO+MYSELF&status=1&text=Delivered+at+12%3A25


То есть адрес, который будет вызван, составляется так: берется строка, которую вы дали в параметре dlr-url, заменяется %d на тип отчета (1 - отчёт о доставке, 2 - отчёт о недоставке), %A на текст отчета, остальное оставляется без изменений.

1.3. Автоматическое получение информации о состоянии баланса

Проверить состояния вашего баланса вы можете HTTP GET запросом на наш скрипт:

https://our.server/somescript2?login=...&password=...service=...


Параметры login, password мы Вам предоставим.

1.4. Передача исходящего голосового трафика (голосовая рассылка, автоматический обзвон)

Отправка звонка осуществляется вызовом нашего скрипта http://our.server/somescript3 методом HTTP GET. GET-параметры:
1) Обязательные GET-параметры:
  • subno – номер абонента, на который будет совершён звонок, в международном формате. Пример subno=79260000000
  • file - содержит ссылку на файл, который будет проигран абоненту в случае успешного дозвона. Файл должен быть в формате .mp3 или .wav, при этом само название файла по ссылке должно иметь соответствующее расширение. Пример file=http%3A%2F%2Fsome.server%2Ftest1.wav.
    ВАЖНО: применяется кеширование звуковых файлов. Во время первого звонка с указанным файлом, скрипт скачивает содержимое ссылки и конвертирует его в формат телефонной линии. При следующем звонке с такой же ссылкой на файл содержимое заново скачиваться не будет, а будет использоваться то, которое было получено при первом звонке. Важно: при кешировании учитывается только ссылка на файл, так что если Вам необходимо заменить файл, недопустимо выкладывать новое содержимое по уже использованному ранее адресу, нужно изменить и адрес звукового файла. Также рекомендуется во избежание накладок перед массовыми рассылками инициировать сначала звонок на один номер телефона, дождаться, когда скачается файл и придёт звонок на телефон и убедиться, что в телефонном аппарате файл звучит именно так, как ожидается. И только после этого инициировать звонки на остальные телефоны с использованием данного файла.
  • login, password – фиксированные (мы их Вам предоставим)
2) Необязательные GET-параметры:
  • callerid - содержит российский национальный номер, который будет использоваться как номер отправителя. 10 цифр. Если номер не указан, то используется наш фиксированный номер, не имеющий обратной маршрутизации (на него нельзя перезвонить). Пример callerid=4990000000.
  • good_url1 - содержит URL (url-encoded), который будет вызван в случае успешного дозвона до абонента. Пример good_url1=http%3A%2F%2Fyour.server%2F%3Fcallid%3D123. URL будет вызван в начале звонка. Этот метод полезен для приложений, в которых требуется синхронизация дозвона до абонента и каких-то событий на сайте, например с помощью него можно реализовать начало воспроизведения ролика на сайте абоненту одновременно с ответом абонента на звонок. Для учёта статистики звонков данный метод менее полезен, и лучше пользоваться good_url2, который вызывается не в начале звонка, а после завершения. ВАЖНО: URL вызывается после ответа абонента на звонок и до начала воспроизведения файла. Если скрипт выдаёт ответ не сразу, а с какой-то задержкой, то на столько же времени будет задержано начало воспроизведения звукового файла абоненту, и на это же время будет в результате увеличена длительность звонка.
  • good_url2 - аналогично good_url1, но будет вызван не в начале звонка, а после завершения успешного звонка. Также в этом URL, как отражено в примере можно указать последовательность символов "%s", которая перед вызовом скрипта будет заменена на итоговую длительность звонка в секундах. Пример good_url2=http%3A%2F%2Fyour.server%2F%3Fcallid%3D123%26duration%3D%25s
  • bad_url - аналогично good_url1, но будет вызван в случае недозвона до абонента. Пример bad_url=http%3A%2F%2Fya.ru%2F%3Fcallid%3D123.

В ответ скрипт возвращает результат принятия заявки. Возможные варианты:
1) Если заявка на звонок принята, то скрипт возвращает ответ HTTP 200 с телом ответа "ok" (два байта).
2) Если заявка на звонок не принята, то скрипт возвращает ответ HTTP 200 с телом ответа, начинающегося со слова "error" и опционально кодом ошибки. По состоянию на сегодня список возможных ошибок таков:
"error 0" - throttling error. Система не может совершить звонок в указанный момент из-за недостаточности свободных линий. Следует повторить попытку инициации звонка позже
"error 1" - указаны неверный login или password. Следует обратиться к менеджеру для уточнения логина и пароля.
"error 2" - невозможно совершить звонок на указанный номер, направление закрыто. Следует обратиться к менеджеру с просьбой открыть данное направление
"error 3" - не указана ссылка на файл, либо файл по ссылке имеет недопустимый формат
Пример инициации звонка абоненту 79260000000 и проигрывания ему файла http://your.server/test1.wav

http://our.server/somescript3?login=...&password=...&subno=79260000000&callerid=4990000000&file=http%3A%2F%2Fyour.server%2Ftest1.wav

1.5. Прием входящего SMS-трафика (короткие и федеральные номера)

При получении SMS-сообщения от абонента мы делаем HTTP GET запрос на Ваш скрипт. В параметрах может быть передана следующая информация о сообщении:
  • subno - номер абонента, например +79260000000
  • scode – короткий/федеральный номер, например 5533
  • keyword - ключевое слово (см.ниже)
  • text - текст сообщения без ключевого слова
  • smsid - уникальный идентификатор сообщения, VARCHAR(48)
  • text_full - полный исходный текст сообщения без изменений
Например, абонент +79260000000 прислал SMS с текстом "Golos 2" на короткий номер 5533. Вы получите такой GET-запрос:

http://your.server/your_script?subno=%2B79260000000&scode=5533&keyword=GOLOS&text=2&text_full=Golos+2&smsid=SOME_UNIQUE_SMSID_HERE


Если Ваша система вернёт HTTP ошибку, например HTTP 500, или же просто Ваш сервер окажется недоступным, то запрос будет периодически повторяться.
Также у Вас будет возможность отправлять ответное SMS-сообщение абоненту. Это можно сделать двумя способами:
1) Ваш скрипт при получении SMS от абонента может напечатать в ответ какой-либо текст, и наша система может выслать этот текст абоненту в виде ответного SMS. Если Ваш скрипт не напечатает ничего - абоненту не будет выслан ответ. Если Вы захотите использовать такую возможность ответа - сообщите нам об этом при подключении.
2) Вы можете отправить ответ позже, для этого вы должны будете сделать GET-запрос на наш скрипт, передав туда два параметра:
  • smsid=ORIGINAL_SMSID_HERE (smsid сообщения абонента, на которое вы высылаете ответ)
  • text=TEXT_IN_UTF8 (текст ответа)

2. Протокол SMPP

Если Ваша платформа поддерживает отправку SMS-сообщений по специализированному протоколу SMPP, используйте следующие параметры подключения:
  • host: (мы Вам предоставим)
  • port: (мы Вам предоставим)
  • system_type: VMA
  • system_id: (мы Вам предоставим)
  • password:м (мы Вам предоставим)

3. Протокол SMTP (email2sms)

Отправить SMS-сообщение абоненту Вы можете отправив электронное письмо определённого содержания на адрес email. Например, чтобы отправить сообщение с текстом "test message" абоненту +79260000000 с подписью (отправителем) "Magazin", Вы должны будете отправить такое письмо: From: "Magazin" <youraddress@your.domain> To: "79260000000" <email> Subject: service:login:password Body: test message, где
  • в имени отправителя содержится подпись смс "от кого", принимает до 11 символов латинского алфавита, некоторые знаки препинания, цифры;
  • адрес отправителя - любой Ваш корректный email адрес;
  • имя получателя - номер абонента в формате 7xxxxxxxxxx;
  • адрес получателя - email;
  • тема письма - фиксированная, служит для авторизации (Параметры login, password мы Вам предоставим);
  • тело письма - текст сообщения

4. Отправка SMS-сообщений из 1С

Для осуществления рассылок из 1С необходимо:
1) Скачать модуль, соответствующий Вашей версии ниже;
2) Внедрить модуль соответственно инструкции, приложенной к модулю.
Необходимые для интеграции данные:
Service, login, password (мы Вам предоставим)
Модуль для 1С 7.7
Модуль для 1С 8.2
Модуль для 1С 8.3