Class: Twilio::Verb

Inherits:
Object
  • Object
show all
Defined in:
lib/twilio/verb.rb

Overview

Twilio Verbs enable your application to respond to Twilio requests (to your app) with XML responses. There are 5 primary verbs (say, play, gather, record, dial) and 3 secondary (hangup, pause, redirect). Verbs can be chained and, in some cases, nested.

If your response consists of a single verb, you can call a Verb class method:

Twilio::Verb.say 'The time is 9:35 PM.'

But if you need to chain several verbs together, just wrap them in an instance block and call the ‘response’ attribute:

verb = Twilio::Verb.new { |v|
  v.dial '415-123-4567'
  v.redirect 'http://www.foo.com/nextInstructions'
}
verb.response

Instance Attribute Summary collapse

Class Method Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize(&block) ⇒ Verb

Returns a new instance of Verb.



30
31
32
33
34
35
36
37
38
 
# File 'lib/twilio/verb.rb', line 30

def initialize(&block)
  @xml = Builder::XmlMarkup.new
  @xml.instruct!

  if block_given?
    @chain = true
    @response = @xml.Response { block.call(self) }
  end
end

Instance Attribute Details

#response ⇒ Object (readonly)

Returns the value of attribute response.



21
22
23
 
# File 'lib/twilio/verb.rb', line 21

def response
  @response
end

Class Method Details

.method_missing(method_id, *args) ⇒ Object

:nodoc:



24
25
26
27
 
# File 'lib/twilio/verb.rb', line 24

def method_missing(method_id, *args) #:nodoc:
  v = Verb.new
  v.send(method_id, *args)
end

Instance Method Details

#conference(*args) ⇒ Object

The <Dial> verb’s <Conference> noun allows you to connect to a conference room. Much like how the <Number> noun allows you to connect to another phone number, the <Conference> noun allows you to connect to a named conference room and talk with the other callers who have also connected to that room.

Options (see www.twilio.com/docs/api_reference/TwiML/conference) are passed in as a hash

Examples:

verb = Twilio::Verb.new { |v|
  v.dial {
    v.conference 'MyRoom', :muted => true
  }
}
verb.response



235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
 
# File 'lib/twilio/verb.rb', line 235

def conference(*args)
  conference_name = ''
  options = {}
  args.each do |arg|
    case arg
    when String
      conference_name = arg
    when Hash
      options.merge!(arg)
    else
      raise ArgumentError, 'conference expects String or Hash argument'
    end
  end

  output { @xml.Conference(conference_name, options)}
end

#dial(*args, &block) ⇒ Object

The Dial verb connects the current caller to an another phone. If the called party picks up, the two parties are connected and can communicate until one hangs up. If the called party does not pick up, if a busy signal is received, or the number doesn’t exist, the dial verb will finish.

If an action verb is provided, Twilio will submit the outcome of the call attempt to the action URL. If no action is provided, Dial will fall through to the next verb in the document.

Note: this is different than the behavior of Record and Gather. Dial does not submit back to the current document URL if no action is provided.

Options (see www.twilio.com/docs/api_reference/TwiML/dial) are passed in as a hash

Examples:

Twilio::Verb.dial '415-123-4567'
Twilio::Verb.dial '415-123-4567', :action => 'http://foobar.com'
Twilio::Verb.dial '415-123-4567', :timeout => 10, :callerId => '858-987-6543'

Twilio also supports an alternate form in which a Number object is nested inside Dial:

verb = Twilio::Verb.new { |v|
  v.dial { |v|
    v.number '415-123-4567'
    v.number '415-123-4568'
    v.number '415-123-4569'
  }
}
verb.response # represents the final xml output



198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
 
# File 'lib/twilio/verb.rb', line 198

def dial(*args, &block)
  number_to_dial = ''
  options = {}
  args.each do |arg|
    case arg
    when String
      number_to_dial = arg
    when Hash
      options.merge!(arg)
    else
      raise ArgumentError, 'dial expects String or Hash argument'
    end
  end

  output {
    if block_given?
      @xml.Dial(options) { block.call }
    else
      @xml.Dial(number_to_dial, options)
    end
  }
end

#gather(*args, &block) ⇒ Object

The Gather verb collects digits entered by a caller into their telephone keypad. When the caller is done entering data, Twilio submits that data to a provided URL, as either a HTTP GET or POST request, just like a web browser submits data from an HTML form.

Options (see www.twilio.com/docs/api_reference/TwiML/gather) are passed in as a hash

Examples:

Twilio::Verb.gather
Twilio::Verb.gather :action => 'http://foobar.com'
Twilio::Verb.gather :finishOnKey => '*'
Twilio::Verb.gather :action => 'http://foobar.com', :finishOnKey => '*'

Gather also lets you nest the Play, Say, and Pause verbs:

verb = Twilio::Verb.new { |v|
  v.gather(:action => '/process_gather', :method => 'GET) {
    v.say 'Please enter your account number followed by the pound sign'
  }
  v.say "We didn't receive any input. Goodbye!"
}
verb.response # represents the final xml output



143
144
145
146
147
148
149
150
151
152
 
# File 'lib/twilio/verb.rb', line 143

def gather(*args, &block)
  options = args.shift || {}
  output {
    if block_given?
      @xml.Gather(options) { block.call}
    else
      @xml.Gather(options)
    end
  }
end

#hangup ⇒ Object

The Hangup (secondary) verb ends the call.

Examples:

If your response is only a hangup:

Twilio::Verb.hangup

If your response is chained:

verb = Twilio::Verb.new { |v|
  v.say "The time is #{Time.now}"
  v.hangup
}
verb.response



337
338
339
 
# File 'lib/twilio/verb.rb', line 337

def hangup
  output { @xml.Hangup }
end

#number(*args) ⇒ Object

The Number element specifies a phone number. The number element has two optional attributes: sendDigits and url. Number elements can only be nested in Dial verbs



343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
 
# File 'lib/twilio/verb.rb', line 343

def number(*args)
  number_to_dial = ''
  options = {}
  args.each do |arg|
    case arg
    when String
      number_to_dial = arg
    when Hash
      options.merge!(arg)
    else
      raise ArgumentError, 'dial expects String or Hash argument'
    end
  end

  output { @xml.Number(number_to_dial, options) }
end

#pause(*args) ⇒ Object

The Pause (secondary) verb waits silently for a number of seconds. It is normally chained with other verbs.

Options (see www.twilio.com/docs/api_reference/TwiML/pause) are passed in as a hash

Examples:

verb = Twilio::Verb.new { |v|
  v.say 'greetings'
  v.pause :length => 2
  v.say 'have a nice day'
}
verb.response



264
265
266
267
 
# File 'lib/twilio/verb.rb', line 264

def pause(*args)
  options = args.shift
  output { @xml.Pause(options) }
end

#play(*args) ⇒ Object

The Play verb plays an audio URL back to the caller. Examples:

Twilio::Verb.play 'http://foo.com/cowbell.mp3'
Twilio::Verb.play 'http://foo.com/cowbell.mp3', :loop => 3

If you need a longer pause between each loop, instead of explicitly calling the Pause verb within a block, you can set the convenient pause option:

Twilio::Verb.play 'http://foo.com/cowbell.mp3', :loop => 3, :pause => true

Options (see www.twilio.com/docs/api_reference/TwiML/play) are passed in as a hash, but only ‘loop’ is currently supported.



98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
 
# File 'lib/twilio/verb.rb', line 98

def play(*args)
  options = {:loop => 1}
  args.each do |arg|
    case arg
    when String
      options[:audio_url] = arg
    when Hash
      options.merge!(arg)
    else
      raise ArgumentError, 'play expects String or Hash argument'
    end
  end

  output {
    if options[:pause]
      loop_with_pause(options[:loop], @xml) do
        @xml.Play(options[:audio_url])
      end
    else
      @xml.Play(options[:audio_url], :loop => options[:loop])
    end
  }
end

#record(*args) ⇒ Object

The Record verb records the caller’s voice and returns a URL that links to a file containing the audio recording.

Options (see www.twilio.com/docs/api_reference/TwiML/record) are passed in as a hash

Examples:

Twilio::Verb.record
Twilio::Verb.record :action => 'http://foobar.com'
Twilio::Verb.record :finishOnKey => '*'
Twilio::Verb.record :transcribe => true, :transcribeCallback => '/handle_transcribe'



166
167
168
169
 
# File 'lib/twilio/verb.rb', line 166

def record(*args)
  options = args.shift
  output { @xml.Record(options) }
end

#redirect(*args) ⇒ Object

The Redirect (secondary) verb transfers control to a different URL. It is normally chained with other verbs.

Options (see www.twilio.com/docs/api_reference/TwiML/redirect) are passed in as a hash

Examples:

verb = Twilio::Verb.new { |v|
  v.dial '415-123-4567'
  v.redirect 'http://www.foo.com/nextInstructions'
}
verb.response



280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
 
# File 'lib/twilio/verb.rb', line 280

def redirect(*args)
  redirect_to_url = ''
  options = {}
  args.each do |arg|
    case arg
    when String
      redirect_to_url = arg
    when Hash
      options.merge!(arg)
    else
      raise ArgumentError, 'dial expects String or Hash argument'
    end
  end

  output { @xml.Redirect(redirect_to_url, options) }
end

#reject(options = {}) ⇒ Object

The Reject verb rejects an incoming call to your Twilio number without billing you (see www.twilio.com/docs/api/twiml/reject) Examples:

Twilio::Verb.reject

If reject is called with an argument:

Twilio::Verb.reject :reason => "busy"



371
372
373
 
# File 'lib/twilio/verb.rb', line 371

def reject options = {}
  output { @xml.Reject(options) }
end

#say(*args) ⇒ Object

The Say verb converts text to speech that is read back to the caller. Say is useful for dynamic text that is difficult to prerecord.

Examples:

Twilio::Verb.say 'The time is 9:35 PM.'
Twilio::Verb.say 'The time is 9:35 PM.', :loop => 3

With numbers, 12345 will be spoken as “twelve thousand three hundred forty five” while 1 2 3 4 5 will be spoken as “one two three four five.”

Twilio::Verb.say 'Your PIN is 1234', :loop => 4
Twilio::Verb.say 'Your PIN is 1 2 3 4', :loop => 4

If you need a longer pause between each loop, instead of explicitly calling the Pause verb within a block, you can set the convenient pause option:

Twilio::Verb.say 'Your PIN is 1 2 3 4', :loop => 4, :pause => true

Options (see www.twilio.com/docs/api_reference/TwiML/say) are passed in as a hash:

Twilio::Verb.say 'The time is 9:35 PM.', :voice => 'woman'
Twilio::Verb.say 'The time is 9:35 PM.', :voice => 'woman', :language => 'es'



62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
 
# File 'lib/twilio/verb.rb', line 62

def say(*args)
  options = {:voice => 'man', :language => 'en', :loop => 1}
  args.each do |arg|
    case arg
    when String
      options[:text_to_speak] = arg
    when Hash
      options.merge!(arg)
    else
      raise ArgumentError, 'say expects String or Hash argument'
    end
  end

  output {
    if options[:pause]
      loop_with_pause(options[:loop], @xml) do
        @xml.Say(options[:text_to_speak], :voice => options[:voice], :language => options[:language])
      end
    else
      @xml.Say(options[:text_to_speak], :voice => options[:voice], :language => options[:language], :loop => options[:loop])
    end
  }
end

#sms(*args) ⇒ Object

The <Sms> verb sends a SMS message to a phone number.

Options (see www.twilio.com/docs/api/2008-08-01/twiml/sms/sms) ars passed in as a hash

Examples:

verb = Twilio::Verb.new { |v|
  v.sms 'Meet at South Street'
}



306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
 
# File 'lib/twilio/verb.rb', line 306

def sms(*args)
  message = ''
  options = {}
  args.each do |arg|
    case arg
    when String
      message = arg
    when Hash
      options.merge!(arg)
    else
      raise ArgumentError, 'sms expects STring or Hash argument'
    end
  end

  output { @xml.Sms(message, options) }
end