API - Events

This is the developer reference document for the event API endpoints. An event stream will be established via Server Side Events (SSE). Channel events typically correspond to a stage of a call lifecycle and may be used to monitor for scenarios to perform call control actions. 

Base URL

https://api.cytracom.net/v1.0

API Endpoints for Events

VERB URL PATH ABOUT
 GET  /events/sse/chan  Channel Events
 GET  /events/sse/queue  Call Queue Statistic Events

Channel Events:

/events/sse/chan

Below is a list of events that are available to be returned once connected:

Event Description
dial_begin The system started ringing an endpoint
dial_end The system finished ringing an endpoint. Call was either answered, timed-out, or rejected
hangup Either callee or caller hangup an endpoint. Look details of the event to find out which endpoint

The JSON responses provide the following data:

Attribute Description
unique_id  The unique id of the created channel
linked_id  The id associated with this call, regardless of let count
event_time  Epoch time
event  Event descriptor
direction  Direction of the call
customer_code  7-Digit customer identifier (PBX Context)
caller  Details for the originator of the call
   state  Channel call state
   number  Dialed number
   name  Caller-Id name
   device  Cytracom device/username
   channel_id  Channel identifier to be used for subsequent actions
   answered_time  Epoch time
   dial_status  Status of an attempt to dial a remote party
   connected_name  Name of the device that was connected to the channel
   connected_number  Number of the device that was connected to the channel
   connected_device  Device that was connected to the channel
callee  Details for the receiver of the call
   state  Channel call state
   number  Dialed number
   name  Caller-Id name
   device  Cytracom device/username
   channel_id  Channel identifier to be used for subsequent actions
   answered_time  Epoch time
   dial_status  Status of an attempt to dial a remote party
   connected_name  Name of the device that was connected to the channel
   connected_number  Number of the device that was connected to the channel
   connected_device  Device that was connected to the channel


Example cURL Request:

curl --request POST \
  --user token:<<YOUR-TOKEN>> \
  --url http://api.cytracom.net/v1.0/events/sse/chan

Example Event Response:

event:chan.dial_begin
data:{"unique_id":"a309994c-70a8-43f2-aaca-2e97986e4131","linked_id":"1548318101312.864897","event_time":1548318101509,"event":"chan.dial_begin","direction":"internal","customer_code":"baaaaac","caller":{"state":null,"number":"226","name":"Mark Meyers","device":"sip226_baaaaac","channel_id":"63d30d39-828d-48c4-a8d9-90ef8f626517","answered_time":"0"},"called":{"state":"ringing","number":"697","name":"Outbound Call","dial_status":"ringing","device":"sip697_baaaaac","channel_id":"63d30d39-828d-48c4-a8d9-90ef8f626517"}}

Example JSON data for dial_begin:

{
"unique_id": "a309994c-70a8-43f2-aaca-2e97986e4131",
"linked_id": "1548318101312.864897",
"event_time": 1548318101509,
"event": "chan.dial_begin",
"direction": "internal",
"customer_code": "baaaaac",
"caller": {
"state": null,
"number": "226",
"name": "Mark Meyer",
"device": "sip226_baaaaac",
"channel_id": "63d30d39-828d-48c4-a8d9-90ef8f626517",
"answered_time": "0"
},
"called": {
"state": "ringing",
"number": "697",
"name": "Outbound Call",
"dial_status": "ringing",
"device": "sip697_baaaaac",
"channel_id": "63d30d39-828d-48c4-a8d9-90ef8f626517"
}
}

 Example JSON data for dial_end:

{
"unique_id": "b5b465de-15fa-4f79-a2b2-e1f39740066c",
"linked_id": "1548320221192.783882",
"event_time": 1548320244669,
"event": "chan.dial_end",
"direction": "outbound",
"customer_code": "baaaaac",
"caller": {
"state": null,
"number": "2147367077",
"name": "Cytracom LLC",
"device": "sip226_baaaaac",
"channel_id": "87e949ff-2688-4e87-95e3-f5b1820dd5ce",
"answered_time": "1548320244649309"
},
"called": {
"state": "answered",
"number": "8774112987",
"name": "Outbound Call",
"dial_status": "answered",
"device": null,
"channel_id": "b5b465de-15fa-4f79-a2b2-e1f39740066c"
}
}

Example JSON data for hangup:

{
"unique_id": "a309994c-70a8-43f2-aaca-2e97986e4131",
"linked_id": "1548318101312.864897",
"event_time": 1548318108369,
"event": "chan.hangup",
"direction": "internal",
"customer_code": "baaaaac",
"channel": {
"state": "hangup",
"number": "697",
"name": "Outbound Call",
"dial_status": "no answer",
"device": "sip697_baaaaac",
"connected_number": "226",
"connected_name": "Mark Meyer",
"connected_device": "sip226_baaaaac",
"channel_id": "63d30d39-828d-48c4-a8d9-90ef8f626517"
}
}

Call Queue Statistic Events:

/events/sse/queue

Below is a list of events that are available to be returned once connected:

Event Description
queue_status Queue statistics

member_init_state

Initial state for each member assigned to the queue

caller_history

A condensed CDR for queue calls for the current day - resets at midnight

caller_join

Provides details of a caller joining a queue

caller_abandon

Provides details of a caller abandoning a queue 

member_state

Updated member state, per member in a queue. (ie: receiving/waiting) 

member_connect

Provides details when a member accepts a queue call

member_complete

Summary of a completed queue call

When connecting to the queue endpoint, you may apply additional filters:

Field Description Mandatory
queue_ids A comma separated list of queue ids. If a queue id is provided an initial "queue_status" event will be generated upon connection No
only_events Filter returned events types from the event list above No


Example cURL Request:

curl --request POST \
  --user token:<<YOUR-TOKEN>> \
  --url http://api.cytracom.net/v1.0/events/sse/queue

 

To view the next article, click:

next-button__for_articles_.png

 

 

Was this article helpful?
0 out of 0 found this helpful
Have more questions? Submit a request