== twilio

Bindings to the Twilio API
[[toc:]]
=== Abstract
[[http://www.twilio.com/|Twilio]] allows one to send SMSes and
place calls using their API; and the {{twilio}} egg requires at least three
pieces of information to do so:

* The account SID
* The auth token
* The from number

They are populated initially from the environment
variables {{TWILIO_SID}}, {{TWILIO_AUTH}}, {{TWILIO_FROM}};
respectively. It is also possible to set the dynamic
parameters {{twilio-sid}}, {{twilio-auth}}, {{twilio-from}}.


=== Documentation
==== {{twilio-sid}}
<parameter>twilio-sid → (get-environment-variable TWILIO_SID)</parameter>
The Twilio account SID
<enscript highlight="scheme">(define twilio-sid (make-parameter (get-environment-variable "TWILIO_SID")))
</enscript>
==== {{twilio-auth}}
<parameter>twilio-auth → (get-environment-variable TWILIO_AUTH)</parameter>
The Twilio auth token
<enscript highlight="scheme">(define twilio-auth (make-parameter (get-environment-variable "TWILIO_AUTH")))
</enscript>
==== {{twilio-from}}
<parameter>twilio-from → (get-environment-variable TWILIO_FROM)</parameter>
The phone number from which to post
<enscript highlight="scheme">(define twilio-from (make-parameter (get-environment-variable "TWILIO_FROM")))
</enscript>
==== {{twilio-url}}
<parameter>twilio-url → https://~a:~a@api.twilio.com/2010-04-01/Accounts/~a/~a</parameter>
The Twilio API URL
<enscript highlight="scheme">(define twilio-url
  (make-parameter "https://~a:~a@api.twilio.com/2010-04-01/Accounts/~a/~a"))
</enscript>
==== {{twilio-make-call}}
<procedure>(twilio-make-call to #!key url application-sid method fallback-url fallback-method status-callback status-callback-method send-digits if-machine timeout record) → unspecified</procedure>
Make a call using the Twilio API; see [[http://www.twilio.com/docs/api/rest/making-calls]].
; to : The phone number to call
; url : TwiML URL when the call connects
; application-sid : Alternatively, the app containing the URL
; method : Method to request {{url}}
; fallback-url : Second {{url}} to try
; fallback-method : Method to which to fall back
; status-callback : URL to post status to
; status-callback-method : Method to use
; send-digits : Keys to dial after connecting
; if-machine : Determine whether the caller is a machine
; timeout : How long to let the phone ring
; record : Whether to record the call
<enscript highlight="scheme">(define (twilio-make-call
         to
         #!key
         url
         application-sid
         method
         fallback-url
         fallback-method
         status-callback
         status-callback-method
         send-digits
         if-machine
         timeout
         record)
  (let ((parameters
          `((from unquote (twilio-from))
            (to unquote to)
            (url unquote url)
            (application-sid unquote application-sid)
            (method unquote method)
            (fallback-url unquote fallback-url)
            (fallback-method unquote fallback-method)
            (status-callback unquote status-callback)
            (status-callback-method unquote status-callback-method)
            (send-digits unquote send-digits)
            (if-machine unquote if-machine)
            (timeout unquote timeout)
            (record unquote record))))
    (with-input-from-request
      (twilio-url-calls)
      (upper-camel-filter-parameters parameters)
      void)))
</enscript>
===== Examples
Placing a call
 (twilio-make-call "+14158141829" url: "http://example.com/twiml.scm")
==== {{twilio-send-sms}}
<procedure>(twilio-send-sms to body #!key status-callback application-sid) → unspecified</procedure>
Send an SMS using the Twilio API; see [[http://www.twilio.com/docs/api/rest/sending-sms]].
; to : The number to send to
; body : The SMS to send
; status-callback : POST when the message is processed
; application-sid : The application's SID
<enscript highlight="scheme">(define (twilio-send-sms to body #!key status-callback application-sid)
  (let ((parameters
          `((from unquote (twilio-from))
            (to unquote to)
            (body unquote body)
            (status-callback unquote status-callback)
            (application-sid unquote application-sid))))
    (with-input-from-request
      (twilio-url-sms)
      (upper-camel-filter-parameters parameters)
      void)))
</enscript>
===== Examples
Sending an SMS
 (twilio-send-sms "+14158141829"
                  "If you wish to make an apple pie from scratch, you must first invent the universe.")
==== {{twilio-write}}
<procedure>(twilio-write response) → unspecified</procedure>
Write STwiML as TwiML.
; response : The STwiML response
<enscript highlight="scheme">(define twilio-write write-shtml-as-html)
</enscript>
==== {{twilio-response}}
<procedure>(twilio-response . verbs) → STwiML</procedure>
Wrap verbs in a STwiML response; see [[http://www.twilio.com/docs/api/twiml]].
; verbs : The verbs to wrap in a response
<enscript highlight="scheme">(define (twilio-response . verbs) `(Response ,@verbs))
</enscript>
==== {{twilio-say}}
<procedure>(twilio-say text #!key voice loop language) → STwiML</procedure>
Say something; see [[http://www.twilio.com/docs/api/twiml/say]].
; text : The text to say
; voice : The voice to say it in
; loop : How many times to say it
; language : The language to say it in
<enscript highlight="scheme">(define (twilio-say text #!key voice loop language)
  (let ((parameters
          (lower-camel-filter-parameters
            `((voice ,voice) (loop ,loop) (language ,language)))))
    (if (null? parameters)
      `(Say ,text)
      `(Say (,(string->symbol "@")
             ,@(lower-camel-filter-parameters parameters))
            ,text))))
</enscript>
==== {{twilio-play}}
<procedure>(twilio-play url #!key loop) → STwiML</procedure>
Play something; see [[http://www.twilio.com/docs/api/twiml/play]].
; url : The audio file to play
; loop : How many times to play it
<enscript highlight="scheme">(define (twilio-play url #!key loop)
  (let ((parameters (lower-camel-filter-parameters `((loop ,loop)))))
    (if (null? parameters)
      `(Play ,url)
      `(Play (,(string->symbol "@")
              ,@(lower-camel-filter-parameters parameters))
             ,url))))
</enscript>
==== {{twilio-sms}}
<procedure>(twilio-sms text #!key to from action method status-callback) → STwiML</procedure>
Send an SMS; see [[http://www.twilio.com/docs/api/twiml/sms]].
; text : The text to send
; to : The number to send it to
; from : The number to send it from
; action : Action URL
; method : {{POST}} or {{GET}} for {{action}}
; status-callback : Status callback URL
<enscript highlight="scheme">(define (twilio-sms text #!key to from action method status-callback)
  (let* ((parameters
           (lower-camel-filter-parameters
             `((to ,to)
               (from ,from)
               (action ,action)
               (method ,method)
               (status-callback ,status-callback)))))
    (if (null? parameters)
      `(Sms ,text)
      `(Sms (,(string->symbol "@")
             ,@(lower-camel-filter-parameters parameters))
            ,text))))
</enscript>
=== About this egg

==== Author

[[/users/klutometis|Peter Danenberg]]
==== Repository
[[https://github.com/klutometis/twilio]]
==== License
BSD
==== Dependencies
* [[debug]]
* [[htmlprag]]
* [[http-client]]
* [[matchable]]
* [[s]]
* [[setup-helper]]

==== Versions
; [[https://github.com/klutometis/twilio/releases/tag/0.1|0.1]] : First release: calls and SMS
; [[https://github.com/klutometis/twilio/releases/tag/0.2|0.2]] : Some Twilio verbs
; [[https://github.com/klutometis/twilio/releases/tag/0.2.1|0.2.1]] : Accomodate no parameters.
==== Colophon

Documented by [[/egg/cock|cock]].