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 支持帮助中心，如果您找不到问题的答案，请提交支持票证。

如果您在库中发现了错误或希望添加新功能，请继续针对此存储库提出问题或拉取请求！