Functions overview

Reference for every Wipple CPaaS Function used to control calls, from dial and gather to transcribe and listen. See syntax, parameters, and usage examples.

Functions are the fundamental building blocks of your Wipple CPaaS application; they instruct the platform how to handle the call.

Note

In the JSON payload each Function is identified by a property named verb (for example "verb": "say"). The property name is kept for API compatibility; throughout this documentation the instructions themselves are called Functions.

Some examples on the Function pages are written in a chained JavaScript style such as session.say({ text: "hello" }).send(). This is the notation of the Node.js client library and produces exactly the same JSON as the raw form shown here.

Interaction

Wipple CPaaS controls calls through the use of JSON payloads that are exchanged either over an webhook or a websocket connection.
When an incoming call for your account is received, Wipple CPaaS retrieves the URL that you have configured for the application you want to run.
If the URL begins with 'http(s)://' Wipple CPaaS makes an http request to the URL, while if the URL starts with 'ws(s)://' Wipple CPaaS establishes a websocket connection to that URL. Wipple CPaaS then sends an initial message describing the incoming call, and your webapp is then responsible for returning a JSON payload that indicates how you want the call handled.

Either way (http or websocket) the details of the JSON payloads are the same.

When an incoming call for your account is received, Wipple CPaaS makes an HTTP request to a URL that you have configured and your webapp will then return a response containing a JSON body that indicates how you want the call handled.

If you want to generate an outbound call it works similarly: you will make an HTTP request using the REST API and in it you will specify a URL or application identifier that will be invoked once the call is answered. Once again, your response to that HTTP request will contain a JSON body that indicates how you want the call handled.

Basic JSON message structure

The JSON payload that you provide in response to an HTTP request must be an array with each item describing a task that the platform shall perform. These tasks are executed sequentially in the order they appear in the array. Each task is identified by a Function name in the verb property (e.g. "dial", "gather", "hangup" etc) with associated detail to configure how the action should be carried out.

If the caller hangs up during the execution of an application for that call, the current task is allowed to complete and any remaining tasks in the application are ignored.

[
  {
    "verb": "say",
    "text": "Hi there!  Please leave a message at the tone.",
    "synthesizer": {
      "vendor": "Google",
      "language": "en-US",
      "gender": "FEMALE"
    }
  },
  {
    /* ..next Function */
  }
]

Some Functions allow other Functions to be nested; e.g. "gather" can have a nested "say" command in order to play a prompt and collect a response in one command:

{
  "verb": "gather",
  "actionHook": "/gatherCardNumber",
  "input": ["speech", "dtmf"],
  "timeout": 16,
  "numDigits": 6,
  "recognizer": {
    "vendor": "Google",
    "language": "en-US"
  },
  "say": {
    "text": "Please say or enter your six digit card number now",
    "synthesizer": {
      "vendor": "Google",
      "language": "en-US",
      "gender": "FEMALE"
    }
  }
}

Altogether then, a simple voicemail application could look like this:

[
  {
    "verb": "say",
    "text": "Hi there!  Please leave a message at the tone and we will get back to you shortly."
  },
  {
    "verb": "listen",
    "actionHook": "http://example.com/voicemail",
    "url": "wss://example.com/my-recorder",
    "finishOnKey": "#",
    "metadata": {
      "topic": "voicemail"
    },
    "playBeep": true,
    "timeout": 20
  },
  {
    "verb": "say",
    "text": "Thanks for your message.  We'll get back to you"
  }
]