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.



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

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.



19
20
21
 
# File 'lib/twilio/verb.rb', line 19

def response
  @response
end

Class Method Details

.method_missing(method_id, *args) ⇒ Object

:nodoc:



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

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

Instance Method Details

#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.number('415-123-4567')
    v.number('415-123-4568')
    v.number('415-123-4569')
  }
}
verb.response # represents the final xml output



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

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



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

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



278
279
280
 
# File 'lib/twilio/verb.rb', line 278

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



284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
 
# File 'lib/twilio/verb.rb', line 284

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



231
232
233
234
 
# File 'lib/twilio/verb.rb', line 231

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.



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

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



164
165
166
167
 
# File 'lib/twilio/verb.rb', line 164

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



247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
 
# File 'lib/twilio/verb.rb', line 247

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

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



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

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