Call Control Verbs

Call control verbs are returned from 3rd party REST endpoints to control the flow of a call dynamically. We expect a JSON response as an array. Here is an example which returns some text to speech and then plays a beep:

[
    {
        "say" : {
            "text" : [
                "Welcome to callable!",
                "Have a great day!"
            ],
            "loop" : 1,
            "voice" : "en-GB-Standard-A"
        }
    },
    {
    "play" : {
        "url" : "https://recordable.io/sounds/beep.mp3",
        "loop" : 1
    }
]

To determine how your software responds, you will need to know some information about the call. We POST the following minimal payload to your registered webhook:

{
    "callId":"6624872eb9991b38efa4d444",
    "from":"441234567890",
    "to":"441234567891",
    "digits":"",
    "speech":"",
    "action":"start"
}

To enable a 3rd party webhook, choose Control - Generic from the webhook list when creating a new webhook

The webhook then needs to be assigned to the call flow using a plugin to reference it.

Then include the plugin as part of the call flow.

The Verbs

The following are the set of valid verbs that can be returned as part of an array. The verbs are read sequentially.

Dial

Dial an endpoint

{
    "dial" : {
        "callerId" : "+441234567890",
        "timeout" : 30,
        "timeLimit" : 14400,
        "record" : { ... },
        "targets" : [ ... ]
    }
}

Record Verb

By including an empty Record verb you can opt in to call recording. Adding a URL will stream raw audio to a websocket endpoint

{
    "dial" : {
        ...
        "record" : {
            "url" : "http://www.recordable.io/ws",
            "username" : "user",
            "password" : "password",
        }
    }
}

Dial Targets

Device

Target a static Flow Device Endpoint

{
    "device" : {
        "id" : "3334872eb9991b38efa4d999"
    }
}

SIP URI

Target a SIP URI

{
    "sipURI" : {
        "uri" : "sip:1234@1.1.1.1:5060"
    }
}

Phone Number

Target a Phone Number, internal routing logic will be applied to this target

{
    "phoneNumber" : {
        "number" : "+441234567891"
    }
}

Extension

*Target an extension/ddi on a Static Flow endpoint, for example sending to extension 600 on a registered client 201 *

{
    "extension" : {
        "extension" : "201",
        "overrideTo" : "600"
    }
}

Say

Text to speech

{
    "say" : {
        "text" : [
            "Welcome to callable!",
            "Have a great day!"
        ],
        "loop" : 1,
        "voice" : "en-GB-Standard-A"
    }
}

Play

Play an MP3 or WAV

{
    "play" : {
        "url" : "https://recordable.io/sounds/beep.mp3",
        "loop" : 1
    }
}

Gather

Wait for input from caller

{
    "gather" :    {
        "input" : ["digits", "speech"],
        "finishOnKey" : "#",
        "numDigits" : 1,
        "timeout" : 10,
        "say" : { ... },
        "play" : { ... },
        "hints" : [ "never" , "eat", "yellow",  "snow" ],
        "language" : "en-GB",
        "redirect" : { ... }
    }
}

Redirect

Redirect to a Static Flow component

{
    "device" : {
        "id" : "3334872eb9991b38efa4d999"
    }
}

Tag

Tag a call for contextual information

{
    "tag" : {
        "data" :  { "tag1", "hey", "tag2" , "yo"  }
    }
}

Hangup

Hangup the call

{
    "hangup" : {
        "reason" :  "call completed"
    }
}

Hangup

Rejecting the call

{
    "hangup" : {
        "reason" :  "call completed"
    }
}