Skip to content

KAZOO Support Channels

This documentation is curated by 2600Hz as part of the KAZOO open source project. Join our community forums here for peer support. Only features in the space are included as part of our 2600Hz Support Services plan.

Webhooks and Websockets#

About Myself#

  1. About Myself

    • James Aimonetti
    • Kazoo Architect and Community at 2600Hz
    • mc_ on freenode
  2. Presenter


Webhooks - High level#

  • Request events to be sent to your server
  • Read-only
  • AMQP->HTTP bridge
  • Custom webhooks via callflows


  • Simple HTTP request is sent from Kazoo to your server
    • Respond with 200 only (auto-disabled otherwise)
    • If possible, relay data to separate process for use
  • Update rows in a database or spreadsheet
  • Screen pops
  • Use with Pivot to build reactive routing logic

Available Webhooks#

  • Code can be found here
  • Channel events
    • CREATE
    • ANSWER
    • BRIDGE
  • Inbound/outbound faxes

Available Webhooks (cont)#

  • Parked calls
  • Account objects
    • Accounts, callflows, devices, fax boxes, media (MOH, IVR, voicemails), users, voicemail boxes, faxes
    • Created/edited/deleted
    • Billing systems
  • Custom webhooks from callflows
    • Analytics on IVRs

Query for webhooks available#

curl -v -X GET http://{SERVER}:8000/v2/webhooks

Creating a webhook#

curl -v -X PUT \
-H "X-Auth-Token: {AUTH_TOKEN}" \
-H "Content-Type: application/json" \
-d '{"data": {
    "name": "New Calls",
    "uri": "http://{YOUR_SERVER}/calls/new.php",
    "http_verb": "post",
    "hook": "channel_create",
}}' \

Webhook Request#

  • GET: query string parameters
  • POST: x-www-urlencoded-form body
  • Data sent will be the AMQP JSON payload, encoded for the HTTP method chosen
  • No processing of the response (except HTTP response code)

The future of webhooks#

  • Reseller hooks for all sub-accounts
    • Added Oct 6
    • Create one hook, receive events for all sub-accounts
  • Feature requests welcome!


  • Persistent connection
  • Lower overhead (no polling)
  • Get events and issue commands to Kazoo
  • Richer UI interactions with Kazoo (operator console)

Anatomy of websocket connection#

![img](./images/WebSockets-Diagram.png "![img](//")

Create a websocket connection#

  • Ensure blackhole application is running
  • Open a connection

Subscribe for events#

Subscribe for an account's new calls#

Subscribe for multiple types of events#

Subscribe for doc change events#

Unsubscribe from events#

Monster makes this easy#

Monster makes this easy (cont)#

Query for available bindings#

curl -v -X GET http://{CROSSBAR}:8000/v2/websockets | python -mjson.tool
    "data": {
        "call": [
                "binding": "call.CHANNEL_CREATE.*",
                "event": "CHANNEL_CREATE"
                "binding": "call.CHANNEL_ANSWER.*",
                "event": "CHANNEL_ANSWER"
                "binding": "call.CHANNEL_DESTROY.*",
                "event": "CHANNEL_DESTROY"
                "binding": "call.CHANNEL_BRIDGE.*",
                "event": "CHANNEL_BRIDGE"

Event categories available#

  • Channel events
  • Fax events
  • Objects - identical to webhooks

Fetch account's socket connections#

curl -v -X GET \
-H "X-Auth-Token: {AUTH_TOKEN}" \
    "data": [
    "status": "success"

Fetch bindings for a socket ID#

curl -v -X GET \
-H "X-Auth-Token: {AUTH_TOKEN}" \
    "data": [
            "account_id": "{ACCOUNT_ID}",
            "auth_token": "{AUTH_TOKEN}",
            "bindings": [
            "websocket_session_id": "{SOCKET_ID}"
    "status": "success"

Execute commands#

curl -v -X PUT \
    -H "Content-Type: application/json" \
    -H "X-Auth-Token: {AUTH_TOKEN}" \
    -d '{"data": {"action": "metaflow", "data": { "module", "hangup" }}' \

The future#

  • Support sending commands
    • Currently, cb_channels is the way (via metaflows/konami)
    • Pivot over websockets (great idea from yesterday!)
  • More events exposed for building richer UIs
    • Conference events
    • Notifications (vm left, system alerts)

Thank You#