NewAgentic Developer Toolkit with Agent Skills is now GA — Build apps faster with AI in minutes. Try Now

Configure onConversationCreate and onConversationUpdate

onConversationCreate

When a conversation is initiated by a user, the onConversationCreate event is invoked and the registered callback method is executed.

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

manifest.json
"events": {
  "onConversationCreate": {
    "handler": "onConversationCreateCallback"
  }
}

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

server.js
exports = {
  onConversationCreateCallback: function(payload) {
    console.log("Logging arguments from onConversationCreate event: " + JSON.stringify(payload));
  }
}

Attributes of the data object

  • actorobject

    Details of the entity that triggered the onConversationCreate event.

    For onConversationCreate, it is a user.

    • avatarobject

      Image associated with the actor.

      • urlstring

        Link from which the image is fetched.

    • emailstring

      Email address of the actor.

    • first_namestring

      Business name of the actor.

    • idstring

      Identifier associated with the actor. Here, it is the user_id.

    • last_namestring

      Last name of the actor.

    • phonestring

      Phone number of the actor.

    • typestring

      Descriptive identifier of the entity who posted the message in the conversation. This value is user for onConversationCreate.

  • associationsobject

    Associated objects related to the conversation object.

  • conversationobject

    Details of the conversation object created when the onConversationCreate event is triggered.

    • app_idstring

      Alias of the Freshworks account ID.

    • assigned_group_idstring

      Identifier of the group to which a conversation is assigned for resolution. This value is null for onConversationCreate.

    • assigned_timestring

      Timestamp of when a conversation is assigned to an agent or a group, specified in the UTC format.

      This value is null for onConversationCreate.

    • channel_idstring

      Identifier of the topic under which the user posted the message that triggered the onConversationCreate event.

    • conversation_idstring

      Identifier of the conversation object, auto-generated when the conversation is initiated.

    • created_timestring

      Timestamp of when the conversation object is created, specified in the UTC format.

    • messagesarray of objects

      Message that constitutes the conversation.

      • actor_idstring

        Identifier of the entity who posted the message. Here, it is the user_id.

      • actor_typestring

        Descriptive identifier of the entity that posted the message in the conversation. This value is user for onConversationCreate.

      • app_idstring

        Alias of the Freshworks account ID.

      • channel_idstring

        Identifier of the topic under which the message is posted. This is an auto-generated value.

      • conversation_idstring

        Identifier of the conversation object. This is an auto-generated value.

      • created_timestring

        Timestamp of when the conversation is created, specified in the UTC format.

      • idstring

        Identifier of the message object. This is an auto-generated value.

      • message_partsarray of objects

        Different parts of a message posted to the conversation. For example, plain text, images, url buttons, and so on. The message can be a combination of these attributes.

        • collectionobject

          Combination of text, image, and url_button.

        • imageobject

          Image part of the message in the conversation.

          • urlstring

            Location of the image file.

        • textobject

          Text part of a message in the conversation.

          • contentstring

            Actual content of the text message.

        • url_buttonobject

          Links in the message.

          • urlstring

            The hyperlink that is accessed by clicking the corresponding label.

          • labelstring

            Text (in the message) that is used as the connector to the hyperlink.

          • targetstring

            Location where the link is opened.

            Possible values (enum): _self, _blank

            Default value: _blank

      • message_typestring

        Descriptive identifier specifying whether the message is a private or normal message. This value is normal for onConversationCreate.

    • reopened_timestring

      Timestamp of when a conversation is reopened, specified in the UTC format.

      This value is null for onConversationCreate.

    • response_due_typestring

      Priority assigned to a conversation. This value is FIRST_RESPONSE_DUE for onConversationCreate.

    • statusstring

      Status of a conversation. This value is new for onConversationCreate.

    • user_idstring

      Identifier of the user who initiates the conversation, auto-generated when the onConversationCreate event is triggered.

onConversationUpdate

The onConversationUpdate event is triggered in the Freshworks system when,

  • A conversation is assigned to an agent or a group.
  • An existing conversation is reassigned to an agent or unassigned from a group.
  • A conversation is resolved or reopened.

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

manifest.json
"events": {
  "onConversationUpdate": {
    "handler": "onConversationUpdateCallback"
  }
}

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

server.js
exports = {
  onConversationUpdateCallback: function(payload) {
    console.log("Logging arguments from onConversationUpdate event: " + JSON.stringify(payload));
  }
}

Attributes of the data object

  • actorobject

    Details of the entity that triggered the onConversationUpdate event.

    • avatarobject

      Image associated with the actor.

      • urlstring

        Link from which the image is fetched.

    • emailstring

      Email address of the actor.

    • first_namestring

      Business name of the actor.

    • idstring

      Identifier associated with the actor. Here, it is the user_id.

    • last_namestring

      Last name of the actor.

    • phonestring

      Phone number of the actor.

    • typestring

      Descriptive identifier of the entity who posted the message in the conversation. This value is user for onConversationCreate.

  • associationsobject

    All associated objects of the conversation object, which specify additional information pertaining to the conversation updated.

    • agentobject

      Details of the agent to whom the conversation is assigned for resolution.

      • agent_statusobject

        Custom status set by the agent.

        • idinteger

          Identifier of custom status, auto-generated when a new status is added to the Freshworks system.

        • namestring

          Title of the status.

      • app_idstring

        Auto-assigned organization-level identifier that helps integrate applications with Freshworks.

      • availability_statusstring

        Status of the agent’s availability for conversation assignment.

        Possible values: AVAILABLE, UNAVAILABLE

      • avatarobject

        Image associated with the agent.

        • urlstring

          Link from which the image is fetched.

      • biographystring

        Meaningful description about the agent.

      • created_timestring

        Timestamp of when the agent’s record is created in the Freshworks system, specified in the UTC format.

      • emailstring

        Email address of the agent.

      • first_namestring

        Business name of the agent.

      • freshid_group_idsarray of strings

        Universally unique identifiers, across Freshworks’ master record, that identify the groups to which the agent belongs, specified as an array.

      • freshid_uuidstring

        Universally unique identifier of the agent across Freshworks’ master record.

      • groupsarray of integers

        Identifiers of the groups to which the agent belongs, specified as an array.

      • idstring

        Identifier of the agent object, auto-generated when the agent’s information is configured in the Freshworks system.

      • internal_fieldsstring

        For internal purposes only.

      • internalDBAppIdinteger

        For internal purposes only.

      • internalIdstring

        For internal purposes only.

      • is_deactivatedboolean

        Specifies whether the agent is deactivated in the Freshworks system.

        Possible values: true, false

      • is_deletedboolean

        Specifies whether the agent's details are deleted from the Freshworks system.

        Possible values: true, false

      • last_namestring

        Last name of the agent.

      • localestring

        Language associated with the agent’s location, specified in the ISO-639 code.

      • login_statusboolean

        Specifies whether the agent is logged into the Freshworks system.

        Possible values: true, false

      • max_active_convinteger

        Maximum number of active conversations that the agent can manage.

      • org_agent_idstring

        Organization-level identifier of the agent associated with the conversation.

      • org_contact_idstring

        Organization-level identifier of the user who initiated the conversation.

      • phonestring

        Phone number of the agent.

      • role_idstring

        System-generated identifier of the role assigned to the agent, specifying the level of access permissions the agent has in the Freshworks system.

        Possible values: ACCOUNT_ADMIN, ADMIN, SUPER_USER, AGENT

      • role_namestring

        Meaningful identifier of the agent’s role that specifies the agent’s level of access in the Freshworks system.

        Possible values: Account admin, Admin, Super user, Agent

      • skill_idstring

        Identifiers of the skill mapped to the agent.

        When a new skill or load is created in the Freshworks system, a skill_id value is auto-generated and assigned to the skill.

      • statusinteger

        Status set by the agent.

        Possible values:

        • 0: Active on IntelliAssign
        • 1: Unavailable
      • timezonestring

        Timezone to which the agent belongs, in the Area/Location format.

    • channelobject

      Details of the topic under which the message is posted.

      • assign_to_groupobject

        Details of the group associated with the topic.

        If a group is associated with a topic, whenever a message is received under the topic, it is automatically assigned to the associated group.

        • account_aliasstring
        • agent_uidsarray of strings

          Organization-level identifier of the agents associated with the group, specified as an array.

        • agentsarray of strings

          Identifier of the agents associated with the group, specified as an array.

        • automatic_agent_assignmentobject

          Details of the assignment rules, based on which the conversation is auto-assigned to the agent.

          • enabledboolean

            Specifies whether the auto-assignment is enabled.

            Possible values: true, false

          • typestring

            Type of assignment rule.

          • settingsobject
        • business_calendarstring

          Details of the business hours associated with the group.

        • chat_group_idstring
        • created_atstring

          Timestamp of when the group is created in the Freshworks system, specified in the UTC format.

        • descriptionstring

          Meaningful definition that specifies the purpose of the group.

        • group_uid

          Organization-level identifier of the agent group.

        • idstring

          Identifier of the group object, auto-generated when a new group is configured in the Freshworks system.

        • internal_fieldsstring

          For internal purposes only.

        • is_deactivatedboolean

          Specifies whether the group is deactivated from the Freshworks system. Possible values: true, false

        • namestring

          Descriptive identifier for the group.

        • org_group_idstring

          Organization-level identifier of the group.

        • routing_typestring

          Type of assignment rules, based on which the conversation is auto-assigned to the group.

          Possible values:

          • OCR (string): The agent is auto-assigned tickets, chats and phone calls based on the Omni-route assignment rule.
          • INTELLIASSIGN (string): The agent is auto-assigned conversations based on the round-robin approach or load based approach.
          • DISABLED (string): Auto-assignment of conversation is disabled. For more information about the assignment rules, see IntelliAssign in Freshchat.
        • updated_atstring

          Timestamp of when the group details are last updated in the Freshworks system, specified in the UTC format.

    • configured_bot_detailsstring

      Details of the chatbot associated with the topic.

    • enabledboolean

      Specifies whether a channel is currently available. Channels can be created by a business but can be disabled until a further point in time when there is a necessity to open the channel.

      Possible values: true, false

    • iconobject

      Pictorial representation of the topic.

      • urlstring

        Location of the image file.

    • idstring

      Identifier of the channel object, auto-generated when a topic is created in the Freshworks system.

    • localestring

      Primary language associated with the topic.

    • namestring

      Name of the topic. For example, Sales, Support, and so on.

    • publicboolean

      Specifies whether the channel is open to receive messages from all users.

      Possible values: true, false

    • tagsarray of strings

      Labels used to sort the conversations received under a topic, specified as an array.

    • updated_timestring

      Timestamp of when the topic is last updated, specified in the UTC format.

    • welcome_messageobject

      Message that sets context about the purpose of the topic.

    • groupobject

      Details of the group to which the conversation is assigned for resolution.

      • account_aliasstring
      • agent_uidsarray of strings

        Organization-level identifier of the agents associated with the group, specified as an array.

      • agentsarray of strings

        Identifier of the agents associated with the group, specified as an array.

      • automatic_agent_assignmentobject

        Details of the assignment rules, based on which the conversation is auto-assigned to the agent.

        • enabledboolean

          Specifies whether the auto-assignment is enabled.

          Possible values: true, false

        • typestring

          Type of assignment rule.

        • settingsobject
      • business_calendarstring

        Details of the business hours associated with the group.

      • chat_group_idstring
      • created_atstring

        Timestamp of when the group is created in the Freshworks system, specified in the UTC format.

      • descriptionstring

        Meaningful definition that specifies the purpose of the group.

      • group_uid

        Organization-level identifier of the agent group.

      • idstring

        Identifier of the group object, auto-generated when a new group is configured in the Freshworks system.

      • internal_fieldsstring

        For internal purposes only.

      • is_deactivatedboolean

        Specifies whether the group is deactivated from the Freshworks system.

        Possible values: true, false

      • namestring

        Descriptive identifier for the group.

      • org_group_idstring

        Organization-level identifier of the group.

      • routing_typestring

        Type of assignment rules, based on which the conversation is auto-assigned to the group.

        Possible values:

        • OCR (string): The agent is auto-assigned tickets, chats and phone calls based on the Omni-route assignment rule.
        • INTELLIASSIGN (string): The agent is auto-assigned conversations based on the round-robin approach or load based approach.
        • DISABLED (string): Auto-assignment of conversation is disabled. For more information about the assignment rules, see IntelliAssign in Freshchat.
      • updated_atstring

        Timestamp of when the group details are last updated in the Freshworks system, specified in the UTC format.

    • label_categorystring

      Name of the conversation label created to categorize conversations.

    • label_subcategorystring

      Name of sub-category label associated with the conversation.

    • userobject

      Details of the user who initiated the conversation.

      • avatarobject

        Image associated with the user.

        • urlstring

          Link from which the image is fetched.

      • created_timestring

        Timestamp of when the user record is created in the Freshworks system, specified in the UTC format.

      • emailstring

        Email address of the user.

      • first_namestring

        Business name of the user.

      • idstring

        Identifier of the user object, auto-generated when a user record is created in the Freshworks system.

      • last_namestring

        Last name of the user.

      • login_statusboolean

        Specifies whether the user is logged into the Freshworks system. Possible values: true, false

      • org_contact_idstring

        Organization-level identifier of the user who initiated the conversation.

      • phonestring

        Phone number of the user.

      • propertiesarray of property objects

        Custom properties for additional user information. This attribute contains custom property names and the corresponding values, as a valid JSON object of key (custom property name)-value (custom property’s value) pairs.

        • namestring

          Name of the custom property.

        • valuestring

          Value of the custom property.

      • reference_idstring
      • restore_idstring

        Unique identifier of the user, auto-generated when a conversation is initiated in the Freshworks system.

        When the logged-in user is using a new device or browser for initiating a conversation, restore_id identifies the user for restoring the past conversations.

      • social_profilesarray of objects

        Details of the social media profiles of the user who initiated the conversation, specified as an array.

        • idinteger

          User handle of the user on the social media platform.

        • stringstring

          Name of the social media platform.

          Possible values: facebook, twitter, skype, linkedin

      • statusstring

        Status of the user.

        Possible values: active, deleting, deleted

      • updated_timestring

        Timestamp of when the user details are last updated in the Freshworks system, specified in the UTC format.

  • changesobject

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

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

    Example

    "changes": {
  "misc_changes": null,
  "model_changes": {
    "assigned_agent_id": [
      "2823233e-7122-4f87-9d56-38aaaaeb676a",
      null
    ],
    "assigned_group_id": [
      "40753ac3-1f66-40d9-b903-23db0a9a70b0",
      null
    ],
    "status": [
      "new",
      "resolved"
    ]
  },
  "system_changes": null
},
    • misc_changesobject

      List of all miscellaneous database parameters whose values have changed, along with the old and modified values.

    • model_changesobject

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

    • system_changesobject

      List of all system-level parameters whose values have changed, along with the old and modified values.

  • conversationobject

    Details of the conversation object created when the onConversationCreate event is triggered.

    • app_idstring

      Auto-assigned organization-level identifier that helps integrate applications with Freshworks.

    • assigned_agent_idstring

      Identifier of the agent assigned to the conversation, auto-generated when an agent’s information is configured in the Freshworks system.

    • assigned_group_idstring

      Identifier of the group to which the conversation is assigned for resolution.

    • assigned_org_agent_idstring

      Organization-level identifier of the agent to whom the conversation is assigned for resolution.

    • assigned_org_group_idstring

      Organization-level identifier of the group to which a conversation is assigned for resolution.

    • assigned_timestring

      Timestamp of when the conversation is assigned to a group or an agent, specified in the UTC format.

    • channel_idstring

      Identifier of the topic under which the conversation is created, auto-generated when a topic is created in the Freshworks system.

    • conversation_idstring

      Identifier of the conversation object, auto-generated when a conversation record is created in the Freshworks system.

    • created_timestring

      Timestamp of when the conversation is created in the Freshworks system, specified in the UTC format.

    • do_not_auto_resolveboolean

      Specifies whether the conversation can be automatically resolved after a specified time period.

      Possible values: true, false

    • first_agent_assigned_timestring

      Timestamp of when an agent is first assigned to the conversation, specified in the UTC format.

    • first_group_assigned_timestring

      Timestamp of when a group was first assigned to the conversation, specified in the UTC format.

    • group_assigned_timestring

      Timestamp of when the conversation is assigned to a group, specified in the UTC format.

    • is_offlineboolean

      Specifies whether the agent assigned to the conversation is available online.

      Possible values: true, false

    • label_category_idstring

      Conversation labels help organize conversations into categories and sub-categories based on common customer support issues.

      label_category_id is the identifier of the label associated with the updated conversation.

    • label_subcategory_idstring

      Conversation labels help organize conversations into categories and sub-categories based on common customer support issues.

      label_subcategory_id is the identifier of the sub-category label associated with the updated conversation.

    • messagesarray of message objects

      Details of the messages that constitute the conversation.

      • actor_idstring

        Identifier of the entity who sends the message to the conversation.

        If a user sends the message, the value of this attribute is the same as conversation.user_id.

        If an agent sends the message, the value of this attribute is the same as conversation.assigned_agent_id.

      • actor_typestring

        A meaningful identifier of the entity who sends the message to the conversation.

        Possible values: user, agent

      • app_idstring

        Auto-assigned organization-level identifier that helps integrate applications with Freshworks.

      • channel_idstring

        Identifier of the topic under which the message is created, auto-generated when a topic is created in the Freshworks system.

      • conversation_idstring

        Identifier of the conversation object, auto-generated when a conversation record is created in the Freshworks system.

        The value of message.conversation_id identifies the conversation which includes the message.

      • created_timestring

        Timestamp of when the message is created, specified in the UTC format.

      • idstring

        Identifier of the message object, auto-generated when a new message is successfully sent in a conversation.

      • in_reply_tostring

        Identifier of the message to which this message is a reply.

      • interaction_idstring

        Identifier of the interaction, auto-generated when a conversation is initiated by an user or an agent.

        An interaction is a conversation from the time it is initiated to the time the conversation is resolved.

      • is_agent_first_responseboolean

        Specifies whether the message is the first response an agent is sending after the conversation is initiated.

        Possible values: true, false

      • is_agent_interim_first_responseboolean

        Specifies whether the message is the first response from the agent engaged in a conversation with the user.

        Possible values: true, false

      • is_first_messageboolean

        Specifies whether the message initiated the conversation.

        Possible values: true, false

      • message_partsarray of message part objects

        Different parts of a message posted to the conversation. For example, plain text, images, url buttons, and so on. The message can be a combination of these attributes.

      • message_sourcestring

        Source through which the message is initiated.

        Possible values: web, system, mobile, api, freshdesk, zendesk, smooch, facebook_native

      • message_typestring

        Type of message.

        Possible values:

        • normal: Normal message that the agent or user has sent.
        • private: Private message that the agent adds to the conversation and is not visible to the user.
        • system: System-generated message.
      • meta_dataobject

        Details of the conversation to which the message belongs.

        • isResolvedboolean

          Specifies whether the conversation is resolved.

          Possible values: true, false

      • org_actor_idstring

        Organization-level identifier of the actor who triggered the onConversationUpdate event.

      • org_contact_idstring

        Organization-level identifier of the user who sent the message. If an agent or the system sends the message, this attribute value is null.

      • response_due_typestring

        Specifies whether a response is due for a message in the conversation and if so, whether the response due is a first response.

        Possible values: FIRST_RESPONSE_DUE, NO_RESPONSE_DUE, RESPONSE_DUE

      • statusstring

        Status of the message.

      • stepIdstring

        For internal purposes only.

    • org_contact_idstring

      Organization-level identifier of the user who initiated the conversation.

    • reopened_timestring

      Timestamp of when the conversation is reopened, specified in the UTC format. For onConversationCreate, this attribute value is null.

    • response_due_typestring

      Specifies whether a response is due for a message in the conversation and if so, whether the response due is a first response.

      Possible values: FIRST_RESPONSE_DUE, NO_RESPONSE_DUE, RESPONSE_DUE

    • resolved_timestring

      Timestamp of when the conversation is resolved, specified in the UTC format. For onConversationUpdate, the value of this attribute is null.

    • sourcestring

      Source through which a user initiates the conversation.

      Possible values: MOBILE, WEBCHAT, FACEBOOK_MESSENGER, WHATSAPP, FB_NATIVE, ABC, LINE, FRESHBOTS_WIDGET, GBM, SMS

    • statisticsobject

      Detailed information about the conversation.

      • agent_reassignment_time_bhrsinteger

        Number of business hours taken to reassign a conversation to another agent after the first assignment, during business hours.

      • agent_reassignment_time_chrsinteger

        Number of hours taken to reassign a conversation to another agent after the first assignment, regardless of the business hours.

      • first_agent_assignment_time_bhrsinteger

        Number of hours within which an agent is assigned to the conversation in the Freshworks system, during business hours.

      • first_agent_assignment_time_chrsinteger

        Number of hours within which an agent is assigned to the conversation in the Freshworks system, regardless of the business hours.

      • first_group_assignment_time_bhrsinteger

        Number of hours within which the conversation is assigned to a group in the Freshworks system, during business hours.

      • first_group_assignment_time_chrsinteger

        Number of hours taken to assign the conversation to a group in the Freshworks system.

      • first_response_time_bhrsinteger

        Number of hours taken to respond to a conversation after an agent is assigned, during business hours.

      • first_response_time_chrsinteger

        Number of hours taken to respond to a conversation after an agent is assigned, regardless of the business hours.

      • group_reassignment_time_bhrsinteger

        Number of hours taken to reassign a conversation to another group after the first assignment, during business hours.

      • group_reassignment_time_chrsinteger

        Number of hours taken to reassign a conversation to another group after the first assignment, regardless of the business hours.

      • resolution_time_bhrsinteger

        Number of hours taken to resolve a conversation, during business hours.

      • resolution_time_chrsinteger

        Number of hours taken to resolve a conversation, regardless of the business hours.

      • wait_time_bhrsinteger

        Number of hours a user has to wait before receiving a response to the message, during business hours.

      • wait_time_chrsinteger

        Number of hours a user has to wait before receiving a response to the message, regardless of the business hours.

    • statusstring

      Status of the conversation.

      Possible values: new, resolved, assigned

    • updated_timestring

      Timestamp of when the user details are last updated in the Freshworks system, specified in the UTC format.

    • user_idstring

      Identifier of the user object, auto-generated when a user record is created in the Freshworks system. The value of conversation.user_id identifies the user who initiated the conversation.

    • usersarray of strings

      Details of the users associated with the conversation.