Liverpie works as a proxy in the following way: when a connection is opened to it from FreeSWITCH (so when a call to the associated extension is made and the dialplan executes the "socket" application), Liverpie first sends a predefined set of commands to FreeSWITCH. (These are hardcoded. If you absolutely need some other sort of channel initialization, edit @initial_commands in liverpie_server.rb).
You have to write your own web-based state machine, in the language of your choice. That means that when you load the same URL of your webapp, it will change its state and reply differently, changing its state request after request, based on the POST parameters, until the thread of the state machine execution is logically finished (presumably with a hangup command). Your state machine can be a huge "case" or "switch" statement, or it can use the concept of "next_step" as my example below, or you can do it however you please.
The idea is that you can keep the machine state in the session, since Liverpie and your cookies are buddies (as opposed to on the lunch menu).
Once FreeSWITCH responds, your webapp will be called at the given URL to reset its state machine.
Then it will be called again, as the first step of the IVR.
It is then the responsability of your web application to return a YAML containing the following information:
Of course the YAML must be plain text, without HTML formatting or any other sort.
Here is an example of a YAML that will send a wave playback command to FreeSWITCH, and ask it to wait for an event whose name signifies that the last execution has completed:
Liverpie will always maintain a hash of parameters received from FreeSWITCH and send them over to the webapp via POST, as regular HTTP parameters.
At the first request, that hash is empty; it is then MERGED (not REPLACED) with every new set of parameters received from FreeSWITCH. That means that the values will always be refreshed, but that you will have values which have persisted from previous calls.
I am not yet sure whether that merging is needed, but it seemed like it was.
If you specify a webapp_dtmf_uri in your config file, then everytime Liverpie receives a DTMF event from Freeswitch, it will call that method with a parameter named "dtmf_code". The value of that parameter will be the DTMF code received by Freeswitch.
You can return a YAML command (like with the state machine runner method), or nothing at all.
Important: Even if you use the 'read' command and use channel variables in order to retrieve the pushed keys, the DTMF events will still be issued. You are free to ignore them then, or ignore them altogether by setting webapp_dtmf_uri to empty in your Liverpie config file.
As of 0.5, Liverpie can distribute calls to more than one webapp. That means that you can set up more extensions in your dialplan, for different IVRs, and have them all handled by the same Liverpie instance.
To do that, you have to give each of your webapps an id in liverpie.yml (one is provided as example) and then set the liverpie_webapp_id channel variable as described in the example above.