sms-pilot-api-v1

SmsPilot API v1 client

Simple wrapper around SMS pilot API v1. Version 1 because it returns more data within its standard response.

Installation

from RubyGems:

gem "sms-pilot-api-v1"

from GitHub:

gem "sms-pilot-api-v1", git: "https://github.com/sergeypedan/sms-pilot-api-v1.git"

Playground

Test sending SMS from console with a test API key (find it at the end of this page):

cd $(bundle info sms-pilot-api-v1 --path)
bin/console

Usage

Initialize

require "sms_pilot"

key = "XXXXXXXXXXXXYYYYYYYYYYYYZZZZZZZZXXXXXXXXXXXXYYYYYYYYYYYYZZZZZZZZ"

client = SmsPilot::Client.new(api_key: key)
client = SmsPilot::Client.new(api_key: key, locale: :en) # Available locales are [:en, :ru]

Method documentation at RubyDoc.

Before sending

There are a bunch of methods describing the state of affairs:

client.api_key          # => "YOUR API KEY"
client.balance          # => nil
client.broadcast_id     # => nil
client.error            # => nil
client.phone            # => nil
client.rejected?        # => false
client.response_body    # => nil
client.response_data    # => {}
client.response_headers # => {}
client.response_status  # => nil
client.sender_blocked?  # => false
client.sms_cost         # => nil
client.sms_sent?        # => false
client.sms_status       # => nil
client.url              # => nil

before the request is sent they return obvious nils or empty structures; after the request they are populated with data.

See structured documentation for those methods at RubyDoc.

Sending SMS

client.send_sms("[phone]", "Привет, мир!")
client.send_sms("[phone]", "Привет, мир!", "ФССПРФ")
# => true

Returns result of sms_sent?, so it’s either true or false.

Method documentation at RubyDoc.

Sending SMS succeeded

client.api_key          # => "YOUR API KEY"
client.balance          # => 20006.97
client.broadcast_id     # => 10000
client.error            # => nil
client.phone            # => "79021234567"
client.rejected?        # => false
client.response_body    # => "{\"send\":[{\"server_id\":\"10000\",\"phone\":\"79021234567\",\"price\":\"1.68\",\"status\":\"0\"}],\"balance\":\"20006.97\",\"cost\":\"1.68\"}"
client.response_data    # => {"send"=>[{"server_id"=>"10000", "phone"=>"79021234567", "price"=>"1.68", "status"=>"0"}], "balance"=>"20006.97", "cost"=>"1.68"}
client.response_headers # => {"Server"=>"nginx", "Date"=>"Thu, 06 May 2021 04:52:58 GMT", "Content-Type"=>"application/json; charset=utf-8", "Content-Length"=>"179", "Connection"=>"close", "Access-Control-Allow-Origin"=>"*"}
client.response_status  # => 200
client.sender_blocked?  # => false
client.sms_cost         # => 1.68
client.sms_sent?        # => true
client.sms_status       # => 1
client.url              # => "https://smspilot.ru/api.php?apikey=1234567890&format=json&send=%D0%9F%D1%80%D0%B8%D0%B2%D0%B5%D1%82%2C+%D0%BC%D0%B8%D1%80%21&to=79021234567"

Sending SMS failed (but HTTP request succeeded)

client.api_key          # => "YOUR API KEY"
client.balance          # => nil
client.broadcast_id     # => nil
client.error            # => "Неправильный API-ключ (см. настройки API в личном кабинете) (код ошибки: 101)"
client.phone            # => "79021234567"
client.rejected?        # => true
client.response_body    # => "{\"error\":{\"code\":\"101\",\"description\":\"APIKEY is invalid\",\"description_ru\":\"Неправильный API-ключ (см. настройки API в личном кабинете)\"}}"
client.response_data    # => {"error"=>{"code"=>"101", "description"=>"APIKEY is invalid", "description_ru"=>"Неправильный API-ключ (см. настройки API в личном кабинете)"}}
client.response_headers # => {"Server"=>"nginx", "Date"=>"Thu, 06 May 2021 04:52:58 GMT", "Content-Type"=>"application/json; charset=utf-8", "Content-Length"=>"179", "Connection"=>"close", "Access-Control-Allow-Origin"=>"*"}
client.response_status  # => 200
client.sender_blocked?  # => false
client.sms_cost         # => nil
client.sms_sent?        # => false
client.sms_status       # => nil
client.url              # => "https://smspilot.ru/api.php?apikey=1234567890&format=json&send=%D0%9F%D1%80%D0%B8%D0%B2%D0%B5%D1%82%2C+%D0%BC%D0%B8%D1%80%21&to=79021234567"

HTTP request failed

client.api_key          # => "YOUR API KEY"
client.balance          # => nil
client.broadcast_id     # => nil
client.error            # => "HTTP request failed with code 404"
client.phone            # => "79021234567"
client.rejected?        # => false
client.response_body    # => "<html>\r\n<head><title>404 Not Found</title></head>\r\n<body>\r\n<center><h1>404 Not Found</h1></center>\r\n<hr><center>nginx</center>\r\n</body>\r\n</html>\r\n"
client.response_data    # => {}
client.response_headers # => {"Server"=>"nginx", "Date"=>"Thu, 06 May 2021 05:30:23 GMT", "Content-Type"=>"text/html", "Content-Length"=>"146", "Connection"=>"close"}
client.response_status  # => 404
client.sender_blocked?  # => false
client.sms_cost         # => nil
client.sms_sent?        # => false
client.sms_status       # => nil
client.url              # => "https://smspilot.ru/api.php?apikey=1234567890&format=json&send=%D0%9F%D1%80%D0%B8%D0%B2%D0%B5%D1%82%2C+%D0%BC%D0%B8%D1%80%21&to=79021234567"

SMS pilot API docs

• Web version — см. вкладку PHP, в остальных ничего нет
• PDF version — тут намного подробнее
• API error code

Test API key

https://smspilot.ru/apikey.php

"XXXXXXXXXXXXYYYYYYYYYYYYZZZZZZZZXXXXXXXXXXXXYYYYYYYYYYYYZZZZZZZZ"

API response examples

SMS sent:

{
  "balance": "11908.50",
  "cost": "1.68",
  "send": [
    { "server_id": "10000", "phone": "79021234567", "price": "1.68", "status": "0" }
  ]
}

SMS rejected:

{
  "error": {
    "code": "400",
    "description": "User not found",
    "description_ru": "Пользователь не найден"
  }
}

Documentation

See structured documentation at RubyDoc.

Roadmap

1. Switch to POST to escape 1024 symbolos GET request limit
2. Support passing sender to the API
3. Switch to result object pattern
4. Проверка статусов SMS
5. Проверка баланса
6. Информация о пользователе