Product Events

Events that occur in the Freshcaller product, such as the establishment of a call connection, completion of a call, or transfer of a call, are termed as product events. You can enable product events to trigger apps. To do this, configure event listeners in the server.js file. When a product event occurs, the corresponding event listener invokes a callback method. The app logic in the callback method runs with the help of the event-specific payload passed to the callback method.

Configure Events

To register a product event and the corresponding callback:

  1. From your app’s root directory, navigate to the manifest.json file.
  2. Include the events attribute, specifying the product event and the corresponding callback methods as follows:
    Copied Copy 
    1
    2
    3
    4
    5
    		"events": {
  "<eventName>": {
      "handler": "<eventCallbackMethod>"
  }
}

    Note: Include only one callback method for an event. Multiple events can access the same callback method.

  3. Navigate to the server.js file.
  4. In the exports block, enter the callback function definition as follows:
    Copied Copy 
    1
    2
    3
    4
    5
    6
    7
    		exports = {
      // args is a JSON block containing the payload information
      // args["iparam"] will contain the installation parameter values
      //eventCallbackMethod is the call-back function name specified in manifest.json
      eventCallbackMethod: function(args) {
        console.log("Logging arguments from the event: " + JSON.stringify(payload));
      }};

Payload Attributes

When a product event occurs, an event-specific payload is passed to the callback method.

Copied Copy 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
{
  "account_id" : "value",
  "domain" : "value",
  "event"  : "value",
  "region"  : "value",
  "timestamp"  : "value",
  "data" : {
    //Contains the list of objects related to the event.
  },
  "iparams" : {
    "Param1" : "value",
    "Param2" : "value"
  }
}
EXPAND ↓

The payload is a JSON object with the following attributes.

Attribute Type Description
account_id string Identifier of the Freshcaller account, auto-generated when the account is configured for a business.
domain string Domain name for the Freshcaller account. For example, acn.freshcaller.com.
event string Identifier of the product event.
region string Region where the Freshcaller account is deployed.
Possible values: US, EU, EUC, AUS, and IND.
timestamp number Timestamp of when the product event occurs, specified in the epoch format.
iparams object Installation parameters specified as a JSON object of <parameter name>: <parameter value> pairs.
data object Event-specific Freshcaller data, specified as a JSON object of key:value pairs.
onCallCreate

When a call originates from a Freshcaller number or is being received to a Freshcaller number, the onCallCreate event is triggered.

Register the onCallCreate event by using the following sample manifest.json content.

Copied Copy 
1
2
3
4
5
"events": {
  "onCallCreate": {
    "handler": "onCallCreateCallback"
  }
}

Define the corresponding callback by using the following sample server.js content:

Copied Copy 
1
2
3
4
5
exports = {
  onCallCreateCallback: function(payload) {
    console.log("Logging arguments from onCallCreateCallback event: " + JSON.stringify(payload));
    }
  }
 Sample Payload 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
{
  "account_id": "82918",
  "domain": "sample.freshcaller.com",
  "event": "onCallCreate",
  "timestamp": 1583839686,
  "region": "US",
  "data": {
    "call": {
      "phone_number": "+12133701559",
      "root_call_id": null,
      "created_time": "2020-03-10T11:28:05.000Z",
      "assigned_ivr_id": null,
      "assigned_team_id": null,
      "phone_number_id": 46851,
      "participants": [
        {
          "participant_type": "Customer",
          "duration": null,
          "caller_id": 7994085,
          "caller_number": "+11234568791",
          "created_time": "2020-03-10T11:28:05.000Z",
          "connection_type": 0,
          "enqueued_time": null,
          "cost_unit": "usd",
          "duration_unit": "seconds",
          "id": 321,
          "cost": null,
          "participant_id": 318,
          "updated_time": "2020-03-10T11:28:05.000Z",
          "call_id": 135,
          "call_status": 0
        },
        {
          "participant_type": "Agent",
          "duration": null,
          "caller_id": null,
          "caller_number": null,
          "created_time": "2020-03-10T11:28:05.000Z",
          "connection_type": 1,
          "enqueued_time": null,
          "cost_unit": "usd",
          "duration_unit": "seconds",
          "id": 322,
          "cost": null,
          "participant_id": 694,
          "updated_time": "2020-03-10T11:28:05.000Z",
          "call_id": 135,
          "call_status": 8
        }
      ],
      "direction": "outgoing",
      "assigned_call_queue_id": null,
      "id": 135,
      "parent_call_id": null,
      "bill_duration": null,
      "bill_duration_unit": "seconds",
      "updated_time": "2020-03-10T11:28:05.000Z",
      "call_notes": null,
      "recording": null,
      "assigned_agent_id": 139694
    },
    "associations": {},
    "actor": {
      "type": "system"
    }
  }
}
EXPAND ↓
Attributes of the data object
ATTRIBUTE TYPE DESCRIPTION
call call object Details pertaining to the call that triggered the onCallCreate event.
associations object All objects related to the call object.
For onCallCreate, this value is an empty object.
actor actor object Information pertaining to the entity that created the call object.
Attribute of the actor object:
type (string): Identifier of the entity that created the call object. For onCallCreate, this value is system.

Attributes of the call object
ATTRIBUTE TYPE DESCRIPTION
id integer Identifier of the call object, auto-generated when the object is created at the start of a call.
direction integer Direction of the call.
Possible values (enum):
Incoming: The call that triggered onCallCreate was received at a Freshcaller number.
Outgoing: The call that triggered onCallCreate was made from a Freshcaller number.
parent_call_id integer This attribute is valid only for transferred calls. Therefore, for onCallCreate this value is null.
root_call_id integer This attribute is valid only when child calls are created. Therefore, for onCallCreate this value is null.
phone_number_id integer Identifier of the Freshcaller number from which the call is made or to which the call is received. The value is auto-generated when a number is configured in the Freshcaller system.
phone_number string Freshcaller number from which the call is made or to which the call is received.
assigned_agent_id integer Identifier of the primary agent who interacts with the customer.
assigned_team_id integer This attribute is valid only when a call is assigned to a team. Therefore, for onCallCreate this value is null.
assigned_call_queue_id integer For inbound calls, assigned_call_queue_id is the identifier of the call queue associated with the number in which the call is received. The call queue to which a call must be routed is specified when call actions are defined for a Freshcaller number.
For outbound calls, the value is null.
assigned_ivr_id integer For inbound calls, assigned_ivr_id is the identifier of the Interactive Voice Response (ivr) menu associated with the number in which the call is received . The ivr menu is associated with a number when call actions are defined for the number.
For outbound calls and for numbers that don’t have an ivr menu, the value is null.
call_notes string This attribute is valid only on completion of a call. Therefore, for onCallCreate this value is null.
bill_duration integer This attribute is valid only on completion of a call. Therefore, for onCallCreate this value is null.
bill_duration_unit string Unit of time used to express bill_duration.
Possible value: seconds.
created_time string Timestamp of when the call is established, specified in the UTC format.
updated_time string Timestamp of when the attributes of a call are last updated, specified in the UTC format. For onCallCreate, this value is the same as created_time.
recording recording object This attribute is valid only on completion of a call. Therefore, for onCallCreate this value is null.
participants array of callparticipant objects Information about the agent and customer involved in the call.

Attributes of the callparticipant object
ATTRIBUTE TYPE DESCRIPTION
id integer Identifier of the call participant object, auto-generated when the call participant object is created (when a participant joins a call) in the Freshcaller system.
call_id integer Identifier of the call object, auto-generated when the call is initiated.
caller_id integer Identifier of the customer number. For the agent participant_type, the value is null.
caller_number string Customer's phone number from which the call is made or to which the call received. For the agent participant_type, the value is null.
participant_id integer Identifier of the participant; either the agent’s id or customer’s id.
participant_type string Type of call participant.
Possible values: Agent, Customer
connection_type integer Indicator of the capacity in which the participant is involved in the call.
Possible values:
0: Indicates that the participant is involved in the call as a customer.
1: Indicates that the participant is involved in the call as a primary agent.
2 - 7: Invalid for onCallCreate.
call_status integer Indicator of the state of the call.
Default: 0
Possible values:
1: Answered/Completed
2: The call connection couldn’t be established as the number is busy.
3: The call falls under the category of a missed call.
4: The call connection failed.
5: The call connection is disconnected.
6: The call is routed to a queue.
8: The call is in progress.
9: The call is blocked.
10: The call is redirected to a voicemail.
11: The call originated from a restricted number.
12: The call is put on hold.
13: Establishing a call connection is in progress.
15: The call interaction was completed recently.
16: The voicemail recording is in progress.
duration integer This attribute is valid only after the completion of a call. Therefore, for onCallCreate this value is null.
duration_unit string Unit used to express duration.
Possible value: seconds
enqueued_time string This attribute is valid only in the case of the call being assigned to a queue. Therefore, for onCallCreate this value is null.
cost integer This attribute is valid only after the completion of the call. Therefore, for onCallCreate this value is null.
cost_unit string Currency in which cost is expressed, specified as a valid three character ISO currency code.
created_time string Timestamp of when the call participant object is created, specified in the UTC format.
updated_time string Timestamp of when the attributes of the call participant object are updated, specified in the UTC format.
onCallUpdate

When a call connection is established or lost, when a call’s status changes (transferred to an agent, an agent barges into a call, the call becomes a conference call, and so on), and when additional information such as call recording information, bill duration, call cost, call notes is associated with a call, the onCallUpdate event is triggered.

Register the onCallUpdate event by using the following sample manifest.json content.

Copied Copy 
1
2
3
4
5
"events": {
  "onCallUpdate": {
    "handler": "onCallUpdateCallback"
  }
}

Define the corresponding callback by using the following sample server.js content:

Copied Copy 
1
2
3
4
5
exports = {
  onCallUpdateCallback: function(payload) {
    console.log("Logging arguments from onCallUpdateCallback event: " + JSON.stringify(payload));
  }
}
EXPAND ↓ Sample Payload 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
{
  "account_id": "82918",
  "domain": "sample.freshcaller.com",
  "event": "onCallUpdate",
  "timestamp": 1583839672,
  "region": "US",
  "data": {
    "call": {
      "phone_number": "+12133701559",
      "root_call_id": null,
      "created_time": "2020-03-10T09:07:00.000Z",
      "assigned_ivr_id": null,
      "assigned_team_id": null,
      "phone_number_id": 46851,
      "participants": [
        {
          "participant_type": "Customer",
          "duration": 0,
          "caller_number": "+12133701559",
          "created_time": "2020-03-10T09:07:00.000Z",
          "connection_type": 0,
          "enqueued_time": null,
          "cost_unit": "usd",
          "caller_id": 7994085,
          "duration_unit": "seconds",
          "id": 321,
          "cost": 0,
          "participant_id": 135,
          "updated_time": "2020-03-10T09:07:44.000Z",
          "call_id": 156,
          "call_status": 3
        },
        {
          "participant_type": "Agent",
          "duration": 9,
          "caller_number": null,
          "created_time": "2020-03-10T09:07:00.000Z",
          "connection_type": 1,
          "enqueued_time": null,
          "cost_unit": "usd",
          "caller_id": null,
          "duration_unit": "seconds",
          "id": 823,
          "cost": null,
          "participant_id": 694,
          "updated_time": "2020-03-10T09:07:09.000Z",
          "call_id": 156,
          "call_status": 1
        }
      ],
      "direction": "outgoing",
      "assigned_call_queue_id": null,
      "id": 156,
      "parent_call_id": null,
      "bill_duration": 9,
      "bill_duration_unit": "seconds",
      "updated_time": "2020-03-10T11:27:51.000Z",
      "call_notes": "Customer needs to cancel flight",
      "recording": null,
      "assigned_agent_id": 694
    },
    "associations": {},
    "actor": {
      "type": "system"
    },
    "changes": {}
  }
}
EXPAND ↓
Attributes of the data object
ATTRIBUTE TYPE DESCRIPTION
call call object Details pertaining to the call whose status change triggered the onCallUpdate event.
associations object All objects related to the call object.
For onCallUpdate, this value is an empty object.
actor actor object Information pertaining to the entity that updated the call object.
Attribute of the actor object:
type (string): Identifier of the entity that updated the call object. For onCallUpdate, this value is system.
changes object Changes that triggered the onCallUpdate event, specified as a JSON object of the following format:
1
2
3
{
“<call object field that changed>”: [“New value”, “Old value”]
}
For onCallUpdate, this value is an empty object.

Attributes of the call object
ATTRIBUTE TYPE DESCRIPTION
id integer Identifier of the call object, auto-generated when the object is created at the start of a call.
direction integer Direction of the call.
Possible values:
Incoming: The call whose details were updated was received at a Freshcaller number.
Outgoing: The call whose details were updated was made from a Freshcaller number.
parent_call_id integer For transferred calls, parent_call_id is the identifier of the parent call that is transferred to an agent or a team.
For non-transferred calls, the value is null.
root_call_id integer For child calls created because of events such as agent monitoring, root_call_id is the identifier of the source call.
For source calls, the value is null.
phone_number_id integer Identifier of the Freshcaller number from which the call is made or to which the call is received. The value is auto-generated when a number is configured in the Freshcaller system.
phone_number string Freshcaller number from which the call is made or to which the call is received.
assigned_agent_id integer Identifier of the primary agent who interacts with the customer.
assigned_team_id integer For inbound calls, assigned_team_id is the identifier of the team to which the call is assigned.
For outbound calls, the value is null.
assigned_call_queue_id integer For inbound calls, assigned_call_queue_id is the identifier of the call queue associated with the number in which the call is received. The call queue to which a call must be routed is specified when call actions are defined for a Freshcaller number.
For outbound calls, the value is null.
assigned_ivr_id integer For inbound calls, assigned_ivr_id is the identifier of the Interactive Voice Response (ivr) menu associated with the number in which the call is received . The ivr menu is associated with a number when call actions are defined for the number.
For outbound calls and for numbers that don’t have an ivr menu, the value is null.
call_notes string Notes entered by an agent during or after the call.
bill_duration integer Duration for which the cost associated with a call is calculated, specified in the unit defined by bill_duration_unit.
bill_duration_unit string Unit of time used to express bill_duration.
Possible value: seconds.
created_time string Timestamp of when the call is established, specified in the UTC format.
updated_time string Timestamp of when the attributes of a call are last updated, specified in the UTC format.
recording recording object This attribute is valid only on completion of a call. Therefore, for onCallCreate this value is null.
participants array of callparticipant objects Information about the agents and customer involved in the call.

Attributes of the callparticipant object
ATTRIBUTE TYPE DESCRIPTION
id integer Identifier of the callparticipant object, auto-generated when the callparticipant object is created (when a participant joins a call) in the Freshcaller system.
call_id integer Identifier of the call object, auto-generated when a call is initiated in the Freshcaller system.
caller_id integer Identifier of the customer number.
For the agent participant_type, the value is null.
caller_number string Customer's phone number from which the call is made or received.
participant_id integer Identifier of the participant, maybe an agent or a customer.
participant_type string Type of call participant.
Possible values (enum): Agent, Customer
connection_type integer Type of call connection the participant is involved in.
Possible values:
0: Indicates that the participant is involved in the call as a customer.
1: Indicates that the participant is involved in the call as a primary agent.
2: Indicates that the participant is involved in the call as an agent monitoring the call.
3: Indicates that the participant is involved in the call as an agent who has barged into the primary agent’s call.
4: Indicates that the participant is involved in the call as an agent to whom the call was transferred (cold transfer).
5: Indicates that the participant is involved in the call as an agent to whom the call was transferred after the primary agent provided relevant information (warm transfer).
6: Indicates that the participant is involved in the call as an agent in a conference call.
7: Indicates that the participant involved in the call is an agent who received the call in a number external to Freshcaller.
call_status integer Indicator of the state of the call.
Default: 0
Possible values:
1: Answered/Completed
2: The call connection couldn’t be established as the number was busy.
3: The call falls under the category of a missed call.
4: The call connection failed.
5: The call connection is disconnected.
6: The call is routed to a queue.
8: The call is in progress.
9: The call is blocked.
10: The call is redirected to a voicemail.
11: The call originated from a restricted number.
12: The call is put on hold.
13: The call connection is being established.
15: The call interaction was completed recently.
16: The voicemail recording is in progress.
duration integer Duration of the call, specified in a unit defined by duration_unit.
duration_unit string Unit used to express duration.
Possible value: seconds
enqueued_time string Time when the call is assigned to a queue, specified in UTC format.
cost integer Cost associated with the call, calculated based on bill_duration and the default pricing mechanism in Freshcaller.
cost_unit string Currency in which cost is expressed, specified as a valid three character ISO currency code.
created_time string Timestamp of when the call participant object is created, specified in the UTC format.
updated_time string Timestamp of when the attributes of the call participant object are updated, specified in the UTC format.
Test

For information on how to simulate a product event and test your app, see Test the app.