twilio ruby

твилио-рубиновый

Документация

Документацию по Twilio API можно найти здесь.

Отдельные релизы здесь.

Версии

twilio-ruby использует модифицированную версию семантического управления версиями для всех изменений. Подробности смотрите в этом документе.

Поддерживаемые версии Ruby

Эта библиотека поддерживает следующие реализации Ruby:

• Рубин 2.4

• Рубин 2.5

• Рубин 2.6

• Рубин 2.7

• Рубин 3.0

• Рубин 3.1

• Рубин 3.2

• JRuby 9.2

• JRuby 9.3

• JRuby 9.4

Миграция с версии 5.x

Руководство по обновлению

Установка

Для установки с помощью Bundler скачайте последнюю стабильную версию:

 gem 'twilio-ruby' , '~> 7.3.6'

Чтобы вручную установить twilio-ruby через Rubygems, просто установите gem:

gem install twilio-ruby -v 7.3.6

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

git clone [email protected]:twilio/twilio-ruby.git
cd twilio-ruby
make install

Информация Если в командной строке отображается сообщение об ошибке «Разрешение запрещено», попробуйте выполнить приведенные выше команды с помощью sudo.

Например: sudo gem install twilio-ruby

Проверьте свою установку

Чтобы убедиться, что установка прошла успешно, попробуйте отправить себе SMS-сообщение, например:

 require "twilio-ruby"

# Your Account SID and Auth Token from console.twilio.com
account_sid = "ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX"
auth_token = "your_auth_token"

@client = Twilio :: REST :: Client . new account_sid , auth_token
message = @client . messages . create (
  body : "Hello from Ruby" ,
  to : "[phone]" ,  # Text this number
  from : "[phone]" , # From a valid Twilio number
)

puts message . sid

Предупреждение. При локальном тестировании можно жестко запрограммировать свои учетные данные, но вам следует использовать переменные среды, чтобы сохранить их в секрете перед фиксацией какого-либо кода или развертыванием в рабочей среде. Дополнительную информацию см. в разделе «Как установить переменные среды».

Использование

Аутентификация клиента

 require 'twilio-ruby'

# Your Account SID and Auth Token from console.twilio.com
account_sid = 'ACxxxxxxxxxxxxxxxxxxxxxxxxxxxxx'
auth_token = 'yyyyyyyyyyyyyyyyyyyyyyyyyyyyyyy'

# Initialize the Twilio Client with your credentials
@client = Twilio :: REST :: Client . new account_sid , auth_token

Используйте ключ API

 require 'twilio-ruby'

# Your Account SID from console.twilio.com
account_sid = 'ACxxxxxxxxxxxxxxxxxxxxxxxxxxxxx'
# API Key from twilio.com/console/project/api-keys
api_key_sid = 'zzzzzzzzzzzzzzzzzzzzzz'
api_key_secret = 'yyyyyyyyyyyyyyyyyyyyyyyyyyyyyyy'

# set up a client to talk to the Twilio REST API using an API Key
@client = Twilio :: REST :: Client . new api_key_sid , api_key_secret , account_sid

Укажите регион и/или край

Чтобы воспользоваться преимуществами глобальной инфраструктуры Twilio, укажите целевой регион и/или Edge для клиента:

 # set up a client to talk to the Twilio REST API over a specific region and edge
@client = Twilio :: REST :: Client . new account_sid , auth_token , nil , 'au1'
@client . edge = 'sydney'

# you may also specify the region and/or edge after client creation
@client = Twilio :: REST :: Client . new account_sid , auth_token
@client . region = 'au1'
@client . edge = 'sydney'

Это приведет к преобразованию hostname с api.twilio.com на api.sydney.au1.twilio.com .

Позвонить

 @client . calls . create (
  from : '[phone]' ,
  to : '[phone]' ,
  url : 'http://example.com'
)

Отправить СМС

 @client . messages . create (
  from : '[phone]' ,
  to : '[phone]' ,
  body : 'Hey there!'
)

Список ваших SMS-сообщений

 @client . messages . list ( limit : 20 )

Получить одно SMS-сообщение от Сида

 # put the message sid you want to retrieve here:
message_sid = 'SMxxxxxxxxxxxxxxxxxxxxxxxxxxxxx'
@client . messages ( message_sid ) . fetch

Перебирать записи

Библиотека автоматически обрабатывает подкачку за вас. Коллекции, такие как calls и messages , имеют методы list и потоков, которые просматриваются внутри. Как с помощью list , так и с stream вы можете указать количество записей, которые вы хотите получить ( limit ), и максимальный размер, который вы хотите получить для каждой страницы ( page_size ). Библиотека выполнит эту задачу за вас.

list охотно извлекает все записи и возвращает их в виде списка, тогда как stream возвращает перечислитель и лениво извлекает страницы записей при переборе коллекции. Вы также можете выполнить страницу вручную, используя метод page .

Для получения дополнительной информации об этих методах просмотрите автоматически созданную документацию библиотеки.

 require 'twilio-ruby'

account_sid = 'ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX'
auth_token = 'your_auth_token'

@client = Twilio :: REST :: Client . new ( account_sid , auth_token )

@client . calls . list
       . each do | call |
         puts call . direction
       end

Включить ведение журнала отладки

Чтобы включить ведение журнала отладки, передайте экземпляр «регистратора» клиенту с уровнем, установленным как минимум «DEBUG».

 @client = Twilio :: REST :: Client . new account_sid , auth_token
myLogger = Logger . new ( STDOUT )
myLogger . level = Logger :: DEBUG
@client . logger = myLogger

@client = Twilio :: REST :: Client . new account_sid , auth_token
myLogger = Logger . new ( 'my_log.log' )
myLogger . level = Logger :: DEBUG
@client . logger = myLogger

Обработка исключений {#Exceptions}

Если Twilio API возвращает HTTP-ответ уровня 400 или 500, библиотека twilio-ruby выдаст Twilio::REST::RestError . Ошибки уровня 400 являются нормальными во время работы API (например, “Invalid number” , “Cannot deliver SMS to that number” ) и должны обрабатываться соответствующим образом.

 require 'twilio-ruby'

account_sid = 'ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX'
auth_token = 'your_auth_token'

@client = Twilio :: REST :: Client . new account_sid , auth_token

begin
  messages = @client . messages . list ( limit : 20 )
rescue Twilio :: REST :: RestError => e
  puts e . message
end

Отладка запросов API

Для облегчения отладки библиотека позволяет получить доступ к базовым объектам запросов и ответов. Эта возможность встроена в HTTP-клиент по умолчанию, который поставляется с библиотекой.

Например, вы можете получить код состояния последнего ответа следующим образом:

 require 'rubygems' # Not necessary with ruby 1.9 but included for completeness
require 'twilio-ruby'

# Your Account SID and Auth Token from console.twilio.com
account_sid = 'ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX'
auth_token = 'your_auth_token'

@client = Twilio :: REST :: Client . new ( account_sid , auth_token )

@message = @client . messages . create (
  to : '[phone]' ,
  from : '[phone]' ,
  body : 'Ahoy!'
)

# Retrieve the status code of the last response from the HTTP client
puts @client . http_client . last_response . status_code

Настройте свой HTTP-клиент

twilio-ruby использует Фарадей для выполнения HTTP-запросов. Вы можете указать Twilio::REST::Client использовать любой из адаптеров Фарадея следующим образом:

 @client . http_client . adapter = :typhoeus

Чтобы использовать собственный HTTP-клиент с этой вспомогательной библиотекой, ознакомьтесь с расширенным примером того, как это сделать.

Чтобы применить настройки, такие как промежуточное программное обеспечение, вы можете использовать метод configure_connection следующим образом:

 @client . http_client . configure_connection do | faraday |
  faraday . use SomeMiddleware
end

Начало работы с токенами возможностей клиента

Если вам просто нужно создать токен возможностей для использования с клиентом Twilio, вы можете сделать это:

 require 'twilio-ruby'

# put your own account credentials here:
account_sid = 'ACxxxxxxxxxxxxxxxxxxxxxxxxxxxxx'
auth_token = 'yyyyyyyyyyyyyyyyyyyyyyyyyyyyyyy'

# set up
capability = Twilio :: JWT :: ClientCapability . new account_sid , auth_token

# allow outgoing calls to an application
outgoing_scope = Twilio :: JWT :: ClientCapability :: OutgoingClientScope . new 'AP11111111111111111111111111111111'
capability . add_scope ( outgoing_scope )

# allow incoming calls to 'andrew'
incoming_scope = Twilio :: JWT :: ClientCapability :: IncomingClientScope . new 'andrew'
capability . add_scope ( incoming_scope )

# generate the token string
@token = capability . to_s

В разделе «Возможности» вики есть немного более подробный документ.

Создать TwiML

Для управления телефонными звонками вашему приложению необходимо выводить TwiML.

Вы можете создать ответ TwiML следующим образом:

 require 'twilio-ruby'

response = Twilio :: TwiML :: VoiceResponse . new do | r |
  r . say ( message : 'hello there' , voice : 'alice' )
  r . dial ( caller_id : '[phone]' ) do | d |
    d . client 'jenny'
  end
end

# print the result
puts response . to_s

Это напечатает следующее (кроме пробелов):

xml version = " 1.0 " encoding = " UTF-8 " ?>
< Response >
  < Say voice = " alice " >hello thereSay >
  < Dial callerId = " [phone] " >
    < Client >jennyClient >
  Dial >
Response >

Докер-образ

Dockerfile присутствующий в этом репозитории, и соответствующий ему образ Docker twilio/twilio-ruby в настоящее время используются Twilio только в целях тестирования.

Получение помощи

Если вам нужна помощь в установке или использовании библиотеки, сначала посетите Справочный центр поддержки Twilio и отправьте запрос в службу поддержки, если вы не нашли ответа на свой вопрос.

Если вместо этого вы обнаружили ошибку в библиотеке или хотите добавить новые функции, открывайте проблемы или запросы на извлечение в этом репозитории!