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

#responseObject (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

#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

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

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

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

#hangupObject

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

335
336
337
# File 'lib/twilio/verb.rb', line 335

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


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

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

262
263
264
265
# File 'lib/twilio/verb.rb', line 262

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

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

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

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

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

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