Interactive Voice Response API

The following section describes the API calls required to create, modify, list and delete IVRs. As with other API calls, the IVR API also requires a valid and authenticated user session.

An IVR is defined by the actions to execute once a DTMF signal is received. IVRs can be cascaded to allow multiple levels.

API Call Reference

/api/ivr

POST /api/ivr

Creates a new IVR and returns the uuid of the newly created IVR.

Request body example

{
    "description" : "Company Welcome",
    "announcement" : "ce19884c-8fed-11e2-93fe-0024e8f90cc1",
    "1" : "ce19884c-8fed-11e2-93fe-0024e8f90cc2",
    "2" : "ce19884c-8fed-11e2-93fe-0024e8f90cc3",
    "4" : "+4922116696000",
    "*" : "ce19884c-8fed-11e2-93fe-0024e8f90cc5",
    "other" : "repeat",
    "timeout" : {
        "seconds": 10,
        "action": "play",
        "announcement": "ce19884c-8fed-11e2-93fe-0024e8f90cc2"
    }
}
JSON Parameters:
 
  • description –

    ^.{1,200}$

    mandatory: A user-given description for the IVR.

  • announcement –

    UUID

    mandatory: The initial announcement to be played at the beginning.

  • [0-9*#] –

    UUID | ^\\+[0-9]{3,20}$

    mandatory: at least one field with a valid DTMF digit must be given. A valid DTMF must be one of [0, 1, 2, 3, 4, 5, 6, 7, 8, 9, #, *]. Each field defines the action to proceed if this DTMF is received:

    • an UUID - a new IVR whose UUID is given will run.
    • a phone number - the call will be redirected to the given phone number.
  • other –

    repeat | ^\\+[0-9]{3,20}$

    optional: define the action to execute if an unspecified DTMF signal is received:

    • repeat - the initial announcement will be repeated.
    • a phone number - the call will be redirected to the given phone number
  • timeout – optional: this block defines what happens if no DTMF signal was received for a certain amount of time.
  • timeout.seconds –

    integer > 0

    mandatory: the timeout duration in seconds.

  • timeout.action –

    repeat | call | play

    mandatory: define the action to proceed after a timeout from the end of the announcement without receiving a DTMF already defined in this IVR.

    • repeat - the IVR will be repeated.
    • call - the call will be redirected.
    • play - an other announcement will be played.
  • timeout.phone –

    ^\\+[0-9]{3,20}$

    mandatory if action is call: the phone number to call.

  • timeout.announcement –

    UUID

    mandatory if action is play: the announcement to be played.

Response body example

{
    "uuid": "ce19884c-8fed-11e2-93fe-0024e8f90cc0"
}
POST /api/ivr/(uuid)

Updates an existing IVR.

Request body example

For the description of the request body see POST /api/ivr

Response body example

{}
Status:
  • wrong-ivr: The IVR with ID uuid does not exist or does not belong to the user.
GET /api/ivr

Lists the current user’s IVRs.

Query Parameters:
 
  • from – optional: start time, in seconds-since-epoch (must have from <= to)
  • to – optional: end time, in seconds-since-epoch (must have from <= to)
  • start –

    optional: the UUID of the first IVR to return, exclusive, i.e. the IVR with an exact match UUID is not returned.

    If given, overrides the from parameter when asc order is selected or overrides the to parameter when desc order is selected.

  • order –

    optional: If set to asc (default), IVRs are returned in time ascending order (i.e. starting with from or start and ending with stop).

    If set to desc, IVRs are returned in time descending order (i.e. starting with to or start and ending with from).

  • count – optional, default 30: limits the number of returned IVRs (valid range: 1...500)

Response body example

{
    "ivr" : [
        {
            "description" : "Company Welcome",
            "uuid" : "db19884c-8fed-11e2-93fe-0024e8f90aa3"
        },
        {
            "description" : "Company Support",
            "uuid" : "cd19882b-8fed-11e2-93fe-0024e8f90ab2"
        }
    ]
}
GET /api/ivr/(uuid)

Gets the details of the specified IVR.

Response body example

{
    "ivr" : {
        "description" : "Company Welcome",
        "announcement" : "ce19884c-8fed-11e2-93fe-0024e8f90cc1",
        "1" : "ce19884c-8fed-11e2-93fe-0024e8f90cc2",
        "2" : "ce19884c-8fed-11e2-93fe-0024e8f90cc3",
        "4" : "+4922116696000",
        "*" : "ce19884c-8fed-11e2-93fe-0024e8f90cc5",
        "other" : "repeat",
        "timeout" : {
            "seconds": 10,
            "action": "play",
            "announcement": "ce19884c-8fed-11e2-93fe-0024e8f90cc2"
        }
    }
}
Status:
  • wrong-ivr: The IVR with ID uuid does not exist or does not belong to the user.
DELETE /api/ivr/(uuid)

Deletes the specified IVR.

Response body example

{}
Status:
  • wrong-ivr: The IVR with ID uuid does not exist or does not belong to the user.