Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with
or
.
Download ZIP
Newer
Older
100644 319 lines (242 sloc) 11.587 kB
566ad4c @jsgoecke Updated the README
jsgoecke authored
1 Tropo AGItate
735798a @jsgoecke The project now has a name
jsgoecke authored
2 ==============
2ad622c @jsgoecke Initial project commit
jsgoecke authored
3
ea1f514 @jsgoecke Fixed a type in the README.
jsgoecke authored
4 Tropo AGItate lets you run Asterisk AGI applications on the Tropo cloud communications platform.
b11ff67 @jsgoecke Added a one-liner at the top to make clear what this script does
jsgoecke authored
5
2ad622c @jsgoecke Initial project commit
jsgoecke authored
6 Description
7 -----------
8
9 Provides a script to emulate the Fast Asterisk Gateway Interface [FastAGI]([http://www.voip-info.org/wiki/view/Asterisk+FastAGI "FastAGI") protocol on [Tropo](http://tropo.com "Tropo"). While most of the development and testing has been done using [Adhearsion](http://adhearsion.com "Adhearsion"), we stayed with the proper Asterisk AGI implementation. Therefore this script should work with any FastAGI server including [PHPAGI](http://phpagi.sourceforge.net/ "PHPAGI") and [Asterisk-Java](http://asterisk-java.org/ "Asterisk Java"). We will be doing more testing with alternative frameworks soon and reporting back.
10
11 Installation
12 -----------
13
376f397 @benlangfeld Kill whitespace
benlangfeld authored
14 This project allows you to control the Tropo AGI via an Adhearsion dialplan context.
2ad622c @jsgoecke Initial project commit
jsgoecke authored
15
16 * Create a free account at [Tropo](http://tropo.com "Tropo").
17
18 * Install [Adhearsion 0.8.6+](http://adhearsion.com "Adhearsion"). You can install this on your local computer.
19
20 <pre>
21 gem install adhearsion
22 </pre>
23
24 * Create a simple dialplan, or use some of the examples provided
25
26 <pre>
27 tropo_agi {
28 play "Wow. My first app! Tropo really is this easy!"
29 }
30 </pre>
31
32 * Ensure your Adhearsion app is running and has a public IP. You may need to port forward 4573 on your firewall.
33
34 * Create your Tropo application
35
36 Instructions may be found [here](https://www.tropo.com/docs/scripting/quickstart.htm "Quick Start").
37
566ad4c @jsgoecke Updated the README
jsgoecke authored
38 * Set your Tropo app to use the [lib/tropo-agitate.rb](https://github.com/tropo/tropo-agitate/raw/master/lib/tropo-agitate.rb) script
2ad622c @jsgoecke Initial project commit
jsgoecke authored
39
566ad4c @jsgoecke Updated the README
jsgoecke authored
40 * Load the file directly to the Github file location [lib/tropo-agitate.rb](https://github.com/tropo/tropo-agitate/raw/master/lib/tropo-agitate.rb)
376f397 @benlangfeld Kill whitespace
benlangfeld authored
41 * Host the 'tropo-agitate.rb' yourself and provide a public URL for access
2ad622c @jsgoecke Initial project commit
jsgoecke authored
42 * Add it to your Tropo FTP/WebDAV account
43
44 * Modify the configuration file and post it to your Tropo FTP/WebDAV account
45
566ad4c @jsgoecke Updated the README
jsgoecke authored
46 * First set your configuration settings in the [tropo_agi_config/tropo_agi_config.yml](https://github.com/tropo/tropo-agitate/raw/master/tropo_agi_config/tropo_agi_config.yml "tropo_agi_config.yml") file
2ad622c @jsgoecke Initial project commit
jsgoecke authored
47 * Then upload to your [Tropo FTP/WebDAV](https://www.tropo.com/docs/scripting/tropohosting.htm) account placing in root/www/tropo_agi_config
48
49 * Use a SIP client (like Blink for Mac) and dial the SIP Voice account listed under your application, may use Skype too!
50
51 * Happy Tropo-ing!
52
21cc719 @jsgoecke Added a structured outbound capability using the Tropo Session API. A…
jsgoecke authored
53 Placing Outbound Calls
54 ----------------------
55
56 Tropo supports placing outbound calls with the [Session API](https://www.tropo.com/docs/scripting/sessions.htm). AGItate allows for receiving a predefined set of parameters to place the call and tag it so you may associate it to your request once it reaches your AGI server. The parameters supported are:
57
58 * destination
59
376f397 @benlangfeld Kill whitespace
benlangfeld authored
60 The destination to make a call to or send a message to. This may currently take one of the following forms:
21cc719 @jsgoecke Added a structured outbound capability using the Tropo Session API. A…
jsgoecke authored
61
376f397 @benlangfeld Kill whitespace
benlangfeld authored
62 14155551212 - The telephone number to dial with the country code.
63 sip:username@doamin.com - The SIP URI to dial
64 username - The IM or Twitter user name.
21cc719 @jsgoecke Added a structured outbound capability using the Tropo Session API. A…
jsgoecke authored
65
376f397 @benlangfeld Kill whitespace
benlangfeld authored
66 Some IM networks like Google Talk and Live Messenger include a domain as part of the user name. For those networks, include the domain: username@gmail.com
21cc719 @jsgoecke Added a structured outbound capability using the Tropo Session API. A…
jsgoecke authored
67
376f397 @benlangfeld Kill whitespace
benlangfeld authored
68 When making a voice call, you can specify dialing options as part of the number:
21cc719 @jsgoecke Added a structured outbound capability using the Tropo Session API. A…
jsgoecke authored
69
376f397 @benlangfeld Kill whitespace
benlangfeld authored
70 You can also list multiple phone numbers or SIP addresses (or both!) as a comma separated list
21cc719 @jsgoecke Added a structured outbound capability using the Tropo Session API. A…
jsgoecke authored
71
72 * caller_id
73
376f397 @benlangfeld Kill whitespace
benlangfeld authored
74 The Caller ID for the session's origin. For example, if the number (407)555-1212 called (407)555-1000, the *1212 number would be the callerID. This also applies to IM account names; if IM account 'tropocloud' sends a message to 'foobar123', the callerID would be 'tropocloud'.
21cc719 @jsgoecke Added a structured outbound capability using the Tropo Session API. A…
jsgoecke authored
75
376f397 @benlangfeld Kill whitespace
benlangfeld authored
76 The callerID can be manually set to a specific number; for voice calls, this can be any valid phone number, though for SMS and IM it must be a number/ID assigned to your account.
21cc719 @jsgoecke Added a structured outbound capability using the Tropo Session API. A…
jsgoecke authored
77
78 * channel
79
376f397 @benlangfeld Kill whitespace
benlangfeld authored
80 Channel tells Tropo whether the call is "voice" or "text".
21cc719 @jsgoecke Added a structured outbound capability using the Tropo Session API. A…
jsgoecke authored
81
82 * network
83
376f397 @benlangfeld Kill whitespace
benlangfeld authored
84 Network is used mainly by the text channels; values can be SMS when sending a text message, or a valid IM network name such as AIM, GTALK, MSN, JABBER, TWITTER and YAHOO. For IM network, you must have an IM account linked in your app. For example, if you try to send to AIM when you don't have an AIM username included in your app, your app will fail.
21cc719 @jsgoecke Added a structured outbound capability using the Tropo Session API. A…
jsgoecke authored
85
86 * timeout
87
376f397 @benlangfeld Kill whitespace
benlangfeld authored
88 Timeout only applies to the voice channel and determines the amount of time Tropo will wait - in seconds - for the call to be answered before giving up.
21cc719 @jsgoecke Added a structured outbound capability using the Tropo Session API. A…
jsgoecke authored
89
90 * tropo_tag
91
376f397 @benlangfeld Kill whitespace
benlangfeld authored
92 An arbitrary unique identifier that you may use to identify the call once it is placed and passed to your AGI server. This value will appear in the tropo\_headers variable received at the beginning of the request to your AGI server in the JSON as tropo\_tag.
93
21cc719 @jsgoecke Added a structured outbound capability using the Tropo Session API. A…
jsgoecke authored
94 You may then invoke a call request via HTTP as follows:
95
96 * GET
64f19aa @jsgoecke Fixed the formatting of the README
jsgoecke authored
97 <pre>
376f397 @benlangfeld Kill whitespace
benlangfeld authored
98 http://api.tropo.com/1.0/sessions?action=create&token=TOKEN&destination=NUMBER&caller\_id=CALLINGNUMBER&tropo_tag=1234
64f19aa @jsgoecke Fixed the formatting of the README
jsgoecke authored
99 </pre>
100
21cc719 @jsgoecke Added a structured outbound capability using the Tropo Session API. A…
jsgoecke authored
101 * POST
64f19aa @jsgoecke Fixed the formatting of the README
jsgoecke authored
102 <pre>
376f397 @benlangfeld Kill whitespace
benlangfeld authored
103 http://api.tropo.com/1.0/sessions
104 <code>
105 <session>
106 <token>YOUR_TOKEN</token>
107 <var name="destination" value="4155551212" />
108 <var name="caller_id" value="7146432997" />
109 <var name="tropo_tag" value=1234 />
110 </session>
111 </code>
64f19aa @jsgoecke Fixed the formatting of the README
jsgoecke authored
112 </pre>
376f397 @benlangfeld Kill whitespace
benlangfeld authored
113
2ad622c @jsgoecke Initial project commit
jsgoecke authored
114 Supported Adhearsion & AGI Methods
115 ----------------------------------
116
2ff5b9b @jsgoecke Fixed a broken link in the README
jsgoecke authored
117 Refer to the wiki [Supported Adhearsion and Asterisk Gateway Interface (AGI) Commands](http://github.com/tropo/tropo-agitate/wiki/Supported-Adhearsion-&-AGI-Methods) page.
2ad622c @jsgoecke Initial project commit
jsgoecke authored
118
119 Asterisk Sound Files Available
120 ------------------------------
121
fecd8cd @jsgoecke Updated the README to let folks know that the wiki page will also let…
jsgoecke authored
122 Refer to the wiki [Asterisk Core Sounds Available](http://github.com/tropo/tropo-agitate/wiki/Built-In-Asterisk-Sound-Files) page. This will also let you know how to add your own custom sound files.
2ad622c @jsgoecke Initial project commit
jsgoecke authored
123
124 Adhearsion Dialplan Examples
125 ----------------------------
126
127 These Adhearsion dialplan examples are also available in the 'examples' directory of this project.
128
129 <pre>
376f397 @benlangfeld Kill whitespace
benlangfeld authored
130 # The main AGI entry point
131 tropo_agi {
132 answer
133 +hello_world
134 hangup
135 }
136
137
138 # Invokes the native Tropo ask for Speech Recognition / ASR
139 # Related Tropo method: https://www.tropo.com/docs/scripting/ask.htm
140 ask_example {
141 result = execute 'ask', { :prompt => 'Please enter your zip code',
142 :choices => 'zipcode([5 DIGITS])' }.to_json
143 # Get rid of the '200 result =' and then parse the JSON
144 response = JSON.parse(result[11..-1])
145 ahn_log.debug response
146 }
147
148 # We have lots of Asterisk sounds!
149 asterisk_sounds_example {
150 play 'tt-monkeys'
151 }
152
153 # You may dial other SIP addresses, or telephone numbers as you like
154 # Formats may be:
155 # SIP/
156 # sip:
157 # tel:+
158 # Related Tropo method: https://www.tropo.com/docs/scripting/transfer.htm
159 dial_example {
160 dial 'sip:9991443146@sip.tropo.com'
161 }
162
163 hello_world {
164 play 'tt-monkeys'
165 }
166
167 # Works as input should, only accepting DTMF
168 # Related Tropo method: https://www.tropo.com/docs/scripting/ask.htm
169 input_example {
170 postal_code = input 5, :play => 'Please enter your post code?',
171 :timeout => 2
172
173 ahn_log.postal_code.debug postal_code
174 play "You entered"
175 say_digits postal_code
176 }
177
178 # Find out if this is a Tropo session or an Asterisk one
179 is_tropo? {
180 if type == 'TROPO'
181 play "Yippeee! It is a Tropo call!"
182 else
183 play "No, this is a good old Asterisk call"
184 end
185 }
186
187 # Related Tropo method: https://www.tropo.com/docs/scripting/say.htm
188 say_digits_example {
189 say_digits '12345'
190 }
191
192 # Uses the native Tropo say method for Speech-Synthesis/TTS, will not play Asterisk sound files like play will
193 # Related Tropo method: https://www.tropo.com/docs/scripting/say.htm
194 say_example {
195 execute 'say', { :prompt => 'I like to have weasels in my cloud.', :voice => 'simon' }.to_json
196 }
197
77011de @jsgoecke Expanded the support for the AGI STREAM FILE command. Also fixed the …
jsgoecke authored
198 # Supports STREAM FILE with and without escape digts
199 # Note, any digits at the end of the string will always be treated as escape digits
200 stream_file_example {
201 raw_response "STREAM FILE tt-monkeys 1234567890*#"
202 raw_response "STREAM FILE tt-monkeys"
203 }
204
376f397 @benlangfeld Kill whitespace
benlangfeld authored
205 # If this is a Tropo call, then all of the SIP headers for the session are available
206 show_call_data {
207 ahn_log.tropo_headers_str.debug tropo_headers
208 tropo_headers = JSON.parse self.tropo_headers
209 ahn_log.tropo_headers_hash.debug tropo_headers
210 play "The content type is " + tropo_headers['Content-Type']
211 +asterisk_sounds_example
212 }
213
214 # Monitor and Mixmonitor behave the same, may also be invoked as startCallRecording
215 # Related Tropo method: https://www.tropo.com/docs/scripting/startcallrecording.htm
216 monitor_example {
217 play 'About to start call recording'
218 execute 'monitor', { :uri => 'http://tropo-audiofiles-to-s3.heroku.com/post_audio_to_s3?filename=voicemail.mp3',
219 :format => 'mp3',
220 :method => 'POST',
221 :transcriptionOutURI => 'mailto:jsgoecke@voxeo.com' }.to_json
222 play 'Call recording started!'
223 play 'Thats it folks!'
224 execute 'monitor_stop', ''
225 play 'Recording stopped!'
226 }
227
228 # Related Tropo method: https://www.tropo.com/docs/scripting/record.htm
229 record_prompt_example {
230 play 'Please record after the beep'
231 record 'http://tropo-audiofiles-to-s3.heroku.com/post_audio_to_s3?filename=voicemail.mp3',
232 :silence => 5,
233 :maxduration => 120
234 }
235
236 # Allows you to set and retrieve variables on the session
237 # These also get passed as custom SIP headers, prepended with 'x-tropo' when you dial/transfer a call
238 variables_example {
239 set_variable('foobar', 'green')
240 ahn_log.debug get_variable('foobar')
241 }
242
243 # We have lots of Asterisk sounds!
244 asterisk_sounds_example {
245 play 'tt-monkeys'
246 }
247
248 # Allows you to send standard DTMF digits
249 send_dtmf_example {
250 dtmf '1234567890#*'
251 }
252
253 # Shows how to set the voice option for speech synthesis/TTS
254 set_voice_example {
255 play 'Hello world!'
256 execute "voice", "simon"
257 play 'Hello world!'
258 execute "voice", "default"
259 play 'Hello world!'
260 }
261
262 # Shows how to set the voice option for speech synthesis/TTS
263 set_recognizer_example {
264 execute "voice", "carmen"
265 execute "recognizer", "es-es"
266 result = execute 'ask', { :prompt => 'Por favor, ingrese su código postal',
267 :choices => 'zipcode([5 DIGITS])' }.to_json
268 # Get rid of the '200 result =' and then parse the JSON
269 response = JSON.parse(result[11..-1])
270 ahn_log.debug response
271 }
272
273 # Start menu example
274 # Related Tropo method: https://www.tropo.com/docs/scripting/ask.htm
275 menu_example {
77011de @jsgoecke Expanded the support for the AGI STREAM FILE command. Also fixed the …
jsgoecke authored
276 menu 'Welcome. For Shipments press 1. For ordering press 2. For a representative push 3 or for Spanish press 4', :timeout => 8.seconds, :tries => 3 do |link|
376f397 @benlangfeld Kill whitespace
benlangfeld authored
277 link.shipment_status 1
278 link.ordering 2
279 link.representative 3
280 link.spanish 4
281 link.employee 500..599
282
283 link.on_invalid { play 'invalid' }
284
285 link.on_premature_timeout do |str|
286 play 'sorry'
287 end
288
289 link.on_failure do
290 play 'goodbye'
291 hangup
292 end
293 end
294 }
295
296 shipment_status {
297 play 'I surely do not know your shipment status.'
298 }
299
300 ordering {
301 play 'Go somewhere else and order.'
302 }
303
304 representative {
305 play 'No representatives here.'
306 }
307
308 spanish {
309 play 'e 2 brutus?'
310 }
311
312 employee {
313 play "The person at"
314 say_digits extension
315 play "went home for the day."
316 }
317 # End menu example
2ad622c @jsgoecke Initial project commit
jsgoecke authored
318 </pre>
Something went wrong with that request. Please try again.