GuidesYour own stack

Vonage

Two URLs on the voice application. Every call is scored before your agent hears it, and on Guard a caller who looks wrong is asked to press a digit first.

How it works

Vonage asks the application's answer URL what to do with an incoming call and expects an NCCO back. You point that URL at us. We record the call, score it, and answer with an NCCO: either connect the call to your agent, or first ask the caller to press a digit. Vonage runs the NCCO on your account at your normal rates. We never touch the audio.

One difference from Twilio

Vonage cannot hand a call to another URL, so the destination after the gate has to be a phone number or a sip: address, typically your agent's SIP URI. Everything else is the same as Twilio.

Setting it up

Add the number in Murusai

Numbers → Add a number. Pick Vonage as the carrier and set the destination to a phone number or SIP address. Or by API:

RequestShell

curl -X POST https://api.murusai.com/v1/numbers \
  -H "Authorization: Bearer $MURUSAI_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "number": "+14155550100",
    "gate_provider": "vonage",
    "gate_mode": "adaptive",
    "gate_destination": "sip:agent@sip.example.com"
  }'

A URL here is refused with 400 vonage_needs_phone_or_sip. The response carries a gate_token: the credential in the URLs below.

Point the application at us
Vonage dashboard → Applications → your voice application → Voice capability.
Answer URLGET or POST
https://api.murusai.com/v1/vonage/answer/gt_…
Event URLPOST
https://api.murusai.com/v1/vonage/event/gt_…, so we learn when the call ended.
Then link the number to the application, if it is not already. The dashboard shows both URLs filled in on the number's page.
Choose a mode
off scores and connects everyone; adaptive challenges a call that scores review or reject, and challenges everyone for thirty minutes after a reject; always challenges everyone. Same as Twilio.
Make a test call
Ring the number. Set always for a moment to hear the challenge yourself, then put it back.

The NCCOs

A single digit, one to nine, pressed or spoken. Two attempts, six seconds each; a right answer faster than a person could have heard the prompt is treated as a machine.

What Vonage receives · challengeJSON

[
  {
    "action": "talk",
    "text": "Quick check. Press or say 4 to be connected.",
    "language": "en-US",
    "bargeIn": true
  },
  {
    "action": "input",
    "type": ["dtmf", "speech"],
    "dtmf": { "maxDigits": 1, "timeOut": 6 },
    "speech": {
      "endOnSilence": 1.5,
      "language": "en-US",
      "context": ["one", "two", "three", "four", "five", "six", "seven", "eight", "nine"]
    },
    "eventUrl": ["https://api.murusai.com/v1/vonage/input/gt_…?attempt=1&expected=4"],
    "eventMethod": "POST"
  }
]

What Vonage receives · connectJSON

[
  {
    "action": "connect",
    "endpoint": [{ "type": "sip", "uri": "sip:agent@sip.example.com" }],
    "timeout": 45,
    "from": "14155550100"
  }
]

What Vonage receives · refusedJSON

[
  { "action": "talk", "text": "Sorry, we couldn't verify this call. Goodbye." }
]

A caller who fails both attempts is blocked on your account, the call is ended with reason gate_fail or gate_timeout, and a caller.rate_exceeded alert goes out with gate: "failed".

On Watch and on Guard

On Watch the gate is off: every call is scored and recorded, with alerts, and connected straight through. adaptive and always need Guard.

Rotating the token

Remove the number and add it again: a new token is issued and the old URLs stop working at once. The number's history stays.