Request

Let us take a deep dive into the request method. Using this method, you can send HTTP requests to a web server open to internet. It is a simple but powerful way to add all kinds of external functionality to SWML scripts.

Reference available

This is a guide for the request method. The reference for this method can be found in here.

We will start by pulling a random dad joke from the internet and reading it out loud to the user.

YAML

version: 1.0.0
sections:
  main:
    - answer: {}
    - play:
        url: 'say:Hello! I can tell you a random dad joke. Please wait a moment.'
    - request:
        url: 'https://icanhazdadjoke.com/'
        method: GET
        headers:
          Accept: application/json
        save_variables: true
    - play:
        url: 'say:%{request_response.joke}'
    - hangup: {}

JSON

{
  "version": "1.0.0",
  "sections": {
    "main": [
      {
        "answer": {}
      },
      {
        "play": {
          "url": "say:Hello! I can tell you a random dad joke. Please wait a moment."
        }
      },
      {
        "request": {
          "url": "https://icanhazdadjoke.com/",
          "method": "GET",
          "headers": {
            "Accept": "application/json"
          },
          "save_variables": true
        }
      },
      {
        "play": {
          "url": "say:%{request_response.joke}"
        }
      },
      {
        "hangup": {}
      }
    ]
  }
}

The following points should be noted:

1. After answering the phone call and playing a short welcome message, we request a joke from the website icanhazdadjoke.com.

2. We specifically state that we want the response to be in JSON format using the Accept header.

3. We have set the save_variables option to be true. SWML can parse the JSON response for you and save all the response objects into a variable named request_response.

4. The server gives back a JSON object in the form:

   {
     "id": "HlGlbFdiqjb",
     "joke": "Why don't eggs tell jokes? They'd crack each other up",
     "status": 200
   }

   We read aloud the joke property of the response JSON using the play method.

Sending POST request

Let us send some information to the server using a POST request.

YAML

version: 1.0.0
sections:
  main:
    - answer: {}
    - prompt:
        play: 'say: Enter PIN'
        max_digits: 4
        terminators: '#'
    - request:
        url: 'https://reqres.in/api/users'
        method: POST
        save_variables: true
        body:
          pin: '%{prompt_value}'
    - play:
        url: 'say:Pin set to: %{request_response.pin}'
    - hangup: {}

JSON

{
  "version": "1.0.0",
  "sections": {
    "main": [
      {
        "answer": {}
      },
      {
        "prompt": {
          "play": "say: Enter PIN",
          "max_digits": 4,
          "terminators": "#"
        }
      },
      {
        "request": {
          "url": "https://reqres.in/api/users",
          "method": "POST",
          "save_variables": true,
          "body": {
            "pin": "%{prompt_value}"
          }
        }
      },
      {
        "play": {
          "url": "say:Pin set to: %{request_response.pin}"
        }
      },
      {
        "hangup": {}
      }
    ]
  }
}

Using your own server

So far, we have used publicly available test REST API. You can also write your own web server, and interact with that using the request method.

An example server in Flask (Python) and Express (Node.js) is presented below:

Python/Flask

from flask import Flask, request
from waitress import serve

app = Flask(__name__)

@app.route("/", methods=['POST'])
def swml():
    body = request.get_json(silent=True)
    print(body)

    # TODO: process body
    result = body
    return result

if __name__ == "__main__":
    serve(app, host='0.0.0.0', port=6000)

JavaScript/Express

const express = require("express");
const app = express();

app.use(express.json());

// note the POST method
app.post("/", (req, res) => {
  const body = req.body;
  console.log(body);
  // TODO: process body
  const result = body;
  res.json(result);
});

const port = 6000;
app.listen(port);

tip

If you need help opening up this web server from your localhost to the wider internet where SWML execution system can find it, please follow this ngrok guide.

Once this web server is up, you can write SWML to access this service.

YAML

version: 1.0.0
sections:
  main:
    - answer: {}
    - prompt:
        play: 'say: Enter PIN'
        max_digits: 4
        terminators: '#'
    - request:
        url: 'https://<uuid>.ngrok-free.dev'
        method: POST
        save_variables: true
        body:
          pin: '%{prompt_value}'
    - play:
        url: 'say:Pin set to: %{request_response.pin}'
    - hangup: {}

JSON

{
  "version": "1.0.0",
  "sections": {
    "main": [
      {
        "answer": {}
      },
      {
        "prompt": {
          "play": "say: Enter PIN",
          "max_digits": 4,
          "terminators": "#"
        }
      },
      {
        "request": {
          "url": "https://<uuid>.ngrok-free.dev",
          "method": "POST",
          "save_variables": true,
          "body": {
            "pin": "%{prompt_value}"
          }
        }
      },
      {
        "play": {
          "url": "say:Pin set to: %{request_response.pin}"
        }
      },
      {
        "hangup": {}
      }
    ]
  }
}