twilio ruby

twilio-rubí

Documentación

La documentación de la API de Twilio se puede encontrar aquí.

Los lanzamientos individuales aquí.

Versiones

twilio-ruby utiliza una versión modificada de Semantic Versioning para todos los cambios. Consulte este documento para obtener más detalles.

Versiones de Ruby compatibles

Esta biblioteca admite las siguientes implementaciones de Ruby:

• Rubí 2.4

• Rubí 2.5

• Rubí 2.6

• Rubí 2.7

• Rubí 3.0

• Rubí 3.1

• Rubí 3.2

• JRuby 9.2

• JRuby 9.3

• JRuby 9.4

Migrando desde 5.x

Guía de actualización

Instalación

Para instalar usando Bundler, obtenga la última versión estable:

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

Para instalar manualmente twilio-ruby a través de Rubygems, simplemente instale gema:

gem install twilio-ruby -v 7.3.6

Para compilar e instalar la rama de desarrollo usted mismo desde la fuente más reciente:

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

Información Si la línea de comando le muestra un mensaje de error que dice Permiso denegado, intente ejecutar los comandos anteriores con sudo.

Por ejemplo: sudo gem install twilio-ruby

Pruebe su instalación

Para asegurarse de que la instalación se haya realizado correctamente, intente enviarse un mensaje SMS como este:

 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

Advertencia Está bien codificar sus credenciales cuando realice pruebas localmente, pero debe usar variables de entorno para mantenerlas en secreto antes de enviar cualquier código o implementarlo en producción. Consulte Cómo configurar variables de entorno para obtener más información.

Uso

Autenticar al 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

Utilice una clave 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

Especificar una región y/o borde

Para aprovechar la infraestructura global de Twilio, especifique la región de destino y/o el borde para el 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'

Esto hará que el hostname se transforme de api.twilio.com a api.sydney.au1.twilio.com .

hacer una llamada

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

Enviar un SMS

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

Lista tus mensajes SMS

 @client . messages . list ( limit : 20 )

Obtener un único mensaje SMS de Sid

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

Iterar a través de registros

La biblioteca maneja automáticamente la paginación por usted. Las colecciones, como calls y messages , tienen métodos list y transmisión que paginan bajo el capó. Tanto con list como stream , puede especificar la cantidad de registros que desea recibir ( limit ) y el tamaño máximo que desea que tenga cada página recuperada ( page_size ). La biblioteca se encargará de la tarea por usted.

list busca con entusiasmo todos los registros y los devuelve como una lista, mientras que stream devuelve un enumerador y recupera perezosamente páginas de registros a medida que itera sobre la colección. También puede paginar manualmente usando el método page .

Para obtener más información sobre estos métodos, consulte los documentos de la biblioteca generados automáticamente.

 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 el registro de depuración

Para habilitar el registro de depuración, pase una instancia de 'registrador' al cliente con el nivel establecido al menos en '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

Manejar excepciones {#exceptions}

Si la API de Twilio devuelve una respuesta HTTP de nivel 400 o 500, la biblioteca twilio-ruby generará un Twilio::REST::RestError . Los errores de nivel 400 son normales durante el funcionamiento de la API ( “Invalid number” , “Cannot deliver SMS to that number” , por ejemplo) y deben manejarse adecuadamente.

 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

Solicitudes de API de depuración

Para ayudar con la depuración, la biblioteca le permite acceder a los objetos de solicitud y respuesta subyacentes. Esta capacidad está integrada en el cliente HTTP predeterminado que se envía con la biblioteca.

Por ejemplo, puedes recuperar el código de estado de la última respuesta de esta manera:

 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

Personaliza tu cliente HTTP

twilio-ruby usa Faraday para realizar solicitudes HTTP. Puede decirle Twilio::REST::Client que use cualquiera de los adaptadores de Faraday de esta manera:

 @client . http_client . adapter = :typhoeus

Para utilizar un cliente HTTP personalizado con esta biblioteca auxiliar, consulte el ejemplo avanzado de cómo hacerlo.

Para aplicar personalizaciones como middleware, puede utilizar el método configure_connection de esta manera:

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

Comience con los tokens de capacidad del cliente

Si solo necesita generar un token de capacidad para usarlo con Twilio Client, puede hacer esto:

 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

Hay un documento un poco más detallado en la sección Capacidad de la wiki.

Generar TwiML

Para controlar las llamadas telefónicas, su aplicación necesita generar TwiML.

Puedes construir una respuesta TwiML como esta:

 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

Esto imprimirá lo siguiente (excepto el espacio en blanco):

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

Imagen acoplable

Actualmente, Twilio utiliza el Dockerfile presente en este repositorio y su respectiva imagen de Docker twilio/twilio-ruby solo con fines de prueba.

Obteniendo ayuda

Si necesita ayuda para instalar o usar la biblioteca, consulte primero el Centro de ayuda de soporte de Twilio y presente un ticket de soporte si no encuentra una respuesta a su pregunta.

Si, en cambio, encontró un error en la biblioteca o desea agregar nuevas funciones, continúe y abra problemas o extraiga solicitudes en este repositorio.