Wipple CPaaS
Menu
Guide
Introduction Getting started
Functions
Overview Agent Alert Answer Conference Config Dequeue Dial Dialogflow DTMF Dub Enqueue Gather Hangup Leave Listen LLM Pause Play Rasa Recognizer Redirect Say SIP Decline SIP Refer SIP Request Synthesizer Tag Transcribe Transfer
REST API
About the REST API Create a call List calls Get a call Update a call Delete a call Get call count List conferences Start conference listen Stop conference listen List queues
Webhooks
Overview New Call (POST) New Call (GET) Client Authentication Client Tool Request
Guide / Introduction

Wipple CPaaS Developer Guide

Wipple CPaaS is the programmable voice platform provided by Miraicom Inc. It lets you control telephone calls from your own web application using simple JSON instructions, and manage calls from your back-end through a REST API.

This documentation is written for developers who build voice applications on Wipple CPaaS. It covers three areas:

Section What it describes
Functions The JSON instructions ("Functions") that tell the platform what to do with a call: play audio, collect digits or speech, dial another party, run an AI voice agent, and so on.
REST API HTTP endpoints for creating outbound calls, updating or ending calls in progress, and inspecting conferences and queues.
Webhooks The HTTP requests that Wipple CPaaS sends to your application when a call arrives, when a SIP client registers, and when an AI agent invokes a client tool.

How Wipple CPaaS works

  1. A phone number (or a SIP user) on your account is assigned to an application.
  2. When a call arrives, Wipple CPaaS sends a webhook (or opens a WebSocket connection) to the URL configured on that application.
  3. Your application replies with a JSON array of Functions. Wipple CPaaS executes them in order.
  4. Many Functions report their result back to your application through an action hook. Your reply to that hook may contain further Functions, so the conversation continues for as long as you like.
  5. To place a call from your own system, call the Create a call REST endpoint. Once the called party answers, the flow continues exactly as for an inbound call.

Every JSON payload, whether it is delivered over HTTP or over a WebSocket, has the same structure. You can build your application in any language or framework that can serve HTTP requests.

Key concepts

Account Your tenant on the platform. Every REST request is scoped by the account identifier (AccountSid), and every webhook carries the account_sid of the account the call belongs to.

API key A bearer token used to authenticate REST API requests. Keep it secret; it grants full control over the calls on your account.

Application A named configuration that ties a call to your code. It holds the call hook URL (where new calls are announced), the call status hook URL (where call status changes are reported), and default speech settings (text-to-speech and speech-to-text vendor, language and voice).

Phone number A telephone number provisioned on your account and routed to an application. Sample numbers in this documentation use the fictitious range +81 50 9999 XXXX; they are not real numbers.

Carrier A SIP trunk that connects Wipple CPaaS to the public telephone network or to another SIP platform. Outbound calls to telephone numbers are sent through one of your carriers.

SIP user A SIP or WebRTC client that registers directly with your account's SIP realm. Registered users can be called with the user target type of the dial Function.

Call SID A unique identifier assigned to every call leg. It is included in every webhook and is the key you use in the REST API to update or end a call.

Function One instruction in the JSON array your application returns. For compatibility, the property that names the Function is called verb in the JSON payload (for example {"verb": "say", "text": "Hello"}).

A first look at an application

The following response answers a call, greets the caller, collects a single digit, and posts the result to /menu on your server:

[
  {
    "verb": "gather",
    "actionHook": "/menu",
    "input": ["digits"],
    "numDigits": 1,
    "say": {
      "text": "Thank you for calling Miraicom. For sales press 1. For support press 2."
    }
  }
]

When the caller presses a key, Wipple CPaaS sends a POST request to /menu with the collected digit. Your reply might then dial a sales representative:

[
  {
    "verb": "dial",
    "callerId": "+815099990001",
    "target": [
      { "type": "phone", "number": "+815099990002" }
    ]
  }
]

Conventions used in this documentation

  • {API_ENDPOINT} stands for the host name of the Wipple CPaaS API endpoint assigned to you. Replace it with the value provided in your service information.
  • {yourserver} stands for the public host name of your own application.
  • Telephone numbers such as +815099990001 and names such as "Miraicom Taro" are fictitious samples.
  • Some examples show Functions using a chained JavaScript style (session.say({...}).send()) rather than raw JSON. Both notations produce the same JSON payload; the JavaScript style is simply how the Node.js client library expresses it.

Where to go next

  • Getting started walks through receiving your first call and placing your first outbound call.
  • Functions overview explains the JSON message structure and how Functions are nested and sequenced.
  • About the REST API describes authentication and response conventions.
Getting started →