CPaaS verbs

Interaction model

Session Router sends call events to application hooks. When an HTTP hook returns a positive response with a non-empty body, the body can contain a JSON array of verb objects. Each object must include a verb property. Verbs are parsed and executed in array order.

[
  {
    "verb": "say",
    "text": "Welcome to Session Router."
  },
  {
    "verb": "pause",
    "length": 1
  },
  {
    "verb": "hangup"
  }
]

• An empty action array ends the call with a no-verbs condition.
• Unknown verbs are skipped during parsing. If no recognized verbs remain, the call is ended.
• redirect stops parsing the current array and asks another hook for the next instructions.
• gather, dial, sip:request, and listen can alter flow depending on runtime result.

Webhook behavior

Event payload fields

Hook payloads include call identity, event name, direction, call status, SIP header summary, caller identity, queue fields, and customer metadata. Exact fields depend on the event and verb result.

Supported verbs

These verbs are parsed and have meaningful runtime handlers in the current implementation.

answer

Answers the current inbound call. If the call is already established, it continues immediately.

[
  {
    "verb": "answer"
  }
]

say

Speaks text into the call using TTS. The runtime supports Azure/Microsoft, ElevenLabs, and Deepgram TTS paths, depending on configured credentials.

[
  {
    "verb": "say",
    "text": "Your call is now connected.",
    "loop": 1,
    "synthesizer": {
      "vendor": "microsoft",
      "language": "en-US",
      "voice": "en-US-JennyNeural"
    }
  }
]

play

Plays one or more WAV/MP3 URLs into the call. Completion or interruption can generate a call event.

[
  {
    "verb": "play",
    "url": ["https://example.com/audio/welcome.wav"],
    "loop": 1,
    "timeoutSecs": 30,
    "dtmfInterrupt": true
  }
]

gather

Collects DTMF digits, speech, or both. It can play a nested prompt using say or play, then reports the result to actionHook.

[
  {
    "verb": "gather",
    "input": ["digits"],
    "numDigits": 1,
    "timeout": 10,
    "interDigitTimeout": 5,
    "finishOnKey": "#",
    "includeFinishKey": false,
    "dtmfBargein": true,
    "actionHook": "https://example.com/menu-result",
    "say": {
      "text": "Press 1 for sales. Press 2 for support."
    }
  }
]

Speech input example

[
  {
    "verb": "gather",
    "input": ["speech"],
    "timeout": 20,
    "maxSpeechLength": 10,
    "bargein": true,
    "listenDuringPrompt": true,
    "actionHook": "https://example.com/speech-result",
    "recognizer": {
      "vendor": "deepgram",
      "language": "en-US",
      "model": "nova-2",
      "minConfidence": 0.55
    },
    "say": {
      "text": "Tell me how I can help."
    }
  }
]

dial

Creates an outbound call leg and connects it to the current call. It supports sequential and parallel target attempts and can include a nested listen verb to stream caller audio while dialing.

[
  {
    "verb": "dial",
    "callerId": "+15551234567",
    "answerOnBridge": true,
    "strategy": "sequential",
    "timeout": 30,
    "timeLimit": 3600,
    "targets": [
      {
        "type": "phone",
        "number": "+15557654321",
        "trunk": "main-carrier"
      }
    ],
    "actionHook": "https://example.com/dial-result"
  }
]

Target object

listen

Streams call audio to and/or from a WebSocket media server. The media WebSocket sends an initial JSON start message and binary PCM audio frames.

[
  {
    "verb": "listen",
    "url": "wss://media.example.com/session",
    "direction": "both",
    "audioFormat": "s16le",
    "sampleRate": 16000,
    "outputSampleRate": 16000,
    "channels": 1,
    "actionHook": "https://example.com/listen-ended"
  }
]

dtmf

Sends DTMF digits into the call. The current call must have a negotiated DTMF format, and digits must be in the set 0-9, *, or #.

[
  {
    "verb": "dtmf",
    "dtmf": "123#",
    "duration": 300
  }
]

Duration is in milliseconds. The current runtime default is 300 ms, and values above 8000 ms are capped.

pause, redirect, tag, bridge, hangup

[{ "verb": "pause", "length": 2 }]

[{ "verb": "redirect", "actionHook": "https://example.com/next" }]

[{ "verb": "tag", "data": { "accountTier": "gold", "caseId": "A-1001" } }]

[{ "verb": "bridge", "releaseMedia": false, "actionHook": "https://example.com/bridge" }]

[
  {
    "verb": "hangup",
    "statusCode": 486,
    "q850Code": 17,
    "warning": "Busy"
  }
]

Queue verbs

enqueue

Places the call into a named queue. The runtime answers the call before queueing and requires name, waitHook, and actionHook.

[
  {
    "verb": "enqueue",
    "name": "support",
    "priority": 5,
    "autoHunt": true,
    "waitHook": "https://example.com/queue-wait",
    "actionHook": "https://example.com/queue-result"
  }
]

The wait hook receives Queue State events and may return only say, play, pause, or leave verbs. Session Router repeats the wait hook while the call remains queued and no RTP prompt is active.

leave

Requests that the current queued call leave the queue.

[{ "verb": "leave" }]

SIP control verbs

sip:request

Sends an in-dialog SIP INFO, NOTIFY, or MESSAGE. Session Router waits for the SIP response and reports the result to actionHook.

[
  {
    "verb": "sip:request",
    "method": "INFO",
    "contentType": "application/json",
    "body": "{\"event\":\"ping\"}",
    "headers": {
      "X-Trace-ID": "abc123"
    },
    "actionHook": "https://example.com/sip-info-result"
  }
]

• Only INFO, NOTIFY, and MESSAGE are accepted.
• Use exactly one of body or bodyBase64 when sending content.
• SDP, arbitrary XML, and unclassified content types are rejected by the current handler.

sip:refer

Sends an in-dialog SIP REFER. The runtime reports the REFER response to actionHook, then can report REFER NOTIFY events. Provisional NOTIFY statuses go to eventHook; final NOTIFY statuses go to actionHook.

[
  {
    "verb": "sip:refer",
    "referTo": "sip:agent@example.com",
    "referredBy": "sip:caller@example.com",
    "actionHook": "https://example.com/refer-result",
    "eventHook": "https://example.com/refer-progress"
  }
]

Unsupported or partial paths