twilio ruby

Twilio-Rubin

Dokumentation

Die Dokumentation zur Twilio-API finden Sie hier.

Die einzelnen Veröffentlichungen hier.

Versionen

twilio-ruby verwendet für alle Änderungen eine modifizierte Version der semantischen Versionierung. Einzelheiten finden Sie in diesem Dokument.

Unterstützte Ruby-Versionen

Diese Bibliothek unterstützt die folgenden Ruby-Implementierungen:

• Ruby 2.4

• Ruby 2.5

• Ruby 2.6

• Ruby 2.7

• Ruby 3.0

• Ruby 3.1

• Ruby 3.2

• JRuby 9.2

• JRuby 9.3

• JRuby 9.4

Migration von 5.x

Upgrade-Anleitung

Installation

Um mit Bundler zu installieren, holen Sie sich die neueste stabile Version:

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

Um twilio-ruby manuell über Rubygems zu installieren, einfach gem install:

gem install twilio-ruby -v 7.3.6

So erstellen und installieren Sie den Entwicklungszweig selbst aus der neuesten Quelle:

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

Info Wenn in der Befehlszeile die Fehlermeldung „Berechtigung verweigert“ angezeigt wird, versuchen Sie, die oben genannten Befehle mit sudo auszuführen.

Zum Beispiel: sudo gem install twilio-ruby

Testen Sie Ihre Installation

Um sicherzustellen, dass die Installation erfolgreich war, versuchen Sie, sich selbst eine SMS-Nachricht wie diese zu senden:

 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

Warnung: Es ist in Ordnung, Ihre Anmeldeinformationen beim lokalen Testen fest zu kodieren, Sie sollten jedoch Umgebungsvariablen verwenden, um sie geheim zu halten, bevor Sie Code festschreiben oder in der Produktion bereitstellen. Weitere Informationen finden Sie unter „So legen Sie Umgebungsvariablen fest“.

Verwendung

Authentifizieren Sie den Client

 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

Verwenden Sie einen API-Schlüssel

 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

Geben Sie eine Region und/oder Kante an

Um die Vorteile der globalen Infrastruktur von Twilio zu nutzen, geben Sie die Zielregion und/oder den Edge für den Client an:

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

Dies führt dazu, dass sich der hostname von api.twilio.com in api.sydney.au1.twilio.com ändert.

Rufen Sie an

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

Senden Sie eine SMS

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

Listen Sie Ihre SMS-Nachrichten auf

 @client . messages . list ( limit : 20 )

Rufen Sie eine einzelne SMS-Nachricht von Sid ab

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

Durchlaufen Sie Datensätze

Die Bibliothek übernimmt automatisch das Paging für Sie. Sammlungen wie calls und messages verfügen über list und Stream-Methoden, die unter der Haube blättern. Sowohl bei list als auch stream können Sie die Anzahl der Datensätze angeben, die Sie empfangen möchten ( limit ) und die maximale Größe, die jeder Seitenabruf haben soll ( page_size ). Die Bibliothek übernimmt dann die Aufgabe für Sie.

list ruft eifrig alle Datensätze ab und gibt sie als Liste zurück, während stream einen Enumerator zurückgibt und beim Durchlaufen der Sammlung langsam Seiten mit Datensätzen abruft. Sie können mit der page auch manuell blättern.

Weitere Informationen zu diesen Methoden finden Sie in den automatisch generierten Bibliotheksdokumenten.

 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

Aktivieren Sie die Debug-Protokollierung

Um die Debug-Protokollierung zu aktivieren, übergeben Sie eine „Logger“-Instanz an den Client, deren Stufe mindestens auf „DEBUG“ eingestellt ist.

 @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

Behandeln Sie Ausnahmen {#Exceptions}

Wenn die Twilio-API eine HTTP-Antwort der Stufe 400 oder 500 zurückgibt, löst die twilio-ruby -Bibliothek einen Twilio::REST::RestError aus. Fehler der Stufe 400 sind während des API-Betriebs normal (z. B. “Invalid number” , “Cannot deliver SMS to that number” ) und sollten entsprechend behandelt werden.

 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-Anfragen debuggen

Zur Unterstützung beim Debuggen ermöglicht Ihnen die Bibliothek den Zugriff auf die zugrunde liegenden Anforderungs- und Antwortobjekte. Diese Funktion ist in den Standard-HTTP-Client integriert, der mit der Bibliothek geliefert wird.

Sie können den Statuscode der letzten Antwort beispielsweise wie folgt abrufen:

 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

Passen Sie Ihren HTTP-Client an

twilio-ruby verwendet Faraday, um HTTP-Anfragen zu stellen. Sie können Twilio::REST::Client anweisen, einen der Faraday-Adapter wie folgt zu verwenden:

 @client . http_client . adapter = :typhoeus

Um einen benutzerdefinierten HTTP-Client mit dieser Hilfsbibliothek zu verwenden, sehen Sie sich bitte das erweiterte Beispiel an.

Um Anpassungen wie Middleware anzuwenden, können Sie die Methode configure_connection wie folgt verwenden:

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

Beginnen Sie mit Client Capability Tokens

Wenn Sie lediglich ein Capability-Token für die Verwendung mit dem Twilio-Client generieren müssen, können Sie Folgendes tun:

 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

Ein etwas ausführlicheres Dokument finden Sie im Abschnitt „Fähigkeiten“ des Wikis.

Generieren Sie TwiML

Um Telefonanrufe zu steuern, muss Ihre Anwendung TwiML ausgeben.

Sie können eine TwiML-Antwort wie folgt erstellen:

 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

Dadurch wird Folgendes gedruckt (mit Ausnahme des Leerzeichens):

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

Docker-Image

Die in diesem Repository vorhandene Dockerfile und das entsprechende Docker-Image twilio/twilio-ruby werden von Twilio derzeit nur zu Testzwecken verwendet.

Hilfe bekommen

Wenn Sie Hilfe bei der Installation oder Verwendung der Bibliothek benötigen, schauen Sie bitte zuerst im Twilio Support Help Center nach und reichen Sie ein Support-Ticket ein, wenn Sie keine Antwort auf Ihre Frage finden.

Wenn Sie stattdessen einen Fehler in der Bibliothek gefunden haben oder neue Funktionen hinzufügen möchten, öffnen Sie Issues oder Pull-Requests für dieses Repo!