asterisk/rest-api/api-docs/events.json

{
	"_copyright": "Copyright (C) 2012 - 2013, Digium, Inc.",
	"_author": "David M. Lee, II <dlee@digium.com>",
	"_svn_revision": "$Revision$",
	"apiVersion": "2.0.0",
	"swaggerVersion": "1.2",
	"basePath": "http://localhost:8088/ari",
	"resourcePath": "/api-docs/events.{format}",
	"requiresModules": [
		"res_http_websocket"
	],
	"apis": [
		{
			"path": "/events",
			"description": "Events from Asterisk to applications",
			"operations": [
				{
					"httpMethod": "GET",
					"upgrade": "websocket",
					"websocketProtocol": "ari",
					"summary": "WebSocket connection for events.",
					"nickname": "eventWebsocket",
					"responseClass": "Message",
					"parameters": [
						{
							"name": "app",
							"description": "Applications to subscribe to.",
							"paramType": "query",
							"required": true,
							"allowMultiple": true,
							"dataType": "string"
						},
						{
							"name": "subscribeAll",
							"description": "Subscribe to all Asterisk events. If provided, the applications listed will be subscribed to all events, effectively disabling the application specific subscriptions. Default is 'false'.",
							"paramType": "query",
							"required": false,
							"allowMultiple": false,
							"dataType": "boolean"
						}
					]
				}
			]
		},
		{
			"path": "/events/user/{eventName}",
			"description": "Stasis application user events",
			"operations": [
				{
					"httpMethod": "POST",
					"summary": "Generate a user event.",
					"nickname": "userEvent",
					"responseClass": "void",
					"parameters": [
						{
							"name": "eventName",
							"description": "Event name",
							"paramType": "path",
							"required": true,
							"allowMultiple": false,
							"dataType": "string"
						},
						{
							"name": "application",
							"description": "The name of the application that will receive this event",
							"paramType": "query",
							"required": true,
							"allowMultiple": false,
							"dataType": "string"
						},
						{
							"name": "source",
							"description": "URI for event source (channel:{channelId}, bridge:{bridgeId}, endpoint:{tech}/{resource}, deviceState:{deviceName}",
							"paramType": "query",
							"required": false,
							"allowMultiple": true,
							"dataType": "string"
						},
						{
							"name": "variables",
							"description": "The \"variables\" key in the body object holds custom key/value pairs to add to the user event. Ex. { \"variables\": { \"key\": \"value\" } }",
							"paramType": "body",
							"required": false,
							"allowMultiple": false,
							"dataType": "containers"
						}
					],
					"errorResponses": [
						{
							"code": 404,
							"reason": "Application does not exist."
						},
						{
							"code": 422,
							"reason": "Event source not found."
						},
						{
							"code": 400,
							"reason": "Invalid even tsource URI or userevent data."
						}
					]
				}
			]
		}
	],
	"models": {
		"Message": {
			"id": "Message",
			"description": "Base type for errors and events",
			"discriminator": "type",
			"properties": {
				"type": {
					"type": "string",
					"required": true,
					"description": "Indicates the type of this message."
				},
				"asterisk_id": {
					"type": "string",
					"required": false,
					"description": "The unique ID for the Asterisk instance that raised this event."
				}
			},
			"subTypes": [
				"MissingParams",
				"Event"
			]
		},
		"MissingParams": {
			"id": "MissingParams",
			"description": "Error event sent when required params are missing.",
			"properties": {
				"params": {
					"required": true,
					"type": "List[string]",
					"description": "A list of the missing parameters"
				}
			}
		},
		"Event": {
			"id": "Event",
			"description": "Base type for asynchronous events from Asterisk.",
			"properties": {
				"application": {
					"type": "string",
					"description": "Name of the application receiving the event.",
					"required": true
				},
				"timestamp": {
					"type": "Date",
					"description": "Time at which this event was created.",
					"required": true
				}
			},
			"subTypes": [
				"DeviceStateChanged",
				"PlaybackStarted",
				"PlaybackContinuing",
				"PlaybackFinished",
				"RecordingStarted",
				"RecordingFinished",
				"RecordingFailed",
				"ApplicationMoveFailed",
				"ApplicationReplaced",
				"BridgeCreated",
				"BridgeDestroyed",
				"BridgeMerged",
				"BridgeBlindTransfer",
				"BridgeAttendedTransfer",
				"BridgeVideoSourceChanged",
				"ChannelCreated",
				"ChannelDestroyed",
				"ChannelEnteredBridge",
				"ChannelLeftBridge",
				"ChannelStateChange",
				"ChannelDtmfReceived",
				"ChannelDialplan",
				"ChannelCallerId",
				"ChannelUserevent",
				"ChannelHangupRequest",
				"ChannelVarset",
				"ChannelTalkingStarted",
				"ChannelTalkingFinished",
				"ChannelHold",
				"ChannelUnhold",
				"ContactStatusChange",
				"EndpointStateChange",
				"Dial",
				"StasisEnd",
				"StasisStart",
				"TextMessageReceived",
				"ChannelConnectedLine",
				"PeerStatusChange"
			]
		},
		"ContactInfo": {
			"id": "ContactInfo",
			"description": "Detailed information about a contact on an endpoint.",
			"properties": {
				"uri": {
					"type": "string",
					"description": "The location of the contact.",
					"required": true
				},
				"contact_status": {
					"type": "string",
					"description": "The current status of the contact.",
					"required": true,
					"allowableValues": {
						"valueType": "LIST",
						"values": [
							"Unreachable",
							"Reachable",
							"Unknown",
							"NonQualified",
							"Removed"
						]
					}
				},
				"aor": {
					"type": "string",
					"description": "The Address of Record this contact belongs to.",
					"required": true
				},
				"roundtrip_usec": {
					"type": "string",
					"description": "Current round trip time, in microseconds, for the contact.",
					"required": false
				}
			}
		},
		"Peer": {
			"id": "Peer",
			"description": "Detailed information about a remote peer that communicates with Asterisk.",
			"properties": {
				"peer_status": {
					"type": "string",
					"description": "The current state of the peer. Note that the values of the status are dependent on the underlying peer technology.",
					"required": true
				},
				"cause": {
					"type": "string",
					"description": "An optional reason associated with the change in peer_status.",
					"required": false
				},
				"address": {
					"type": "string",
					"description": "The IP address of the peer.",
					"required": false
				},
				"port": {
					"type": "string",
					"description": "The port of the peer.",
					"required": false
				},
				"time": {
					"type": "string",
					"description": "The last known time the peer was contacted.",
					"required": false
				}
			}
		},
		"DeviceStateChanged": {
			"id": "DeviceStateChanged",
			"description": "Notification that a device state has changed.",
			"properties": {
				"device_state": {
					"type": "DeviceState",
					"description": "Device state object",
					"required": true
				}
			}
		},
		"PlaybackStarted": {
			"id": "PlaybackStarted",
			"description": "Event showing the start of a media playback operation.",
			"properties": {
				"playback": {
					"type": "Playback",
					"description": "Playback control object",
					"required": true
				}
			}
		},
		"PlaybackContinuing": {
			"id": "PlaybackContinuing",
			"description": "Event showing the continuation of a media playback operation from one media URI to the next in the list.",
			"properties": {
				"playback": {
					"type": "Playback",
					"description": "Playback control object",
					"required": true
				}
			}
		},
		"PlaybackFinished": {
			"id": "PlaybackFinished",
			"description": "Event showing the completion of a media playback operation.",
			"properties": {
				"playback": {
					"type": "Playback",
					"description": "Playback control object",
					"required": true
				}
			}
		},
		"RecordingStarted": {
			"id": "RecordingStarted",
			"description": "Event showing the start of a recording operation.",
			"properties": {
				"recording": {
					"type": "LiveRecording",
					"description": "Recording control object",
					"required": true
				}
			}
		},
		"RecordingFinished": {
			"id": "RecordingFinished",
			"description": "Event showing the completion of a recording operation.",
			"properties": {
				"recording": {
					"type": "LiveRecording",
					"description": "Recording control object",
					"required": true
				}
			}
		},
		"RecordingFailed": {
			"id": "RecordingFailed",
			"description": "Event showing failure of a recording operation.",
			"properties": {
				"recording": {
					"type": "LiveRecording",
					"description": "Recording control object",
					"required": true
				}
			}
		},
		"ApplicationMoveFailed": {
			"id": "ApplicationMoveFailed",
			"description": "Notification that trying to move a channel to another Stasis application failed.",
			"properties": {
				"channel": {
					"required": true,
					"type": "Channel"
				},
				"destination": {
					"required": true,
					"type": "string"
				},
				"args": {
					"required": true,
					"type": "List[string]",
					"description": "Arguments to the application"
				}
			}
		},
		"ApplicationReplaced": {
			"id": "ApplicationReplaced",
			"description": "Notification that another WebSocket has taken over for an application.\n\nAn application may only be subscribed to by a single WebSocket at a time. If multiple WebSockets attempt to subscribe to the same application, the newer WebSocket wins, and the older one receives this event.",
			"properties": {}
		},
		"BridgeCreated": {
			"id": "BridgeCreated",
			"description": "Notification that a bridge has been created.",
			"properties": {
				"bridge": {
					"required": true,
					"type": "Bridge"
				}
			}
		},
		"BridgeDestroyed": {
			"id": "BridgeDestroyed",
			"description": "Notification that a bridge has been destroyed.",
			"properties": {
				"bridge": {
					"required": true,
					"type": "Bridge"
				}
			}
		},
		"BridgeMerged": {
			"id": "BridgeMerged",
			"description": "Notification that one bridge has merged into another.",
			"properties": {
				"bridge": {
					"required": true,
					"type": "Bridge"
				},
				"bridge_from": {
					"required": true,
					"type": "Bridge"
				}
			}
		},
		"BridgeVideoSourceChanged": {
			"id": "BridgeVideoSourceChanged",
			"description": "Notification that the source of video in a bridge has changed.",
			"properties": {
				"bridge": {
					"required": true,
					"type": "Bridge"
				},
				"old_video_source_id": {
					"required": false,
					"type": "string"
				}
			}
		},
		"BridgeBlindTransfer": {
			"id": "BridgeBlindTransfer",
			"description": "Notification that a blind transfer has occurred.",
			"properties": {
				"channel": {
					"description": "The channel performing the blind transfer",
					"required": true,
					"type": "Channel"
				},
				"replace_channel": {
					"description": "The channel that is replacing transferer when the transferee(s) can not be transferred directly",
					"required": false,
					"type": "Channel"
				},
				"transferee": {
					"description": "The channel that is being transferred",
					"required": false,
					"type": "Channel"
				},
				"exten": {
					"description": "The extension transferred to",
					"required": true,
					"type": "string"
				},
				"context": {
					"description": "The context transferred to",
					"required": true,
					"type": "string"
				},
				"result": {
					"description": "The result of the transfer attempt",
					"required": true,
					"type": "string"
				},
				"is_external": {
					"description": "Whether the transfer was externally initiated or not",
					"required": true,
					"type": "boolean"
				},
				"bridge": {
					"description": "The bridge being transferred",
					"type": "Bridge"
				}
			}
		},
		"BridgeAttendedTransfer": {
			"id": "BridgeAttendedTransfer",
			"description": "Notification that an attended transfer has occurred.",
			"properties": {
				"transferer_first_leg": {
					"description": "First leg of the transferer",
					"required": true,
					"type": "Channel"
				},
				"transferer_second_leg": {
					"description": "Second leg of the transferer",
					"required": true,
					"type": "Channel"
				},
				"replace_channel": {
					"description": "The channel that is replacing transferer_first_leg in the swap",
					"required": false,
					"type": "Channel"
				},
				"transferee": {
					"description": "The channel that is being transferred",
					"required": false,
					"type": "Channel"
				},
				"transfer_target": {
					"description": "The channel that is being transferred to",
					"required": false,
					"type": "Channel"
				},
				"result": {
					"description": "The result of the transfer attempt",
					"required": true,
					"type": "string"
				},
				"is_external": {
					"description": "Whether the transfer was externally initiated or not",
					"required": true,
					"type": "boolean"
				},
				"transferer_first_leg_bridge": {
					"description": "Bridge the transferer first leg is in",
					"type": "Bridge"
				},
				"transferer_second_leg_bridge": {
					"description": "Bridge the transferer second leg is in",
					"type": "Bridge"
				},
				"destination_type": {
					"description": "How the transfer was accomplished",
					"required": true,
					"type": "string"
				},
				"destination_bridge": {
					"description": "Bridge that survived the merge result",
					"type": "string"
				},
				"destination_application": {
					"description": "Application that has been transferred into",
					"type": "string"
				},
				"destination_link_first_leg": {
					"description": "First leg of a link transfer result",
					"type": "Channel"
				},
				"destination_link_second_leg": {
					"description": "Second leg of a link transfer result",
					"type": "Channel"
				},
				"destination_threeway_channel": {
					"description": "Transferer channel that survived the threeway result",
					"type": "Channel"
				},
				"destination_threeway_bridge": {
					"description": "Bridge that survived the threeway result",
					"type": "Bridge"
				}
			}
		},
		"ChannelCreated": {
			"id": "ChannelCreated",
			"description": "Notification that a channel has been created.",
			"properties": {
				"channel": {
					"required": true,
					"type": "Channel"
				}
			}
		},
		"ChannelDestroyed": {
			"id": "ChannelDestroyed",
			"description": "Notification that a channel has been destroyed.",
			"properties": {
				"cause": {
					"required": true,
					"description": "Integer representation of the cause of the hangup",
					"type": "int"
				},
				"cause_txt": {
					"required": true,
					"description": "Text representation of the cause of the hangup",
					"type": "string"
				},
				"channel": {
					"required": true,
					"type": "Channel"
				}
			}
		},
		"ChannelEnteredBridge": {
			"id": "ChannelEnteredBridge",
			"description": "Notification that a channel has entered a bridge.",
			"properties": {
				"bridge": {
					"required": true,
					"type": "Bridge"
				},
				"channel": {
					"type": "Channel"
				}
			}
		},
		"ChannelLeftBridge": {
			"id": "ChannelLeftBridge",
			"description": "Notification that a channel has left a bridge.",
			"properties": {
				"bridge": {
					"required": true,
					"type": "Bridge"
				},
				"channel": {
					"required": true,
					"type": "Channel"
				}
			}
		},
		"ChannelStateChange": {
			"id": "ChannelStateChange",
			"description": "Notification of a channel's state change.",
			"properties": {
				"channel": {
					"required": true,
					"type": "Channel"
				}
			}
		},
		"ChannelDtmfReceived": {
			"id": "ChannelDtmfReceived",
			"description": "DTMF received on a channel.\n\nThis event is sent when the DTMF ends. There is no notification about the start of DTMF",
			"properties": {
				"digit": {
					"required": true,
					"type": "string",
					"description": "DTMF digit received (0-9, A-E, # or *)"
				},
				"duration_ms": {
					"required": true,
					"type": "int",
					"description": "Number of milliseconds DTMF was received"
				},
				"channel": {
					"required": true,
					"type": "Channel",
					"description": "The channel on which DTMF was received"
				}
			}
		},
		"ChannelDialplan": {
			"id": "ChannelDialplan",
			"description": "Channel changed location in the dialplan.",
			"properties": {
				"channel": {
					"required": true,
					"type": "Channel",
					"description": "The channel that changed dialplan location."
				},
				"dialplan_app": {
					"required": true,
					"type": "string",
					"description": "The application about to be executed."
				},
				"dialplan_app_data": {
					"required": true,
					"type": "string",
					"description": "The data to be passed to the application."
				}
			}
		},
		"ChannelCallerId": {
			"id": "ChannelCallerId",
			"description": "Channel changed Caller ID.",
			"properties": {
				"caller_presentation": {
					"required": true,
					"type": "int",
					"description": "The integer representation of the Caller Presentation value."
				},
				"caller_presentation_txt": {
					"required": true,
					"type": "string",
					"description": "The text representation of the Caller Presentation value."
				},
				"channel": {
					"required": true,
					"type": "Channel",
					"description": "The channel that changed Caller ID."
				}
			}
		},
		"ChannelUserevent": {
			"id": "ChannelUserevent",
			"description": "User-generated event with additional user-defined fields in the object.",
			"properties": {
				"eventname": {
					"required": true,
					"type": "string",
					"description": "The name of the user event."
				},
				"channel": {
					"required": false,
					"type": "Channel",
					"description": "A channel that is signaled with the user event."
				},
				"bridge": {
					"required": false,
					"type": "Bridge",
					"description": "A bridge that is signaled with the user event."
				},
				"endpoint": {
					"required": false,
					"type": "Endpoint",
					"description": "A endpoint that is signaled with the user event."
				},
				"userevent": {
					"required": true,
					"type": "object",
					"description": "Custom Userevent data"
				}
			}
		},
		"ChannelHangupRequest": {
			"id": "ChannelHangupRequest",
			"description": "A hangup was requested on the channel.",
			"properties": {
				"cause": {
					"type": "int",
					"description": "Integer representation of the cause of the hangup."
				},
				"soft": {
					"type": "boolean",
					"description": "Whether the hangup request was a soft hangup request."
				},
				"channel": {
					"required": true,
					"type": "Channel",
					"description": "The channel on which the hangup was requested."
				}
			}
		},
		"ChannelVarset": {
			"id": "ChannelVarset",
			"description": "Channel variable changed.",
			"properties": {
				"variable": {
					"required": true,
					"type": "string",
					"description": "The variable that changed."
				},
				"value": {
					"required": true,
					"type": "string",
					"description": "The new value of the variable."
				},
				"channel": {
					"required": false,
					"type": "Channel",
					"description": "The channel on which the variable was set.\n\nIf missing, the variable is a global variable."
				}
			}
		},
		"ChannelHold": {
			"id": "ChannelHold",
			"description": "A channel initiated a media hold.",
			"properties": {
				"channel": {
					"required": true,
					"type": "Channel",
					"description": "The channel that initiated the hold event."
				},
				"musicclass": {
					"required": false,
					"type": "string",
					"description": "The music on hold class that the initiator requested."
				}
			}
		},
		"ChannelUnhold": {
			"id": "ChannelUnhold",
			"description": "A channel initiated a media unhold.",
			"properties": {
				"channel": {
					"required": true,
					"type": "Channel",
					"description": "The channel that initiated the unhold event."
				}
			}
		},
		"ChannelTalkingStarted": {
			"id": "ChannelTalkingStarted",
			"description": "Talking was detected on the channel.",
			"properties": {
				"channel": {
					"required": true,
					"type": "Channel",
					"description": "The channel on which talking started."
				}
			}
		},
		"ChannelTalkingFinished": {
			"id": "ChannelTalkingFinished",
			"description": "Talking is no longer detected on the channel.",
			"properties": {
				"channel": {
					"required": true,
					"type": "Channel",
					"description": "The channel on which talking completed."
				},
				"duration": {
					"required": true,
					"type": "int",
					"description": "The length of time, in milliseconds, that talking was detected on the channel"
				}
			}
		},
		"ContactStatusChange": {
			"id": "ContactStatusChange",
			"description": "The state of a contact on an endpoint has changed.",
			"properties": {
				"endpoint": {
					"required": true,
					"type": "Endpoint"
				},
				"contact_info": {
					"required": true,
					"type": "ContactInfo"
				}
			}
		},
		"PeerStatusChange": {
			"id": "PeerStatusChange",
			"description": "The state of a peer associated with an endpoint has changed.",
			"properties": {
				"endpoint": {
					"required": true,
					"type": "Endpoint"
				},
				"peer": {
					"required": true,
					"type": "Peer"
				}
			}
		},
		"EndpointStateChange": {
			"id": "EndpointStateChange",
			"description": "Endpoint state changed.",
			"properties": {
				"endpoint": {
					"required": true,
					"type": "Endpoint"
				}
			}
		},
		"Dial": {
			"id": "Dial",
			"description": "Dialing state has changed.",
			"properties": {
				"caller": {
					"required": false,
					"type": "Channel",
					"description": "The calling channel."
				},
				"peer": {
					"required": true,
					"type": "Channel",
					"description": "The dialed channel."
				},
				"forward": {
					"required": false,
					"type": "string",
					"description": "Forwarding target requested by the original dialed channel."
				},
				"forwarded": {
					"required": false,
					"type": "Channel",
					"description": "Channel that the caller has been forwarded to."
				},
				"dialstring": {
					"required": false,
					"type": "string",
					"description": "The dial string for calling the peer channel."
				},
				"dialstatus": {
					"required": true,
					"type": "string",
					"description": "Current status of the dialing attempt to the peer."
				}
			}
		},
		"StasisEnd": {
			"id": "StasisEnd",
			"description": "Notification that a channel has left a Stasis application.",
			"properties": {
				"channel": {
					"required": true,
					"type": "Channel"
				}
			}
		},
		"StasisStart": {
			"id": "StasisStart",
			"description": "Notification that a channel has entered a Stasis application.",
			"properties": {
				"args": {
					"required": true,
					"type": "List[string]",
					"description": "Arguments to the application"
				},
				"channel": {
					"required": true,
					"type": "Channel"
				},
				"replace_channel": {
					"required": false,
					"type": "Channel"
				}
			}
		},
		"TextMessageReceived": {
			"id": "TextMessageReceived",
			"description": "A text message was received from an endpoint.",
			"properties": {
				"message": {
					"required": true,
					"type": "TextMessage"
				},
				"endpoint": {
					"required": false,
					"type": "Endpoint"
				}
			}
		},
		"ChannelConnectedLine": {
			"id": "ChannelConnectedLine",
			"description": "Channel changed Connected Line.",
			"properties": {
				"channel": {
					"required": true,
					"type": "Channel",
					"description": "The channel whose connected line has changed."
				}
			}
		}
	}
}