Subscribe to KAZOO events

This API provide a way to subscribe to KAZOO event using binding and receive them on websoxckert message in real time. Effectively this API provides an AMQP->Websocket bridge, providing you with real-time event streams about calls, API changes, and more.

Authorization

Some events may need to check if you are authorized to access to event binding or not, please check the event documentation for more info.

Request Payload

This is common a request to either subscribe or unsubscribe actions.

See Binding string syntax below to learn about the format of binding string.

Key	Description	Type	Default	Required
action	to subscribe or unsubscribe	`string(‘subscribe'	'unsubscribe’)`
data.account_id	The account ID to use for binding	string()		false
data.binding	Binding string to use	string()		false
data.bindings	A list of bindings to use	array(string())		true

Please note:

• If no data.account_id is present, the account_id from your auth_token will be used instead.
• data.binding will be picked first over data.bindings in case both are present.

List of events

• app_event
• call
• conference
• fax
• live
• object
• presence

Response payload message

{
    "action": "reply",
    "request_id": "{REQUEST_ID}",
    "status": "success",
    "data": {
        "subscribed": "SUBSCRIBED_KEY",
        "subscriptions": [
            "{ALL_SUBSCRIPTIONS}"
        ]
    }
}

Event payload message

After you subscribe to events the Blackhole application will listen for those events from AMQP. It will send an event to you through Websockets if there is an active binding that matches this event.

Events are plain AMQP event messages.

{
    "action": "event",
    "subscribed_key": "{SUBSCRIBED_KEY}",
    "subscription_key": "{SUBSCRIPTION_KEY}",
    "name": "{NAME}",
    "routing_key": "AMQP_ROUTING_KEY",
    "data": "{EVENT_AMQP_PAYLOAD}"
}

Binding string syntax

The binding syntax is the same used throughout all KAZOO, since it is the same as AMQP’s binding syntax.

Each binding is consist of multiple slots (or segments) separated by dot ., like call.CHANNEL_CREATE.*. Each slot is matches one slot in the event’s routing key.

The are two specical characters:

• * in a slot matches exactly one slot with any value
• # in a slot matches zero or more slots with any value

Here are some examples:

• call.CHANNEL_CREATE.123qweasdzxc will matches call’s CHANNEL_CREATE event with Call-ID 123qweasdzxc.
• call.CHANNEL_CREATE.* will matches all call’s CHANNEL_CREATE events (with any Call-ID)
• app_event.mychatapp.room.123.# will matches all app_event for mychatapp.room.123 event with any possible remaining slots in routing keys (like app_event.mychatapp.room.123.message.qaz)

Some examples of subscribe or unsubscribe

// For one use: binding
// Binding to edit event of user documents
send({
    action: 'subscribe',
    auth_token: '{AUTH_TOKEN}',
    request_id: '{REQUEST_ID}',
    data: {
        account_id: '{ACCOUNT_ID}',
        binding: 'doc_edited.*.user.*'
    }
});

// For multiple use: bindings
// Binding to edit or deletion events of user documents
send({
    action: 'subscribe',
    auth_token: '{AUTH_TOKEN}',
    request_id: '{REQUEST_ID}',
    data: {
        account_id: '{ACCOUNT_ID}',
        bindings: ['doc_edited.*.user.*', 'doc_deleted.*.user.*']
    }
});

You can also add a friendly name and some metadata to any subscribe command.

send({
    action: 'subscribe',
    auth_token: '{AUTH_TOKEN}',
    request_id: '{REQUEST_ID}',
    data: {
        account_id: '{ACCOUNT_ID}',
        name: "My new socket",
        metadata: {
            test: "test"
        },
        binding: 'doc_edited.*.user.*'
    }
});

To remove bindings use unsubscribe event:

send({
    action: 'unsubscribe',
    auth_token: '{AUTH_TOKEN}',
    request_id: '{REQUEST_ID}',
    data: {
        account_id: '{ACCOUNT_ID}',
        binding: 'call.CHANNEL_CREATE.*'
    }
});