twilio ruby

twilioルビー

ドキュメント

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'

Rubygems 経由でtwilio-ruby手動でインストールするには、単に gem install を実行します。

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 のグローバル インフラストラクチャを利用するには、クライアントのターゲット リージョンおよび/またはエッジを指定します。

 # 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'
)

SMSを送信する

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

SMS メッセージをリストする

 @client . messages . list ( limit : 20 )

Sid による 1 つの 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」に設定して「logger」インスタンスをクライアントに渡します。

 @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 が 400 または 500 レベルの HTTP 応答を返した場合、 twilio-rubyライブラリはTwilio::REST::RestErrorをスローします。 API 操作中の 400 レベルのエラー ( “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

Wiki の「機能」セクションには、もう少し詳細なドキュメントがあります。

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とそのそれぞれのtwilio/twilio-ruby Docker イメージは、現在 Twilio によってテスト目的のみに使用されています。

助けを求める

ライブラリのインストールまたは使用についてサポートが必要な場合は、まず Twilio サポート ヘルプ センターを確認し、質問に対する答えが見つからない場合はサポート チケットを提出してください。

ライブラリでバグを見つけた場合、または新しい機能を追加したい場合は、このリポジトリに対して問題を開くかプル リクエストをオープンしてください。