ARI WebSocket Trigger

Subscribe to Asterisk ARI events over WebSocket
Join our community

Overview

This node subscribes to Asterisk ARI (Asterisk REST Interface) events over a WebSocket connection. It enables real-time monitoring and processing of telephony events such as channel state changes, bridge events, recordings, and more from an Asterisk PBX system.

Common scenarios where this node is beneficial include:

  • Monitoring call progress and status in a call center environment.
  • Triggering workflows based on specific telephony events like call answered, hung up, or transferred.
  • Collecting detailed event data for analytics or logging purposes.
  • Detecting agent pickup events with specialized filtering to automate call handling processes.

Practical example:

  • Automatically log all "ChannelCreated" and "ChannelDestroyed" events to track call activity.
  • Trigger a workflow when a recording starts or stops to manage call recordings.
  • Filter and process only agent pickup events to update CRM systems with agent call details.

Properties

Name Meaning
Protocol The WebSocket protocol to use: ws (insecure) or wss (secure).
Host The hostname or IP address of the Asterisk ARI server.
Port The port number on which the ARI WebSocket server listens (1–65535).
Application The ARI application name to connect to (required).
Username Username for ARI authentication (required).
Password Password for ARI authentication (required, hidden input).
Subscribe All Whether to subscribe to all ARI events (true) or not (false).
Event Type Filtering Enable filtering by specific event types (true to enable).
Event Types List of specific ARI event types to process if filtering is enabled. Leave empty to process all events.
Agent Pickup Detection Enable specialized filtering for detecting agent pickup events (true to enable).
Agent Pickup Variables Select which agent pickup-related variables to monitor (e.g., agent extension, queue name). Only shown if Agent Pickup Detection is enabled.
Channel State Filter Filter agent pickup events by channel state: Any State, Up (Answered), Ringing, or Down (Hung Up). Only shown if Agent Pickup Detection is enabled.
Extra Query (optional) Additional query parameters appended to the WebSocket URL in key=value format separated by &.
Heartbeat Interval (ms) Interval in milliseconds to send heartbeat pings to keep the WebSocket connection alive (default 25000 ms).
Emit Connection Events If enabled, emits additional items for WebSocket connection open, close, and error events alongside ARI messages.
Debug Mode Enable debug logging to console to assist with testing and troubleshooting.

Output

The node outputs JSON objects representing ARI events received via WebSocket. Each output item contains:

  • messageNumber: Sequential number of the received message.
  • type: The ARI event type (e.g., "ChannelCreated", "BridgeDestroyed").
  • timestamp: Timestamp of the event as provided by ARI.
  • application: The ARI application name.
  • asterisk_id: Unique identifier for the Asterisk instance.
  • channelId: ID of the related channel if applicable.
  • channelName: Name of the related channel if available.
  • callerNumber: Caller number extracted from the channel.
  • connectedNumber: Connected party number if available.
  • dialplan: Dialplan information from the channel.
  • raw: The full raw event object as received.
  • receivedAt: ISO timestamp when the event was processed by the node.

If agent pickup detection is enabled and relevant variables are detected, additional fields are included:

  • agentPickupEvent: Boolean indicating an agent pickup event.
  • agentPickupVariable: The variable name that triggered the pickup detection.
  • agentPickupValue: The value of the pickup variable.
  • agentNumber: The agent's number involved in the pickup.
  • agentExtension: The agent's extension (if applicable).
  • agentId: The agent's ID (if applicable).
  • channelState: The current state of the channel.

If connection event emission is enabled, the node also outputs items for:

  • open: WebSocket connection opened.
  • close: WebSocket connection closed, including code and reason.
  • error: WebSocket errors with message details.

The node does not output binary data.

Dependencies

  • Requires access to an Asterisk ARI server with WebSocket support.
  • Needs valid ARI credentials (username and password) for authentication.
  • Uses the WebSocket protocol (ws or wss) to connect to the ARI events endpoint.
  • No external npm packages beyond the built-in WebSocket client library are required.
  • Network connectivity to the specified host and port must be allowed.
  • Proper configuration of the ARI application on the Asterisk server is necessary.

Troubleshooting

  • Connection failures: Ensure the host, port, protocol, username, and password are correct and that the ARI server is reachable.
  • Authentication errors: Verify ARI credentials; incorrect username or password will prevent connection.
  • No events received: Check if "Subscribe All" is enabled or if event type filtering excludes all events.
  • Agent pickup events missing: Confirm agent pickup detection is enabled and the correct variables and channel state filter are selected.
  • WebSocket disconnects/reconnects frequently: Network instability or server-side issues may cause frequent reconnects; check network and server logs.
  • Debug mode: Enable debug mode to see detailed logs in the console for troubleshooting.
  • Heartbeat ping failures: If heartbeat pings fail, the connection might be dropped by the server; verify heartbeat interval and network stability.
  • Extra Query parameter formatting: Ensure extra query string parameters are correctly formatted as key=value&key2=value2.

Links and References

Discussion