Freshworks Developer Platform Docs

onCallCreate

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

Subscribe to the onCallCreate event and register the callback by using the following sample manifest.json content.

manifest.json

"events": {
  "onCallCreate": {
    "handler": "onCallCreateCallback"
  }
}

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

server.js

exports = {
  onCallCreateCallback: function(payload) {
    console.log("Logging arguments from onCallCreate event: " + JSON.stringify(payload));
  }
}

Attributes of the data object

actorobject
Information pertaining to the entity that created the call object.
- typestring
  Identifier of the entity that created the call object.
  For onCallCreate, this value is system.
associationsobject
All objects related to the call object.
For onCallCreate, this value is an empty object.
callobject
Details pertaining to the call that triggered the onCallCreate event.
- assigned_agent_idinteger
  Identifier of the primary agent who interacts with the customer.
- assigned_call_queue_idinteger
  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 Freshworks number.
  For outbound calls, the value is null.
- assigned_ivr_idinteger
  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.
- assigned_team_idinteger
  This attribute is valid only when a call is assigned to a team.
  Therefore, for onCallCreate this value is null.
- bill_durationinteger
  This attribute is valid only on completion of a call.
  Therefore, for onCallCreate this value is null.
- bill_duration_unitstring
  Unit of time used to express bill_duration.
  Possible value: seconds.
- call_notesstring
  This attribute is valid only on completion of a call.
  Therefore, for onCallCreate this value is null.
- created_timestring
  Timestamp of when the call is established, specified in the UTC format.
- directioninteger
  Direction of the call.
  Possible values (enum):
  Incoming: The call that triggered onCallCreate was received at a Freshworks number.
  Outgoing: The call that triggered onCallCreate was made from a Freshworks number.
- idinteger
  Identifier of the call object, auto-generated when the object is created at the start of a call.
- parent_call_idinteger
  This attribute is valid only for transferred calls.
  Therefore, for onCallCreate this value is null.
- participantsarray of objects
  Information about the agent and customer involved in the call.
  call_idinteger
  Identifier of the call object, auto-generated when the call is initiated.
  call_statusinteger
  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.
  caller_idinteger
  Identifier of the customer number.
  If participant_type value is Agent, the value of caller_id is null.
  caller_numberstring
  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.
  connection_typeinteger
  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.
  costinteger
  This attribute is valid only after the completion of the call.
  Therefore, for onCallCreate this value is null.
  cost_unitstring
  Currency in which cost is expressed, specified as a valid three character ISO currency code.
  created_timestring
  Timestamp of when the call participant object is created, specified in the UTC format.
  durationinteger
  This attribute is valid only after the completion of a call.
  Therefore, for onCallCreate this value is null.
  duration_unitstring
  Unit used to express duration.
  Possible value: seconds
  enqueued_timestring
  This attribute is valid only in the case of the call being assigned to a queue.
  Therefore, for onCallCreate this value is null.
  idinteger
  Identifier of the call participant object, auto-generated when the call participant object is created (when a participant joins a call) in the Freshworks system.
  participant_idinteger
  Identifier of the participant; either the agent’s id or customer’s id.
  participant_typestring
  Type of call participant.
  Possible values: Agent, Customer
  updated_timestring
  Timestamp of when the attributes of the call participant object are updated, specified in the UTC format.
- phone_numberstring
  Freshworks number from which the call is made or to which the call is received.
- phone_number_idinteger
  Identifier of the Freshworks 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 Freshworks system.
- recordingobject
  This attribute is valid only on completion of a call.
  Therefore, for onCallCreate this value is null.
- root_call_idinteger
  This attribute is valid only when child calls are created.
  Therefore, for onCallCreate this value is null.
- updated_timestring
  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.

Sample payload

{
  "currentHost":{
    "subscribed_modules": [
      "call", "caller_conversation"
    ],
    "endpoint_urls": {
      "freshcaller": "https://subdomain.freshcaller.com"
    }
  },
  "data": {
    "actor": {
      "type": "system"
    },
    "associations": {},
    "call": {
      "assigned_agent_id": 139694,
      "assigned_call_queue_id": null,
      "assigned_ivr_id": null,
      "assigned_team_id": null,
      "bill_duration": null,
      "bill_duration_unit": "seconds",
      "call_notes": null,
      "created_time": "2020-03-10T11:28:05.000Z",
      "direction": "outgoing",
      "id": 135,
      "parent_call_id": null,
      "participants": [
        {
          "call_id": 135,
          "call_status": 0,
          "caller_id": 7994085,
          "caller_number": "+11234568791",
          "connection_type": 0,
          "cost": null,
          "cost_unit": "usd",
          "created_time": "2020-03-10T11:28:05.000Z",
          "duration": null,
          "duration_unit": "seconds",
          "enqueued_time": null,
          "id": 321,
          "participant_id": 318,
          "participant_type": "Customer",
          "updated_time": "2020-03-10T11:28:05.000Z"
        },
        {
          "call_id": 135,
          "call_status": 8,
          "caller_id": null,
          "caller_number": null,
          "connection_type": 1,
          "cost": null,
          "cost_unit": "usd",
          "created_time": "2020-03-10T11:28:05.000Z",
          "duration": null,
          "duration_unit": "seconds",
          "enqueued_time": null,
          "id": 322,
          "participant_id": 694,
          "participant_type": "Agent",
          "updated_time": "2020-03-10T11:28:05.000Z"
        }
      ],
      "phone_number": "+12133701559",
      "phone_number_id": 46851,
      "recording": null,
      "root_call_id": null,
      "updated_time": "2020-03-10T11:28:05.000Z"
    }
  },
  "event": "onCallCreate",
  "region": "US",
  "timestamp": 1583839686
}

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.

Subscribe to the onCallUpdate event and register the callback by using the following sample manifest.json content.

manifest.json

"events": {
  "onCallUpdate": {
    "handler": "onCallUpdateCallback"
  }
}

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

server.js

exports = {
  onCallUpdateCallback: function(payload) {
    console.log("Logging arguments from onCallUpdate event: " + JSON.stringify(payload));
  }
}

Attributes of the data object

actorobject
Information pertaining to the entity that created the call object.
- typestring
  Identifier of the entity that created the call object.
  For onCallCreate, this value is system.
associationsobject
All objects related to the call object.
For onCallCreate, this value is an empty object.
callobject
Details pertaining to the call that triggered the onCallCreate event.
- assigned_agent_idinteger
  Identifier of the primary agent who interacts with the customer.
- assigned_call_queue_idinteger
  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 Freshworks number.
  For outbound calls, the value is null.
- assigned_ivr_idinteger
  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.
- assigned_team_idinteger
  This attribute is valid only when a call is assigned to a team.
  Therefore, for onCallCreate this value is null.
- bill_durationinteger
  This attribute is valid only on completion of a call.
  Therefore, for onCallCreate this value is null.
- bill_duration_unitstring
  Unit of time used to express bill_duration.
  Possible value: seconds.
- call_notesstring
  This attribute is valid only on completion of a call.
  Therefore, for onCallCreate this value is null.
- created_timestring
  Timestamp of when the call is established, specified in the UTC format.
- directioninteger
  Direction of the call.
  Possible values (enum):
  Incoming: The call that triggered onCallCreate was received at a Freshworks number.
  Outgoing: The call that triggered onCallCreate was made from a Freshworks number.
- idinteger
  Identifier of the call object, auto-generated when the object is created at the start of a call.
- parent_call_idinteger
  This attribute is valid only for transferred calls.
  Therefore, for onCallCreate this value is null.
- participantsarray of objects
  Information about the agent and customer involved in the call.
  call_idinteger
  Identifier of the call object, auto-generated when the call is initiated.
  call_statusinteger
  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.
  caller_idinteger
  Identifier of the customer number.
  If participant_type value is Agent, the value of caller_id is null.
  caller_numberstring
  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.
  connection_typeinteger
  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.
  costinteger
  This attribute is valid only after the completion of the call.
  Therefore, for onCallCreate this value is null.
  cost_unitstring
  Currency in which cost is expressed, specified as a valid three character ISO currency code.
  created_timestring
  Timestamp of when the call participant object is created, specified in the UTC format.
  durationinteger
  This attribute is valid only after the completion of a call.
  Therefore, for onCallCreate this value is null.
  duration_unitstring
  Unit used to express duration.
  Possible value: seconds
  enqueued_timestring
  This attribute is valid only in the case of the call being assigned to a queue.
  Therefore, for onCallCreate this value is null.
  idinteger
  Identifier of the call participant object, auto-generated when the call participant object is created (when a participant joins a call) in the Freshworks system.
  participant_idinteger
  Identifier of the participant; either the agent’s id or customer’s id.
  participant_typestring
  Type of call participant.
  Possible values: Agent, Customer
  updated_timestring
  Timestamp of when the attributes of the call participant object are updated, specified in the UTC format.
- phone_numberstring
  Freshworks number from which the call is made or to which the call is received.
- phone_number_idinteger
  Identifier of the Freshworks 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 Freshworks system.
- recordingobject
  This attribute is valid only on completion of a call.
  Therefore, for onCallCreate this value is null.
- root_call_idinteger
  This attribute is valid only when child calls are created.
  Therefore, for onCallCreate this value is null.
- updated_timestring
  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.
changesobject
Changes that triggered the onCallUpdate event, specified as a JSON object of the following format:
```
{
  “<call.attribute that changed>”: [“New value”, “Old value”]
}
```
For onCallUpdate, this value is an empty object.

Sample payload

{
  "currentHost":{
    "subscribed_modules": [
      "call", "caller_conversation"
    ],
    "endpoint_urls": {
      "freshcaller": "https://subdomain.freshcaller.com"
    }
  },
  "data": {
    "actor": {
      "type": "system"
    },
    "associations": {},
    "call": {
      "assigned_agent_id": 694,
      "assigned_call_queue_id": null,
      "assigned_ivr_id": null,
      "assigned_team_id": null,
      "bill_duration": 9,
      "bill_duration_unit": "seconds",
      "call_notes": "Customer needs to cancel flight",
      "created_time": "2020-03-10T09:07:00.000Z",
      "direction": "outgoing",
      "id": 156,
      "parent_call_id": null,
      "participants": [
        {
          "call_id": 156,
          "call_status": 1,
          "caller_id": null,
          "caller_number": null,
          "connection_type": 1,
          "cost": null,
          "cost_unit": "usd",
          "created_time": "2020-03-10T09:07:00.000Z",
          "duration": 9,
          "duration_unit": "seconds",
          "enqueued_time": null,
          "id": 823,
          "participant_id": 694,
          "participant_type": "Agent",
          "updated_time": "2020-03-10T09:07:09.000Z"
        },
        {
          "call_id": 156,
          "call_status": 3,
          "caller_id": 7994085,
          "caller_number": "+12133701559",
          "connection_type": 0,
          "cost": 0,
          "cost_unit": "usd",
          "created_time": "2020-03-10T09:07:00.000Z",
          "duration": 0,
          "duration_unit": "seconds",
          "enqueued_time": null,
          "id": 321,
          "participant_id": 135,
          "participant_type": "Customer",
          "updated_time": "2020-03-10T09:07:44.000Z"
        }
      ],
      "phone_number": "+12133701559",
      "phone_number_id": 46851,
      "recording": null,
      "root_call_id": null,
      "updated_time": "2020-03-10T11:27:51.000Z"
    },
    "changes": {}
  },
  "event": "onCallUpdate",
  "region": "US",
  "timestamp": 1583839672
}

Configure onCallCreate and onCallUpdateOn this page

onCallCreate

Attributes of the data object

onCallUpdate

Attributes of the data object

Configure onCallCreate and onCallUpdate