Phone Calls

The Calls resource manages all interaction with Twilio phone calls, including the creation and termination of phone calls.

Making a Phone Call

The Calls resource allows you to make outgoing calls. Before a call can be successfully started, you’ll need a to set up a url endpoint which outputs valid TwiML.

require 'twilio-ruby'

# To find these visit https://www.twilio.com/user/account
account_sid = "ACXXXXXXXXXXXXXXXXX"
auth_token = "YYYYYYYYYYYYYYYYYY"

@client = Twilio::REST::Client.new account_sid, auth_token
@call = @client.calls.create(
  to: "9991231234",
  from: "9991231234",
  url: "http://foo.com/call.xml"
)
puts @call.length
puts @call.sid

Retrieve a Call Record

If you already have a Call sid, you can use the client to retrieve that record.

require 'twilio-ruby'

# To find these visit https://www.twilio.com/user/account
account_sid = "ACXXXXXXXXXXXXXXXXX"
auth_token = "YYYYYYYYYYYYYYYYYY"

@client = Twilio::REST::Client.new account_sid, auth_token
sid = "CA12341234"
@call = @client.calls.get(sid)

Delete a Call Record

require 'twilio-ruby'

# To find these visit https://www.twilio.com/user/account
account_sid = "ACXXXXXXXXXXXXXXXXX"
auth_token = "YYYYYYYYYYYYYYYYYY"

@client = Twilio::REST::Client.new account_sid, auth_token
sid = "CA12341234"
@call = @client.calls.get(sid)

# Removes the entire record from Twilio's storage
@call.delete

Accessing Specific Call Resources

Each Call resource also has access to its notifications, recordings, and transcriptions. These attributes are ListResources, just like the Calls resource itself.

require 'twilio-ruby'

# To find these visit https://www.twilio.com/user/account
account_sid = "ACXXXXXXXXXXXXXXXXX"
auth_token = "YYYYYYYYYYYYYYYYYY"

@client = Twilio::REST::Client.new account_sid, auth_token
sid = "CA12341234"
@call = @client.calls.get(sid)

puts @call.notifications.list()
puts @call.recordings.list()
puts @call.transcriptions.list()

However, what if you only have a CallSid, and not the actual Resource? No worries, as list() can be filter based on a given CallSid.

require 'twilio-ruby'

# To find these visit https://www.twilio.com/user/account
account_sid = "ACXXXXXXXXXXXXXXXXX"
auth_token = "YYYYYYYYYYYYYYYYYY"

@client = Twilio::REST::Client.new account_sid, auth_token
sid = "CA24234"
puts @client.notifications.list(call: sid)
puts @client.recordings.list(call: sid)
puts @client.transcriptions.list(call: sid)

Modifying Live Calls

The Call resource makes it easy to find current live calls and redirect them as necessary

require 'twilio-ruby'

# To find these visit https://www.twilio.com/user/account
account_sid = "ACXXXXXXXXXXXXXXXXX"
auth_token = "YYYYYYYYYYYYYYYYYY"

@client = Twilio::REST::Client.new account_sid, auth_token
@calls = @client.calls.list(status: "in-progress")

@calls.each do |call|
  call.redirect_to("http://twimlets.com/holdmusic?Bucket=com.twilio.music.ambient")
end

Ending all live calls is also possible

require 'twilio-ruby'

# To find these visit https://www.twilio.com/user/account
account_sid = "ACXXXXXXXXXXXXXXXXX"
auth_token = "YYYYYYYYYYYYYYYYYY"

@client = Twilio::REST::Client.new account_sid, auth_token
@calls = @client.calls.list(status: "in-progress")

@calls.each do |call|
  call.hangup()
end

Note that hangup() will also cancel calls currently queued.

If you already have a Call sid, you can use the Calls resource to update the record without having to use get() first.

require 'twilio-ruby'

# To find these visit https://www.twilio.com/user/account
account_sid = "ACXXXXXXXXXXXXXXXXX"
auth_token = "YYYYYYYYYYYYYYYYYY"

@client = Twilio::REST::Client.new account_sid, auth_token
sid = "CA12341234"
@client.calls.get(sid).redirect_to("http://twimlets.com/holdmusic?Bucket=com.twilio.music.ambient")

Hanging up the call also works.

require 'twilio-ruby'

# To find these visit https://www.twilio.com/user/account
account_sid = "ACXXXXXXXXXXXXXXXXX"
auth_token = "YYYYYYYYYYYYYYYYYY"

@client = Twilio::REST::Client.new account_sid, auth_token
sid = "CA12341234"
@client.calls.get(sid).hangup()