Jump to content
  • PBXWebRequest


    Lua   → VBScript   SwxWare v13.10


    In order to communicate from ECR scripts with web services of all kinds, the Lua integration offers a dynamically embeddable module based on the proven curl library. This module is not loaded by default because this does not unnecessarily increase the resource requirements of the Lua runtime environment.

    Functions offered by this module


    • Execute all well-known request types:
    • Support of most common HTTP-Auth methods:
      Basic, Digest und Bearer
    • Add any header to the request in text form
    • Add any URL parameter with build-in escaping
    • Retrieve all header from requests and reponses
    • Automatic conversion of the response body to a Lua string based on the 'Contenttype' header


    Requests can be made either via encrypted or unencrypted connections. This is selected by URL ("https:// ..." oder "http:// ...").


    In addition, certificate validation can be disabled in the case of internal web services with self-signed certificates.



    Howto use the module


    The integration into an ECR script is done with the usual Lua mechanism by means of the keyword 'require' placed in an 'InsertScript'-Block


    local webreq = require "PBXWebRequest"


    The webreq object now can be used to create one or more independent HTTP session objects. New HTTP session objects are preset to HTTP Verb GET with no authentication and certification validation is active.


    Additional note: the webreq should always be checked for 'nil' to avoid potential run-time errors.

    if (webreq ~= nil) then
    	local hsession1, hsession2
    	hsession1 = webreq.new()
    	hsession2 = webreq.new() -- a second HTTP Session object to perform an additional query in parallel



    Here is an example as overview - the detailed description of the API can be found below this example.


    local webreq = require "PBXWebRequest"
    if (webreq ~= nil) then
        local hsession, reponseCode, responseHeaders, encodedURL
        PBXScript.OutputTrace("Web request loaded...")
        hsession = webreq.new()
        hsession:AddHeader("Content-Type:application/json; charset=UTF-8")
        hsession:AddQueryPair("artist", "Simon & Garfunkel")
        hsession:AddQueryPair("callid", PBXCall.CallId())
        hsession:AddQueryPair("callernumber", PBXCall.CallingPartyNumber())
        hsession:AddQueryPair("callername", PBXCall.CallingPartyName())
        -- hsession:HttpAuth = HttpAuthBasic
        -- hsession:AuthUser = "foo"
        -- hsession:AuthPass = "bar"
        requestHeaders = hsession:RequestHeaders()
        for i = 1, #requestHeaders do
           PBXScript.OutputTrace(" [" .. i .. "] " .. requestHeaders[i])
        responseCode = hsession:Execute()
        PBXScript.OutputTrace("Web request response " .. responseCode)
        if (responseCode == 200) then
            responseHeaders = hsession:ResponseHeaders()
            for i = 1, #responseHeaders do
               PBXScript.OutputTrace(" [" .. i .. "] " .. responseHeaders[i])


    A complete usage example can be found in the Zendesk Integration project (incl. Json formatted data handling), which is part of the Open ECR Extensions project here on Swyx Forum.


    Another more simple example is the LaunchHTTPRequest() function from the Function Collection.



    Description of WebReq Object API

    Some enum values used as parameter


    HTTP Verbs

    PBXHttpVerbGetto   execute a GET request  (default)

    PBXHttpVerbPost   to execute a POST request

    PBXHttpVerbPut   to execute a PUT request

    PBXHttpVerbDelete   to execute a DELETE request

    PBXHttpVerbPatch   to execute a PATCH request

    PBXHttpVerbHead   to execute a HEAD request


    HTTP Authentication

    PBXHttpAuthNone   no authentication used for request (Default)

    PBXHttpAuthBasic   HTTP basic authentication by username and password according to RFC7617

    PBXHttpAuthDigest   HTTP digest authentication by username and password according to RFC7616

    PBXHttpAuthBearer   HTTP bearer authentication by OAuth 2.0 bearer access token provided via password property

    PBXHttpAuthAny   automatic negotiation which authentication mechanism to use



    API Methods

    The following methods set the respective value when it is passed as a parameter, or return the current value set if the method is called without parameters. Note: all examples assume a HTTP session variable with the name hsession!


    HttpVerb(<verb enum>)

    Set HTTP Verb by enum value.

    To set:


    To retrieve:

    verb = hsession:HttpVerb()

    HttpAuth(<auth enum>)

    Set HTTP authentication method to use.

    To set:


    To retrieve:

    auth = hsession:HttpAuth()


    AuthUser("<user name>")

    Set user name to use with authentication.

    To set:

    hsession:AuthUser("<user name>")

    To retrieve:

    user = hsession:AuthUser()



    Set password to use with authentication.

    To set:


    To retrieve:

    password = hsession:AuthPass()



    Activate or deactivate validation of TLS certificate. 'true' = check is active, 'false' = check is deactivated.



    Url("<url string >")

    Sets the URL for the request. The choice between encrypted or unencrypted is made via the URL in the form "https:// ..." oder "http:// ...".

    To set:


    To retrieve:

    url = hsession:URL()



    Additional functions


    UrlEncode("<string to encode>")

    Convert given string according to URL escaping rules as of https://en.wikipedia.org/wiki/URL-Encoding

    Return value: string URL encoded

    url_encoded = hsession:URLEncode("Dörte Weiß sucht das Glück")


    AddHeader("<header string>")

    Sets any header as text

    Return value: none

    hsession:AddHeader("Content-Type:application/json; charset=UTF-8")


    AddQueryPair("<key>", "<value>")

    Set key/value pair to use in request URL

    Return value: none

    hsession::AddQueryPair("artist", "Simon & Garfunkel")


    RequestBody("<body text>")

    Sets any request body text or returns the currently set text (blank string if no text has been set)

    To set:

    hsession:RequestBody("<h1>My body text</h1>")

    To retrieve:

    body = hsession:RequestBody()



    Return current list of request header(s) as Lua table or nil.
    No input parameter supported!

    Return value: Lua table or 'nil'

    headers = hsession:RequestHeaders()



    Return last response body text or blank string.
    No input parameter supported!

    respBody = hsession:ResponseBody()



    Return current list of response header(s) as Lua table or nil.
    No input parameter supported!

    Return value: Lua table or 'nil'

    respBody = hsession:ResponseHeaders()



    Execute web request with given parameters.
    No input parameter supported!

    Return value: response code from request as number. Will be 200 on successful request or any value according to HTTP spec.

    resp = hsession:Execute()



    Resets the HTTP Session object back to its initial state. The HTTP verb is GET without authentication and certificate validation is enabled.

    Return value: none






    To diagnose a problem the following trace modules of SwyxWare-Server can be used:

    • SrvScrAPI            set to 6 to get detailed tracing for API calls
    • SrvScrWeb          set to 6 to get detailed tracing for any web request



    Final notes


    • Two timeout values are fixed and can‘t be changed dynamically:
      Maximum time for establishing a connection to the web service is 10s.
      Maximum time for web service to respond is 10s
    • The http proxy settings are read and applied by the system.



    Tom Wellige


  • Create New...

Important Information

By using this site, you agree to our Terms of Use and have taken note of our Privacy Policy.
We have placed cookies on your device to help make this website better. You can adjust your cookie settings, otherwise we'll assume you're okay to continue.