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:
- From your app’s root directory, navigate to the manifest.json file.
- Include the events attribute, specifying the product event and the corresponding callback methods as follows:
Copied
Copy
12345
"events": { "<eventName>": { "handler": "<eventCallbackMethod>" } } Note: Include only one callback method for an event. Multiple events can access the same callback method.
- Navigate to the server.js file.
- In the exports block, enter the callback function definition as follows:
Copied
Copy
1234567
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 Copy1 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" } } |
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 Copy1 2 3 4 5 | "events": { "onCallCreate": { "handler": "onCallCreateCallback" } } |
Define the corresponding callback by using the following sample server.js content:
Copied Copy1 2 3 4 5 | exports = { onCallCreateCallback: function(payload) { console.log("Logging arguments from onCallCreateCallback event: " + JSON.stringify(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" } } } |
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 Copy1 2 3 4 5 | "events": { "onCallUpdate": { "handler": "onCallUpdateCallback" } } |
Define the corresponding callback by using the following sample server.js content:
Copied Copy1 2 3 4 5 | exports = { onCallUpdateCallback: function(payload) { console.log("Logging arguments from onCallUpdateCallback event: " + JSON.stringify(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": {} } } |
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:
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.