Freshworks Developer Platform Docs

The onAgentUpdate event is triggered and the registered callback method is executed, when:

The agent status is modified.
The agent signs in or out of the Freshworks system.

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

manifest.json

"events": {
  "onAgentUpdate": {
    "handler": "onAgentUpdateCallback"
  }
}

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

server.js

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

Attributes of the data object

actorobject
Information pertaining to the entity (agent/ user) who triggered the onAgentUpdate event in the Freshworks system.
- account_adminboolean
  Specifies whether the actor is an account admin.
  Possible values: true, false
- account_idinteger
  Identifier of the organization’s Freshworks account, auto-generated when the account is configured.
- agentobject
  Information pertaining to an agent whose details were updated.
  account_idinteger
  Identifier of the organization’s Freshworks account, auto-generated when the account is configured.
  available_oninteger
  Medium in which the agent is available.
  Possible values:
  0: The agent is offline and unavailable to take calls.
  1: The agent is available to take calls on the browser.
  2: The agent is available to take calls on the mobile.
  browser_status_idinteger
  Identifier of the agent status in the browser.
  browser_status_namestring
  Status of the agent in the browser.
  common_status_idinteger
  Identifier of the agent status determined based on the status set in both the browser and the mobile app.
  common_status_namestring
  Status of the agent, automatically set according to the status preference selected by the agent on the browser and the mobile app.
  If the agent is available to take calls on either the browser or the mobile then the value of this attribute is set as Available.
  Note: If the browser status is set as Forward to phone and the agent is available to take calls on mobile,the browser status takes precedence. In this case, the value of this attribute is set as Forward to phone.
  created_atstring
  Timestamp of when the agent’s record is created in the Freshworks system, specified in the UTC format.
  deletedboolean
  Specifies whether the agent record is deleted from the Freshworks system.
  Possible values: true, false
  emailstring
  Email address of the agent.
  freshid_uuidstring
  Universally unique identifier of the agent across Freshworks’ master record.
  idinteger
  Identifier of the agent object, auto-generated when an agent’s information is configured in the Freshworks system.
  last_call_atstring
  Timestamp of when the agent handled the previous call in the Freshworks system, specified in the UTC format.
  last_seen_atstring
  Timestamp of when the agent was last active in the Freshworks system, specified in the UTC format.
  last_status_change_atstring
  Timestamp of when the agent status was last modified in the Freshworks system, specified in the UTC format.
  logged_inboolean
  Specifies whether the agent is logged into the Freshworks system.
  Possible values: true, false
  mobile_app_status_idinteger
  Identifier of the agent status in the mobile app.
  mobile_app_status_namestring
  Status of the agent in the mobile app.
  namestring
  Name of the agent.
  preferenceinteger
  Last availability status preference of the agent that is used to assign the current availability status, when the agent signs in to the Freshworks account or concludes a call.
  Possible values:
  0: Offline and unavailable.
  1: Available to take calls on the browser.
  2: Available to take calls on the mobile.
  statusinteger
  Status of the agent, automatically set according to the status preference selected by the agent.
  The default agent statuses and the corresponding agent.status values are,
  0: Status selected is Offline or any custom status
  1: Status selected is Online
  2: Status selected is Busy or whenever the user is on a call.
  3: Status is After Call Work (ACW) (the status is automatically selected as ACW after a call is disconnected and till the conversation widget is open).
  Custom statuses such as Away, In a meeting, and so on, can be added in Freshworks. The agent can upload these custom statuses when they are unavailable to receive or make a call. When an agent uploads the custom status as their availability status, then the value of status attribute is 0.
  teamsarray of objects
  Details of the teams to which the agent is associated, specified as an array.
  idstring
  Identifier of the team object, auto-generated when a new team is configured in the Freshworks system.
  namestring
  Name of the team.
  time_zonestring
  Time zone to which the agent belongs, specified in the RAILS timezone.name format.
  updated_atstring
  Timestamp of when the agent’s record is last updated in the Freshworks system, specified in the UTC format.
  user_idinteger
  Identifier of the agent who is also added as a user in the Freshworks system. All agents are also added as users in the Freshworks system.
  user_idinteger
  Identifier of the agent who is also added as a user in the Freshworks system. All agents are also added as users in the Freshworks system.
- confirmedboolean
  Specifies whether the actor’s account is activated by accessing the activation email.
  Possible values: true, false
- created_atstring
  Timestamp of when the actor object is created in the Freshworks system, specified in the UTC format.
- current_sign_in_atstring
  Timestamp of when the actor signed in for the current session in the Freshworks system, specified in the UTC format.
- deletedboolean
  Specifies whether the actor’s information is deleted from the Freshworks system.
  Possible values: true, false
- facebook_idstring
  Identifier of the actor’s facebook account.
- failed_attemptsinteger
  Number of times the actor attempts to login and fails. Multiple, incorrect login attempts trigger the security protocol and lock the actor out of the Freshworks account.
- freshid_uuidstring
  Universally unique identifier of the agent across Freshworks’ master record.
- idinteger
  Identifier of the actor who triggered the product event.
  For onAgentUpdate event, the value of this attribute is agent.user_id.
- languagestring
  Preferred language selected by the actor when setting up the user profile.
- last_sign_in_atstring
  Timestamp of when the actor previously signed in to the Freshworks system, specified in the UTC format.
- locked_atstring
  Timestamp of when the actor was blocked from accessing the Freshworks system due to multiple failed login attempts, specified in the UTC format.
- mobilestring
  Mobile number of the actor.
- namestring
  Name of the actor.
  For onAgentUpdate event, the value of this attribute is agent.name.
- phonestring
  Telephone number of the actor.
- primary_emailobject
  Information pertaining to the primary email of the actor.
  account_idinteger
  Identifier of the organization’s Freshworks account, auto-generated when the account is configured.
  confirmedboolean
  Specifies whether the agent’s account is activated by accessing the activation email.
  Possible values: true, false
  created_atstring
  Timestamp of when the primary email object is created in the Freshworks system, specified in the UTC format.
  emailstring
  Primary email address of the agent.
  idinteger
  Identifier of the primary email object, auto-generated when the agent’s primary email is configured in the Freshworks system.
  primary_emailboolean
  Specifies whether the email is a primary email.
  For onAgentUpdate event, the value of this attribute is true.
  Possible values: true, false
  updated_atstring
  Timestamp of when the primary email object is last updated in the Freshworks system, specified in the UTC format.
  user_idinteger
  Identifier of the agent who is also added as a user in the Freshworks system. All agents are also added as users in the Freshworks system.
- sign_in_countinteger
  Number of times the actor has signed in.
- time_zonestring
  Time zone selected by the actor when setting up the user profile.
- twitter_idstring
  Identifier of the actor’s twitter account.
- updated_atstring
  Timestamp of when the actor object is last updated in the Freshworks system, specified in the UTC format.
- uuidstring
  Unique user identifier, this value is auto-generated.
agentobject
Information pertaining to an agent whose details are modified in the Freshworks system.
- account_idinteger
  Identifier of the organization’s Freshworks account, auto-generated when the account is configured.
- available_oninteger
  Medium in which the agent is available.
  Possible values:
  0: The agent is offline and unavailable to take calls.
  1: The agent is available to take calls on the browser.
  2: The agent is available to take calls on the mobile.
- browser_status_idinteger
  Identifier of the agent status in the browser.
- browser_status_namestring
  Status of the agent in the browser.
- common_status_idinteger
  Identifier of the agent status determined based on the status set in both the browser and the mobile app.
- common_status_namestring
  Status of the agent, automatically set according to the status preference selected by the agent on the browser and the mobile app.
  If the agent is available to take calls on either the browser or the mobile then the value of this attribute is set as Available.
  Note: If the browser status is set as Forward to phone and the agent is available to take calls on mobile,the browser status takes precedence. In this case, the value of this attribute is set as Forward to phone.
- created_atstring
  Timestamp of when the agent’s record is created in the Freshworks system, specified in the UTC format.
- deletedboolean
  Specifies whether the agent record is deleted from the Freshworks system.
  Possible values: true, false
- emailstring
  Email address of the agent.
- freshid_uuidstring
  Universally unique identifier of the agent across Freshworks’ master record.
- idinteger
  Identifier of the agent object, auto-generated when an agent’s information is configured in the Freshworks system.
- last_call_atstring
  Timestamp of when the agent handled the previous call in the Freshworks system, specified in the UTC format.
- last_seen_atstring
  Timestamp of when the agent was last active in the Freshworks system, specified in the UTC format.
- last_status_change_atstring
  Timestamp of when the agent status was last modified in the Freshworks system, specified in the UTC format.
- logged_inboolean
  Specifies whether the agent is logged into the Freshworks system.
  Possible values: true, false
- mobile_app_status_idinteger
  Identifier of the agent status in the mobile app.
- mobile_app_status_namestring
  Status of the agent in the mobile app.
- namestring
  Name of the agent.
- preferenceinteger
  Last availability status preference of the agent that is used to assign the current availability status, when the agent signs in to the Freshworks account or concludes a call.
  Possible values:
  0: Offline and unavailable.
  1: Available to take calls on the browser.
  2: Available to take calls on the mobile.
- statusinteger
  Status of the agent, automatically set according to the status preference selected by the agent.
  The default agent statuses and the corresponding agent.status values are,
  0: Status selected is Offline or any custom status
  1: Status selected is Online
  2: Status selected is Busy or whenever the user is on a call.
  3: Status is After Call Work (ACW) (the status is automatically selected as ACW after a call is disconnected and till the conversation widget is open).
  Custom statuses such as Away, In a meeting, and so on, can be added in Freshworks. The agent can upload these custom statuses when they are unavailable to receive or make a call. When an agent uploads the custom status as their availability status, then the value of status attribute is 0.
- teamsarray of objects
  Details of the teams to which the agent is associated, specified as an array.
  idstring
  Identifier of the team object, auto-generated when a new team is configured in the Freshworks system.
  namestring
  Name of the team.
- time_zonestring
  Time zone to which the agent belongs, specified in the RAILS timezone.name format.
- updated_atstring
  Timestamp of when the agent’s record is last updated in the Freshworks system, specified in the UTC format.
- user_idinteger
  Identifier of the agent who is also added as a user in the Freshworks system. All agents are also added as users in the Freshworks system.
- user_idinteger
  Identifier of the agent who is also added as a user in the Freshworks system. All agents are also added as users in the Freshworks system.
associationsobject
All associated objects of the agent object, which specify additional information pertaining to the agent.

changesobject

Changes that triggered the onAgentUpdate event, specified as a JSON object of the following format:

{
  "model_changes": {
    //For non-array attributes
    "<agent.attribute that changed>": ["Old value", "New value"]
  }
}

Example

{
  "model_changes": {
    "updated_at": [
        "2022-08-29 18:45:26 UTC",
        "2022-08-30 08:05:50 UTC"
    ]
  }
}

model_changesobject
List of all attributes whose values have changed along with the old and modified values of the attributes.

Sample payload

{
  "currentHost":{
    "subscribed_modules": [
      "caller_agent"
    ],
    "endpoint_urls": {
      "freshcaller": "https://subdomain.freshcaller.com"
    }
  },
  "data": {
    "actor": {
      "account_admin": true,
      "account_id": 682861,
      "agent": {
        "account_id": 682861,
        "available_on": 0,
        "browser_status_id": 5642131,
        "browser_status_name": "Offline",
        "common_status_id": 5642131,
        "common_status_name": "Offline",
        "created_at": "2021-12-10T12:51:59Z",
        "deleted": false,
        "email": "sample@example.com",
        "freshid_uuid": "389398835151017469",
        "id": 787096,
        "last_call_at": "2022-08-12T05:08:56Z",
        "last_seen_at": "2022-08-12T05:08:56Z",
        "last_status_change_at": "2022-08-12T05:08:56Z",
        "logged_in": false,
        "mobile_app_status_id": 5642131,
        "mobile_app_status_name": "Offline",
        "name": "sample name",
        "preference": 0,
        "status": 0,
        "teams": [
          {
            "id": 301395,
            "name": "group2"
          }
        ],
        "time_zone": "Etc/UTC",
        "user_id": 856523,
        "updated_at": "2022-08-30T08:05:50Z"
      },
      "confirmed": true,
      "created_at": "2021-12-10T12:51:58Z",
      "current_sign_in_at": "2022-08-29T18:45:26Z",
      "deleted": false,
      "facebook_id": null,
      "failed_attempts": 0,
      "freshid_uuid": "389398835151017469",
      "id": 856523,
      "language": null,
      "last_sign_in_at": "2022-08-29T14:28:54Z",
      "locked_at": null,
      "mobile": null,
      "name": "omniagent one",
      "phone": "",
      "primary_email": {
        "account_id": 682861,
        "confirmed": true,
        "created_at": "2021-12-10T12:51:58Z",
        "email": "omni.agent@example.com",
        "id": 856514,
        "primary_email": true,
        "updated_at": "2021-12-10T12:51:59Z",
        "user_id": 856523
      },
      "shared": false,
      "sign_in_count": 248,
      "time_zone": "UTC",
      "twitter_id": null,
      "updated_at": "2022-08-29T18:45:26Z",
      "uuid": "389398835151017469"
    },
    "agent": {
      "account_id": 682861,
      "available_on": 0,
      "browser_status_id": 5642131,
      "browser_status_name": "Offline",
      "common_status_id": 5642131,
      "common_status_name": "Offline",
      "created_at": "2021-12-10T12:51:59Z",
      "deleted": false,
      "email": "sample@example.com",
      "freshid_uuid": "sample_uuid",
      "id": 787096,
      "last_call_at": "2022-08-12T05:08:56Z",
      "last_seen_at": "2022-08-12T05:08:56Z",
      "last_status_change_at": "2022-08-12T05:08:56Z",
      "logged_in": false,
      "mobile_app_status_id": 5642131,
      "mobile_app_status_name": "Offline",
      "name": "omniagent one",
      "preference": 0,
      "status": 0,
      "teams": [
        {
            "id": 301395,
            "name": "group2"
        }
      ],
      "time_zone": "Etc/UTC",
      "updated_at": "2022-08-30T08:05:50Z",
      "user_id": 856523
    },
    "associations": {},
    "changes": {
      "model_changes": {
        "updated_at": [
            "2022-08-29 18:45:26 UTC",
            "2022-08-30 08:05:50 UTC"
        ]
      }
    }
  },
  "event": "onAgentUpdate",
  "region": "US",
  "timestamp": 1583839672,
  "version": "2.0"
}

Configure onAgentUpdate

Attributes of the data object