twilio ruby

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'

要透過 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

測試您的安裝

為了確保安裝成功，請嘗試向自己發送一條短信，如下所示：

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

傳簡訊

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

列出您的簡訊

 @client . messages . list ( limit : 20 )

透過 Sid 取得單一 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

啟用調試日誌記錄

為了啟用偵錯日誌記錄，請將“logger”實例傳遞給客戶端，並將等級至少設為“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 傳回 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使用 Faraday 發出 HTTP 請求。您可以告訴Twilio::REST::Client使用任何 Faraday 適配器，如下所示：

 @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 >

Docker 映像

此儲存庫中存在的Dockerfile及其各自的twilio/twilio-ruby Docker 映像目前僅由 Twilio 用於測試目的。

尋求協助

如果您需要安裝或使用該程式庫的協助，請先查看 Twilio 支援幫助中心，如果您找不到問題的答案，請提交支援票證。

如果您在庫中發現了錯誤或希望添加新功能，請繼續針對此儲存庫提出問題或拉取請求！