twilio ruby

twilio-rubi

Documentação

A documentação da API Twilio pode ser encontrada aqui.

Os lançamentos individuais aqui.

Versões

twilio-ruby usa uma versão modificada do Versionamento Semântico para todas as alterações. Consulte este documento para obter detalhes.

Versões Ruby suportadas

Esta biblioteca oferece suporte às seguintes implementações Ruby:

• Rubi 2.4

• Rubi 2.5

• Rubi 2.6

• Rubi 2.7

• Rubi 3.0

• Rubi 3.1

• Rubi 3.2

• JRuby 9.2

• JRuby 9.3

• JRuby 9.4

Migrando do 5.x

Guia de atualização

Instalação

Para instalar usando o Bundler, pegue a versão estável mais recente:

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

Para instalar manualmente twilio-ruby via Rubygems simplesmente gem install:

gem install twilio-ruby -v 7.3.6

Para compilar e instalar você mesmo o branch de desenvolvimento a partir da fonte mais recente:

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

Informações Se a linha de comando exibir uma mensagem de erro dizendo Permissão negada, tente executar os comandos acima com sudo.

Por exemplo: sudo gem install twilio-ruby

Teste sua instalação

Para ter certeza de que a instalação foi bem-sucedida, tente enviar para si mesmo uma mensagem SMS, como esta:

 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

Aviso Não há problema em codificar suas credenciais ao testar localmente, mas você deve usar variáveis ​​de ambiente para mantê-las secretas antes de confirmar qualquer código ou implantá-lo em produção. Confira Como definir variáveis ​​de ambiente para obter mais informações.

Uso

Autenticar o cliente

 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

Use uma chave de 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

Especifique uma região e/ou borda

Para aproveitar a infraestrutura global da Twilio, especifique a região e/ou borda de destino do cliente:

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

Isso resultará na transformação do hostname de api.twilio.com para api.sydney.au1.twilio.com .

Faça uma chamada

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

Envie um SMS

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

Liste suas mensagens SMS

 @client . messages . list ( limit : 20 )

Obtenha uma única mensagem SMS de Sid

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

Iterar através de registros

A biblioteca lida automaticamente com a paginação para você. Coleções, como calls e messages , possuem métodos list e fluxo que paginam nos bastidores. Com list e stream , você pode especificar o número de registros que deseja receber ( limit ) e o tamanho máximo que deseja que cada busca de página tenha ( page_size ). A biblioteca cuidará da tarefa para você.

list busca avidamente todos os registros e os retorna como uma lista, enquanto stream retorna um enumerador e recupera preguiçosamente páginas de registros conforme você itera na coleção. Você também pode paginar manualmente usando o método page .

Para obter mais informações sobre esses métodos, consulte os documentos da biblioteca gerados automaticamente.

 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

Habilitar registro de depuração

Para ativar o log de depuração, passe uma instância de 'logger' para o cliente com o nível definido como pelo menos '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

Lidar com exceções {#exceptions}

Se a API do Twilio retornar uma resposta HTTP de nível 400 ou 500, a biblioteca twilio-ruby lançará um Twilio::REST::RestError . Erros de nível 400 são normais durante a operação da API ( “Invalid number” , “Cannot deliver SMS to that number” , por exemplo) e devem ser tratados adequadamente.

 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

Depurar solicitações de API

Para ajudar na depuração, a biblioteca permite acessar os objetos de solicitação e resposta subjacentes. Esse recurso está integrado ao cliente HTTP padrão fornecido com a biblioteca.

Por exemplo, você pode recuperar o código de status da última resposta assim:

 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

Personalize seu cliente HTTP

twilio-ruby usa Faraday para fazer solicitações HTTP. Você pode dizer Twilio::REST::Client para usar qualquer um dos adaptadores Faraday assim:

 @client . http_client . adapter = :typhoeus

Para usar um cliente HTTP personalizado com esta biblioteca auxiliar, consulte o exemplo avançado de como fazer isso.

Para aplicar personalizações como middleware, você pode usar o método configure_connection assim:

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

Comece com tokens de capacidade do cliente

Se você precisar apenas gerar um token de capacidade para uso com o Twilio Client, poderá fazer o seguinte:

 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

Há um documento um pouco mais detalhado na seção Capacidade do wiki.

Gerar TwiML

Para controlar chamadas telefônicas, seu aplicativo precisa gerar TwiML.

Você pode construir uma resposta TwiML assim:

 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

Isso imprimirá o seguinte (exceto o espaço em branco):

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

Imagem Docker

O Dockerfile presente neste repositório e sua respectiva imagem Docker twilio/twilio-ruby são usados ​​atualmente pelo Twilio apenas para fins de teste.

Obtendo ajuda

Se precisar de ajuda para instalar ou usar a biblioteca, verifique primeiro o Centro de Ajuda de Suporte da Twilio e registre um tíquete de suporte se não encontrar uma resposta para sua pergunta.

Se você encontrou um bug na biblioteca ou gostaria de adicionar novos recursos, vá em frente e abra problemas ou receba solicitações neste repositório!