Product Events

GETTING STARTED
Quick Start
Sample Apps
What's New
Reference
Freshworks CLI
External Libraries
JWT
Configuration
App Manifest
Placeholders
Installation Parameters
Custom Installation Page
Basic Features
App Lifecycle Methods
Data Method
Events Method
Interface Method
Advanced Features
Data Storage
Request Method
Instance Method
OAuth
Serverless
Overview
Product Events
- Payload
- Registration
- onConversationCreate
- onConversationUpdate
- onMessageCreate
- onUserCreate
- onUserUpdate
- Testing
App Setup Events
External Events
Scheduled Events
Server Method Invocation
Errors and Validations
Troubleshooting
Lint Validations
GUIDELINES
App Content Guidelines
Code Review Guidelines
Marketplace Listing
Types of Apps
Freshchat Apps
Custom Apps
External Apps
Other Resources
Terms of Use

Product Events

These are Freshchat events, such as onConversationCreate, onUserCreate, and onMessageCreate, which can trigger apps. When product events occur, the appropriate method in the server.js file is invoked.

Note: The serverless component of the app is executed in sandbox mode where some methods, such as setTimeout and setInterval, cannot be used.

Payload

When a supported product event occurs, the corresponding method in the server.js file is invoked and the following payload is passed to the app.

Copied Copy

1
2
3
4
5
6
7
8
9
10
11
12
13 {
  "account_id" : "value",
  "event"  : "value",
  "region"  : "value",
  "timestamp"  : "value",
  "data" : {
    //“data” contains the list of objects related to the event.
  },
  "iparams" : {
      "Param1" : "value",
      "Param2" : "value"
  }
}

EXPAND ↓

The following table lists the payload attributes.

Attribute	Type	Description
account_id	number	Freshchat account ID.
event	string	Name of the event.
region	string	Region where the app is installed, will be either "US", "EU", "EUC", or "AUS".
timestamp	number	App installation timestamp in the epoch format.
iparams	object	Installation parameters.

Registration

When a product event occurs, an event listener is required for the appropriate method to be invoked. This is done in the following format.

server.js Copied Copy

1
2
3
4
5
6
7
8
9 exports = {
  events: [
    { event: "eventName", callback: "eventCallbackMethod" }
  ],
  eventCallbackMethod: function(payload) {
   //Multiple events can access the same callback
    console.log("Logging arguments from the event: " + JSON.stringify(payload));
  }
}

Note:
1. Include the event and callback definition in the exports block.
2. Include only one callback method for an event.

onConversationCreate

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

Use the following format to include the event in the server.js file.

Copied Copy

1
2
3
4
5
6
7
8 exports = {
  events: [
    { event: "onConversationCreate", callback: "onConversationCreateCallback" }
  ],
  onConversationCreateCallback: function(payload) {
    console.log("Logging arguments from onConversationCreate event: " + JSON.stringify(payload));
  }
}

Sample Reply 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
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97 {
  "data": {
    "conversation": {
      "user_id": "98c76ba0-6b38-499b-9c37-e104774276b8",
      "reopened_time": null,
      "assigned_time": null,
      "created_time": "2019-07-29T14:51:56.933Z",
      "response_due_type": "FIRST_RESPONSE_DUE",
      "conversation_id": "8c65b83e-5be0-45f4-9645-9ddbbe015f4d",
      "app_id": "032c91b6-4b46-4f5b-adcb-102c72cd4efa",
      "messages": [
        {
          "message_parts": [
            {
              "text": {
                "content": "Hi"
              }
            }
          ],
          "app_id": "032c91b6-4b46-4f5b-adcb-102c72cd4efa",
          "actor_id": "98c76ba0-6b38-499b-9c37-e104774276b8",
          "id": "59abdc73-ce82-4a33-be10-93e61edc416a",
          "channel_id": "167e73ff-9dd5-4e2d-8c50-74161b38a6fe",
          "conversation_id": "8c65b83e-5be0-45f4-9645-9ddbbe015f4d",
          "message_type": "normal",
          "actor_type": "user",
          "created_time": "2019-07-29T14:51:56.933Z"
        }
      ],
      "status": "new",
      "channel_id": "167e73ff-9dd5-4e2d-8c50-74161b38a6fe",
      "assigned_group_id": "40753ac3-1f66-40d9-b903-23db0a9a70b0"
    },
    "associations": {
      "group": {
        "id": "40753ac3-1f66-40d9-b903-23db0a9a70b0",
        "name": "Support",
        "description": "L1 support group",
        "routing_type": "DISABLED"
      },
      "channel": {
        "id": "167e73ff-9dd5-4e2d-8c50-74161b38a6fe",
        "icon": {},
        "updated_time": "2019-05-20T12:21:29.718Z",
        "enabled": true,
        "public": true,
        "name": "Inbox",
        "tags": [],
        "welcome_message": {
          "message_parts": [
            {
              "text": {
                "content": "Hello there! Need help? Reach out to us right here, and we'll get back to you as soon as we can!"
              }
            }
          ],
          "message_type": "normal"
        },
        "locale": ""
      },
      "user": {
        "properties": [
          {
            "name": "siteId",
            "value": "Orders"
          }
        ],
        "created_time": "2019-07-29T20:21:42.063Z",
        "id": "98c76ba0-6b38-499b-9c37-e104774276b8",
        "first_name": "John",
        "last_name": "Doe",
        "email": "john.doe@gmail.com",
        "phone": "9876543212",
        "reference_id": "john.doe.198",
        "avatar": {
          "url": "https://s3.amazonaws.com/fresh-chat-names/img/john_doe.png"
        }
      }
    },
    "actor": {
      "type": "user",
      "id": "98c76ba0-6b38-499b-9c37-e104774276b8",
      "first_name": "John",
      "last_name": "Doe",
      "email": "john.doe@gmail.com",
      "phone": "9876543212",
      "avatar": {
        "url": "https://s3.amazonaws.com/fresh-chat-names/img/john_doe.png"
      }
    }
  },
  "region": "US",
  "account_id": "227655214724132",
  "event": "onConversationCreate",
  "timestamp": 1564392319214,
  "version": "1.0.0"
}

EXPAND ↓

The following table lists the attributes of the conversation object.

ATTRIBUTE	TYPE	DESCRIPTION
user_id	string	Identifier of a user who initiates the conversation.
reopened_time	string	Time when the conversation is reopened, specified in the date-time format. When a convesation is initiated, this value is null.
assigned_time	string	Time when the conversation is assigned to an agent or a group, specified in the date-time format.
created_time	string	Time when the conversation is created, specified in the date-time format.
response_due_type	string	Priority of a conversation awaiting response. Possible values: First Response Due, No Response Due, Response Due
conversation_id	string	Identifier of the initiated conversation.
app_id	string	Identifier of the Freshchat account under which the conversation is created. To know your app_id, navigate to https://web.freshchat.com and log in with your account credentials. Navigate to Settings > Account Settings > Integration Settings. The App ID is displayed under AGENT WIDGET.
messages	array of message object	Messages that constitute a conversation.
status	string	Status of a conversation, whether new, resolved, reopened, assigned.
channel_id	string	Identifier of the channel.
assigned_group_id	string	Identifier of the group to which a conversation is assigned for resolution.

The following table lists the attributes of the message object.

ATTRIBUTE	TYPE	DESCRIPTION
message_parts	array of message_part object	Message stored as different parts - plain text, images, url buttons, a combination of text and image, or a combination of text, image, and url buttons.
app_id	string	Identifier of the Freshchat account.
actor_id	string	Identifier associated with the actor, either the user_id or agent_id.
id	string	Identifier of the message.
channel_id	string	Identifier of the channel in which a message is posted to a conversation.
conversation_id	string	Identifier of the initiated conversation.
message_type	string	Descriptive identifier stating whether the message in a conversation is a private message. Possible values (enum): normal
actor_type	string	Specifies if the message posted in a conversation is by a user or an agent. Possible values (enum): user, agent, system
created_time	string	Time when the conversation is created, specified in the date-time format.

The following table lists the attributes of the message_part object.

ATTRIBUTE	TYPE	DESCRIPTION
text	text_part object	Text part of a message in a conversation. Attribute of the text_part object: content (string): Actual content of the text message.
image	image_part object	Image part of a message in a conversation. Attribute of the image_part object: url (string): Location of the image file.
url_button	url_button_part object	Links in a message. Attributes of the url_button_part object: url (string): The hyperlink that is accessed by clicking the corresponding label. label (string): Text (in the message) that is used as the connector to the hyperlink. target (string): Specifies where the link is opened. If the value is _self, the link is opened within the conversation widget. If the value is _blank, the link is opened in a new tab. Possible values (enum): _self, _blank Default value: _blank
quick_reply_button	quick_reply_button_part object	Key value pairs containing the custom_reply_text and label. Attributes of the quick_reply_button_part object: Custom_reply_text (string): Custom text that is used as a reply text. label (string): Label on the button that is used to give a quick reply.
collection	array of message sub-part object	Combinations of text, image, url_button, and quick_reply_button.
callback	callback object	Key value pairs containing the payload and label.

Note: Only one attribute should be present in the message_part object.

The following table lists the attributes of the associations object.

ATTRIBUTE	TYPE	DESCRIPTION
group	group object	Group to which the conversation is assigned for resolution.
channel	channel object	Channel in which a message is posted to a conversation.
user	user object	User who initiates the conversation.
actor	actor object	Actor specifies if the message posted in a conversation is by a user or an agent.

The following table lists the attributes of the group object.

ATTRIBUTE	TYPE	DESCRIPTION
id	string	Identifier of the group to which the conversation is assigned for resolution.
name	string	Descriptive identifier for the group.
description	string	Meaningful definition that specifies the purpose of the group.
routing_type	string	Specifies if group members can accept auto-assigned conversations. If a business uses the Estate plan of Freshchat, the business can use the Intelliassign feature to auto-assign conversations to agents within a group. Possible values: Intelliassign, Disabled

The following table lists the attributes of the channel object.

ATTRIBUTE	TYPE	DESCRIPTION
id	string	Identifier of the channel in which a message is posted to a conversation.
icon	image object	Pictorial representation of the channel. Attribute of the image object: url (string): Link from which the image is fetched.
updated_time	string	Time when the channel is last updated, specified in the date-time format.
enabled	boolean	Specifies if a channel is available or disabled. Possible values: true, false
public	boolean	Specifies if a channel is open to receive messages from all users. Possible values: true, false
name	string	Meaningful description for the channel. For example, Inbox.
tags	array of string	Labels with which messages or conversations in a channel can be sorted. Example values: sales, support
welcome_message	welcome_message object	Message that sets context about the purpose of the channel. Attributes of the welcome_message object: message_parts (array of message_part object): Message stored as different parts - plain text, images, url buttons, a combination of text and image, or a combination of text, image, and url buttons. message_type (string): Descriptive identifier stating whether the message in a conversation is a private message. Possible values (enum): normal.
locale	string	Locale (language) value of the user.

The following table lists the attributes of the user object.

ATTRIBUTE	TYPE	DESCRIPTION
properties	array of property object	Key value pairs containing names and values of the custom user properties.
created_time	string	Time when the user information is created, specified in the date-time format.
id	string	Identifier of the user.
first_name	string	Business name of the user.
last_name	string	Last name of the user.
email	string	Email address of the user.
phone	string	Phone number of the user.
reference_id	string	Reference ID of the user.
avatar	image object	Image associated with the user. Attribute of the image object: url (string): Link from which the image is fetched.

The following table lists the attributes of the actor object.

ATTRIBUTE	TYPE	DESCRIPTION
type	string	Specifies if the message posted in a conversation is by a user or an agent. Possible values (enum): user, agent, system.
id	string	Identifier associated with the actor, either the user_id or agent_id.
first_name	string	Business name of the actor.
last_name	string	Last name of the actor.
email	string	Email address of the actor.
phone	string	Phone number of the actor.
avatar	image object	Image associated with the actor. Attribute of the image object: url (string): Link from which the image is fetched.

onConversationUpdate

When a conversation is resolved, an existing conversation is assigned to an agent or group, or a conversation is reopened, the onConversationUpdate event is invoked and the registered callback method is executed.

Use the following format to include the event in the server.js file.

Copied Copy

1
2
3
4
5
6
7
8 exports = {
  events: [
    { event: "onConversationUpdate", callback: "onConversationUpdateCallback" }
  ],
  onConversationUpdateCallback: function(payload) {
    console.log("Logging arguments from onConversationUpdate event: " + JSON.stringify(payload));
  }
}

Sample Reply 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
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126 {
  "data": {
    "conversation": {
      "user_id": "57fdd128-eb6d-44a8-9757-d7003966ad09",
      "reopened_time": "2019-07-29T14:51:56.933Z",
      "assigned_time": "2019-07-29T14:55:00.234Z",
      "created_time": "2019-07-25T10:01:23.564Z",
      "response_due_type": "NO_RESPONSE_DUE",
      "conversation_id": "4ec945ec-6717-409d-9549-198d5d121bd1",
      "app_id": "032c91b6-4b46-4f5b-adcb-102c72cd4efa",
      "messages": [
        {
          "message_parts": [
            {
              "text": {
                "content": "Conversation was reopened by John Doe"
              }
            }
          ],
          "app_id": "032c91b6-4b46-4f5b-adcb-102c72cd4efa",
          "actor_id": "2823233e-7122-4f87-9d56-38aaaaeb676a",
          "id": "f0cf8a2a-0772-4cce-be54-ebcb1bc68860",
          "channel_id": "d2f99658-ff98-44b8-b5c1-3a19dbfe2a2d",
          "conversation_id": "4ec945ec-6717-409d-9549-198d5d121bd1",
          "actor_type": "user",
          "created_time": "2019-07-29T15:27:17.972Z"
        }
      ],
      "status": "new",
      "channel_id": "d2f99658-ff98-44b8-b5c1-3a19dbfe2a2d",
      "assigned_agent_id": "2823233e-7122-4f87-9d56-38aaaaeb676a",
      "assigned_group_id": "40753ac3-1f66-40d9-b903-23db0a9a70b0"
    },
    "associations": {
      "group": {
        "id": "40753ac3-1f66-40d9-b903-23db0a9a70b0",
        "name": "Support",
        "description": "L1 support group",
        "routing_type": "DISABLED"
      },
      "channel": {
        "id": "d2f99658-ff98-44b8-b5c1-3a19dbfe2a2d",
        "icon": {},
        "updated_time": "2019-06-23T14:00:45.208Z",
        "enabled": true,
        "public": true,
        "name": "Inbox",
        "tags": [],
        "welcome_message": {
          "message_parts": [
            {
              "text": {
                "content": "Hello there! Need help? Reach out to us right here, and we'll get back to you as soon as we can!"
              }
            }
          ],
          "message_type": "normal"
        },
        "locale": ""
      },
      "user": {
        "created_time": "2019-07-29T00:51:50.776Z",
        "id": "57fdd128-eb6d-44a8-9757-d7003966ad09",
        "first_name": "John",
        "last_name": "Doe",
        "email": "jon.doe@freshworks.com",
        "reference_id": "john.doe.198",
        "phone": "9876543212",
        "properties": [
          {
            "name": "plan",
            "value": "Estate"
          }
        ],
        "avatar": {
          "url": "https://s3.amazonaws.com/fresh-chat-names/img/john_doe.png"
        }
      },
      "agent": {
        "groups": [],
        "status": 0,
        "id": "2823233e-7122-4f87-9d56-38aaaaeb676a",
        "first_name": "Jon",
        "last_name": "Snow",
        "email": "jon.snow@freshworks.com",
        "avatar": {
          "url": "https://s3.amazonaws.com/fresh-chat-names/img/jon_snow.png"
        },
        "social_profiles": []
      }
    },
    "actor": {
      "type": "system",
      "sub_type": "user",
      "id": "2823233e-7122-4f87-9d56-38aaaaeb676a",
      "first_name": "Jon",
      "last_name": "Doe",
      "email": "jon.doe@freshworks.com",
      "phone": "9876543212",
      "avatar": {
        "url": "https://s3.amazonaws.com/fresh-chat-names/img/jon_doe.png"
      }
    },
    "changes": {
      "model_changes": {
        "assigned_agent_id": [
          "2823233e-7122-4f87-9d56-38aaaaeb676a",
          null
        ],
        "assigned_group_id": [
          "40753ac3-1f66-40d9-b903-23db0a9a70b0",
          null
        ],
        "status": [
          "resolved",
          "new"
        ]
      }
    }
  },
  "region": "US",
  "account_id": "227655214724132",
  "event": "onConversationUpdate",
  "timestamp": 1564394238524,
  "version": "1.0.0"
}

EXPAND ↓

The following table lists the attributes of the conversation object.

ATTRIBUTE	TYPE	DESCRIPTION
user_id	string	Identifier of a user who initiates the conversation.
reopened_time	string	Time when the conversation is reopened, specified in the date-time format.
assigned_time	string	Time when the conversation is assigned to an agent or a group, specified in the date-time format.
created_time	string	Time when the conversation is created, specified in the date-time format.
response_due_type	string	Priority of a conversation awaiting response. Possible values: First Response Due, No Response Due, Response Due
conversation_id	string	Identifier of the initiated conversation.
app_id	string	Identifier of the Freshchat account under which the conversation is created. To know your app_id, navigate to https://web.freshchat.com and log in with your account credentials. Navigate to Settings > Account Settings > Integration Settings. The App ID is displayed under AGENT WIDGET.
messages	array of message object	Messages that constitute a conversation.
status	string	Status of a conversation, whether new, resolved, reopened, assigned.
channel_id	string	Identifier of the channel.
assigned_agent_id	string	Identifier of the agent to whom a conversation is assigned for resolution.
assigned_group_id	string	Identifier of the group to which a conversation is assigned for resolution.

The following table lists the attributes of the message object.

ATTRIBUTE	TYPE	DESCRIPTION
message_parts	array of message_part object	Message stored as different parts - plain text, images, url buttons, a combination of text and image, or a combination of text, image, and url buttons.
app_id	string	Identifier of the Freshchat account.
actor_id	string	Identifier associated with the actor, either the user_id or agent_id.
channel_id	string	Identifier of the channel in which a message is posted to a conversation.
conversation_id	string	Identifier of the initiated conversation.
actor_type	string	Specifies if the message posted in a conversation is by a user or an agent. Possible values (enum): user, agent, system
created_time	string	Time when the conversation is created, specified in the date-time format.

The following table lists the attributes of the message_part object.

ATTRIBUTE	TYPE	DESCRIPTION
text	text_part object	Text part of a message in a conversation. Attribute of the text_part object: content (string): Actual content of the text message.
image	image_part object	Image part of a message in a conversation. Attribute of the image_part object: url (string): Location of the image file.
url_button	url_button_part object	Links in a message. Attributes of the url_button_part object: url (string): The hyperlink that is accessed by clicking the corresponding label. label (string): Text (in the message) that is used as the connector to the hyperlink. target (string): Specifies where the link is opened. If the value is _self, the link is opened within the conversation widget. If the value is _blank, the link is opened in a new tab. Possible values (enum): _self, _blank Default value: _blank
quick_reply_button	quick_reply_button_part object	Key value pairs containing the custom_reply_text and label. Attributes of the quick_reply_button_part object: Custom_reply_text (string): Custom text that is used as a reply text. label (string): Label on the button that is used to give a quick reply.
collection	array of message sub-part object	Combinations of text, image, url_button, and quick_reply_button.
callback	callback object	Key value pairs containing the payload and label.

Note: Only one attribute should be present in the message_part object.

The following table lists the attributes of the associations object.

ATTRIBUTE	TYPE	DESCRIPTION
group	group object	Group to which the conversation is assigned for resolution.
channel	channel object	Channel in which a message is posted to a conversation.
user	user object	User who initiates the conversation.
agent	agent object	Agent to whom the conversation is assigned for resolution.
actor	actor object	Actor specifies if the message posted in a conversation is by a user or an agent.
changes	changes object	Updated field values.

The following table lists the attributes of the group object.

ATTRIBUTE	TYPE	DESCRIPTION
id	string	Identifier of the group to which the conversation is assigned for resolution.
name	string	Descriptive identifier for the group.
description	string	Meaningful definition that specifies the purpose of the group.
routing_type	string	Specifies if group members can accept auto-assigned conversations. If a business uses the Estate plan of Freshchat, the business can use the Intelliassign feature to auto-assign conversations to agents within a group. Possible values: Intelliassign, Disabled

The following table lists the attributes of the channel object.

ATTRIBUTE	TYPE	DESCRIPTION
id	string	Identifier of the channel in which a message is posted to a conversation.
icon	image object	Pictorial representation of the channel. Attribute of the image object: url (string): Link from which the image is fetched.
updated_time	string	Time when the channel is last updated, specified in the date-time format.
enabled	boolean	Specifies if a channel is available or disabled. Possible values: true, false
public	boolean	Specifies if a channel is open to receive messages from all users. Possible values: true, false
name	string	Meaningful description for the channel. For example, Inbox.
tags	array of string	Labels with which messages or conversations in a channel can be sorted. Example values: sales, support
welcome_message	welcome_message object	Message that sets context about the purpose of the channel. Attributes of the welcome_message object: message_parts (array of message_part object): Message stored as different parts - plain text, images, url buttons, a combination of text and image, or a combination of text, image, and url buttons. message_type (string): Descriptive identifier stating whether the message in a conversation is a private message. Possible values (enum): normal.
locale	string	Locale (language) value of the user.

The following table lists the attributes of the user object.

ATTRIBUTE	TYPE	DESCRIPTION
properties	array of property object	Key value pairs containing names and values of the custom user properties.
created_time	string	Time when the user information is created, specified in the date-time format.
id	string	Identifier of the user.
first_name	string	Business name of the user.
last_name	string	Last name of the user.
email	string	Email address of the user.
reference_id	string	Reference ID of the user.
phone	string	Phone number of the user.
avatar	image object	Image associated with the user. Attribute of the image object: url (string): Link from which the image is fetched.

The following table lists the attributes of the agent object.

ATTRIBUTE	TYPE	DESCRIPTION
groups	array of group object	Groups to which the agent belongs.
status	integer	Status of the conversation, whether new, resolved, reopened, assigned.
id	string	Identifier of the agent to whom the conversation is assigned for resolution.
first_name	string	Business name of the agent.
last_name	string	Last name of the agent.
email	string	Email address of the agent.
avatar	image object	Image associated with the agent. Attribute of the image object: url (string): Link from which the image is fetched.
social_profiles	array of social_profile object	Social platforms in which the agent is available. Attributes of the social_profile object: type (string): Name of the social media platform. Possible values (enum): facebook, twitter, skype, linkedin id (string): User ID of the agent on the platform.

The following table lists the attributes of the actor object.

ATTRIBUTE	TYPE	DESCRIPTION
type	string	Specifies if the message posted in a conversation is by a user or an agent. Possible values (enum): user, agent.
sub_type	string	Sub_type of the actor. Possible values (enum): user, agent.
id	string	Identifier associated with the actor, either the user_id or agent_id.
first_name	string	Business name of the actor.
last_name	string	Last name of the actor.
email	string	Email address of the actor.
phone	string	Phone number of the actor.
avatar	image object	Image associated with the actor. Attribute of the image object: url (string): Link from which the image is fetched.

The following table lists the attributes of the changes object.

ATTRIBUTE	TYPE	DESCRIPTION
model_changes	model_changes object	Updated field values. Attribute of the model_changes object: assigned_agent_id (array of string): Identifier of the agent to whom the conversation is assigned for resolution. assigned_group_id (array of string): Identifier of the group to which the conversation is assigned for resolution. status (array of string): Status of the conversation, whether new, resolved, reopened, assigned.

onMessageCreate

When an agent replies to a conversation initiated by a user, the onMessageCreate event is invoked and the registered callback method is executed.

Use the following format to include the event in the server.js file.

Copied Copy

1
2
3
4
5
6
7
8 exports = {
  events: [
    { event: "onMessageCreate", callback: "onMessageCreateCallback" }
  ],
  onMessageCreateCallback: function(payload) {
    console.log("Logging arguments from onMessageCreate event: " + JSON.stringify(payload));
  }
}

Sample Reply 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
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97 {
  "data": {
    "message": {
      "user_id": "98c76ba0-6b38-499b-9c37-e104774276b8",
      "reopened_time": null,
      "assigned_time": null,
      "created_time": "2019-07-29T14:51:56.933Z",
      "response_due_type": "FIRST_RESPONSE_DUE",
      "id": "8c65b83e-5be0-45f4-9645-9ddbbe015f4d",
      "app_id": "032c91b6-4b46-4f5b-adcb-102c72cd4efa",
      "messages": [
        {
          "message_parts": [
            {
              "text": {
                "content": "Hey again"
              }
            }
          ],
          "app_id": "032c91b6-4b46-4f5b-adcb-102c72cd4efa",
          "actor_id": "98c76ba0-6b38-499b-9c37-e104774276b8",
          "id": "17456eb1-4969-44a0-8c12-05b8b9604e7a",
          "channel_id": "167e73ff-9dd5-4e2d-8c50-74161b38a6fe",
          "conversation_id": "8c65b83e-5be0-45f4-9645-9ddbbe015f4d",
          "message_type": "normal",
          "actor_type": "user",
          "created_time": "2019-07-29T15:15:54.120Z"
        }
      ],
      "status": "new",
      "channel_id": "167e73ff-9dd5-4e2d-8c50-74161b38a6fe",
      "assigned_group_id": "40753ac3-1f66-40d9-b903-23db0a9a70b0"
    },
    "associations": {
      "group": {
        "id": "40753ac3-1f66-40d9-b903-23db0a9a70b0",
        "name": "Support",
        "description": "L1 support group",
        "routing_type": "DISABLED"
      },
      "channel": {
        "id": "167e73ff-9dd5-4e2d-8c50-74161b38a6fe",
        "icon": {},
        "updated_time": "2019-05-20T12:21:29.718Z",
        "enabled": true,
        "public": true,
        "name": "Inbox",
        "tags": [],
        "welcome_message": {
          "message_parts": [
            {
              "text": {
                "content": "Hello there! Need help? Reach out to us right here, and we'll get back to you as soon as we can!"
              }
            }
          ],
          "message_type": "normal"
        },
        "locale": ""
      },
      "user": {
        "properties": [
          {
            "name": "siteId",
            "value": "Orders"
          }
        ],
        "created_time": "2019-07-29T20:21:42.063Z",
        "id": "98c76ba0-6b38-499b-9c37-e104774276b8",
        "first_name": "John",
        "last_name": "Doe",
        "email": "jon.doe@freshworks.com",
        "reference_id": "john.doe.198",
        "phone": "9876543212",
        "avatar": {
          "url": "https://s3.amazonaws.com/fresh-chat-names/img/john_doe.png"
        }
      }
    },
    "actor": {
      "type": "user",
      "id": "98c76ba0-6b38-499b-9c37-e104774276b8",
      "first_name": "John",
      "last_name": "Doe",
      "email": "jon.doe@freshworks.com",
      "phone": "9876543212",
      "avatar": {
        "url": "https://s3.amazonaws.com/fresh-chat-names/img/john_doe.png"
      }
    }
  },
  "region": "US",
  "account_id": "227655214724132",
  "event": "onMessageCreate",
  "timestamp": 1564393556026,
  "version": "1.0.0"
}

EXPAND ↓

The following table lists the attributes of the conversation message object.

ATTRIBUTE	TYPE	DESCRIPTION
user_id	string	Identifier of a user who initiates the conversation.
reopened_time	string	Time when the conversation is reopened, specified in the date-time format.
assigned_time	string	Time when the conversation is assigned to an agent or a group, specified in the date-time format.
created_time	string	Time when the conversation is created, specified in the date-time format.
response_due_type	string	Priority of a conversation awaiting response. Possible values: First Response Due, No Response Due, Response Due
conversation_id	string	Identifier of the initiated conversation.
app_id	string	Identifier of the Freshchat account under which the conversation is created. To know your app_id, navigate to https://web.freshchat.com and log in with your account credentials. Navigate to Settings > Account Settings > Integration Settings. The App ID is displayed under AGENT WIDGET.
messages	array of message object	Messages that constitute a conversation.
status	string	Status of a conversation, whether new, resolved, reopened, assigned.
channel_id	string	Identifier of the channel.
assigned_group_id	string	Identifier of the group to which the conversation is assigned for resolution.

The following table lists the attributes of the message object.

ATTRIBUTE	TYPE	DESCRIPTION
message_parts	array of message_part object	Message stored as different parts - plain text, images, url buttons, a combination of text and image, or a combination of text, image, and url buttons.
app_id	string	Identifier of the Freshchat account.
actor_id	string	Identifier associated with the actor, either the user_id or agent_id.
channel_id	string	Identifier of the channel in which a message is posted to a conversation.
conversation_id	string	Identifier of the initiated conversation.
message_type	string	Descriptive identifier stating whether the message in a conversation is a private message. Possible values (enum): normal
actor_type	string	Specifies if the message posted in a conversation is by a user or an agent. Possible values (enum): user, agent, system
created_time	string	Time when the conversation is created, specified in the date-time format.

The following table lists the attributes of the message_part object.

ATTRIBUTE	TYPE	DESCRIPTION
text	text_part object	Text part of a message in a conversation. Attribute of the text_part object: content (string): Actual content of the text message.
image	image_part object	Image part of a message in a conversation. Attribute of the image_part object: url (string): Location of the image file.
url_button	url_button_part object	Links in a message. Attributes of the url_button_part object: url (string): The hyperlink that is accessed by clicking the corresponding label. label (string): Text (in the message) that is used as the connector to the hyperlink. target (string): Specifies where the link is opened. If the value is _self, the link is opened within the conversation widget. If the value is _blank, the link is opened in a new tab. Possible values (enum): _self, _blank Default value: _blank
quick_reply_button	quick_reply_button_part object	Key value pairs containing the custom_reply_text and label. Attributes of the quick_reply_button_part object: Custom_reply_text (string): Custom text that is used as a reply text. label (string): Label on the button that is used to give a quick reply.
collection	array of message sub-part object	Combinations of text, image, url_button, and quick_reply_button.
callback	callback object	Key value pairs containing the payload and label.

Note: Only one attribute should be present in the message_part object.

The following table lists the attributes of the associations object.

ATTRIBUTE	TYPE	DESCRIPTION
group	group object	Group to which the conversation is assigned for resolution.
channel	channel object	Channel in which a message is posted to a conversation.
user	user object	User who initiates the conversation.
actor	actor object	Actor specifies if the message posted in a conversation is by a user or an agent.

The following table lists the attributes of the group object.

ATTRIBUTE	TYPE	DESCRIPTION
id	string	Identifier of the group to which the conversation is assigned for resolution.
name	string	Descriptive identifier for the group.
description	string	Meaningful definition that specifies the purpose of the group.
routing_type	string	Specifies if group members can accept auto-assigned conversations. If a business uses the Estate plan of Freshchat, the business can use the Intelliassign feature to auto-assign conversations to agents within a group. Possible values: Intelliassign, Disabled

The following table lists the attributes of the channel object.

ATTRIBUTE	TYPE	DESCRIPTION
id	string	Identifier of the channel in which a message is posted to a conversation.
icon	image object	Pictorial representation of the channel. Attribute of the image object: url (string): Link from which the image is fetched.
updated_time	string	Time when the channel is last updated, specified in the date-time format.
enabled	boolean	Specifies if a channel is available or disabled. Possible values: true, false
public	boolean	Specifies if a channel is open to receive messages from all users. Possible values: true, false
name	string	Meaningful description for the channel. For example, Inbox.
tags	array of string	Labels with which messages or conversations in a channel can be sorted. Example values: sales, support
welcome_message	welcome_message object	Message that sets context about the purpose of the channel. Attributes of the welcome_message object: message_parts (array of message_part object): Message stored as different parts - plain text, images, url buttons, a combination of text and image, or a combination of text, image, and url buttons. message_type (string): Descriptive identifier stating whether the message in a conversation is a private message. Possible values (enum): normal.
locale	string	Locale (language) value of the user.

The following table lists the attributes of the user object.

ATTRIBUTE	TYPE	DESCRIPTION
properties	array of property object	Key value pairs containing names and values of the custom user properties.
created_time	string	Time when the user information is created, specified in the date-time format.
id	string	Identifier of the user.
first_name	string	Business name of the user.
last_name	string	Last name of the user.
email	string	Email address of the user.
reference_id	string	Reference ID of the user.
phone	string	Phone number of the user.
avatar	image object	Image associated with the user. Attribute of the image object: url (string): Link from which the image is fetched.

The following table lists the attributes of the actor object.

ATTRIBUTE	TYPE	DESCRIPTION
type	string	Specifies if the message posted in a conversation is by a user or an agent. Possible values (enum): user, agent.
id	string	Identifier associated with the actor, either the user_id or agent_id.
first_name	string	Business name of the actor.
last_name	string	Last name of the actor.
email	string	Email address of the actor.
phone	string	Phone number of the actor.
avatar	image object	Image associated with the actor. Attribute of the image object: url (string): Link from which the image is fetched.

onUserCreate

When a user initiates a conversation, the onUserCreate event is invoked and the registered callback method is executed.

Use the following format to include the event in the server.js file.

Copied Copy

1
2
3
4
5
6
7
8 exports = {
  events: [
    { event: "onUserCreate", callback: "onUserCreateCallback" }
  ],
  onUserCreateCallback: function(payload) {
    console.log("Logging arguments from onUserCreate event: " + JSON.stringify(payload));
  }
}

Sample Reply Payload

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23 {
    "data": {
      "user": {
        "id": "b3c2c92e-d650-4c40-bb7d-aeb3423cd4d2",
        "reference_id": "john.doe.198",
        "created_time": "2019-07-29T14:51:56.933Z",
        "first_name": "John",
        "last_name": "Doe",
        "email": "john.doe@gmail.com",
        "phone": "9876543212",
        "avatar": {
          "url": "https://s3.amazonaws.com/fresh-chat-names/img/john_doe.png"
        }
      }
    },
    "associations": {},
    "actor": {},
    "region": "US",
    "account_id": "227655214724132",
    "event": "onUserCreate",
    "timestamp": 1571036504512,
    "version": "1.0.0"
  }

EXPAND ↓

The following table lists the attributes of the user object.

ATTRIBUTE	TYPE	DESCRIPTION
id	string	Identifier of the user.
reference_id	string	Reference ID of the user.
created_time	string	Time when the user information is created, specified in the date-time format.
first_name	string	Business name of the user.
last_name	string	Last name of the user.
email	string	Email address of the user.
phone	string	Phone number of the user.
avatar	image object	Image associated with the user. Attribute of the image object: url (string): Link from which the image is fetched.

onUserUpdate

When a user's information is updated, the onUserUpdate event is invoked and the registered callback method is executed.

Use the following format to include the event in the server.js file.

Copied Copy

1
2
3
4
5
6
7
8 exports = {
  events: [
    { event: "onUserUpdate", callback: "onUserUpdateCallback" }
  ],
  onUserUpdateCallback: function(payload) {
    console.log("Logging arguments from onUserUpdate event: " + JSON.stringify(payload));
  }
}

Sample Reply 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 {
  "data": {
    "user": {
      "created_time": "2019-07-29T14:51:56.933Z",
      "id": "b3c2c92e-d650-4c40-bb7d-aeb3423cd4d2",
      "reference_id": "john.doe.198",
      "first_name": "John",
      "last_name": "Doe",
      "email": "john.doe@gmail.com",
      "phone": "9876543212",
      "avatar": {
        "url": "https://s3.amazonaws.com/fresh-chat-names/img/john_doe.png"
      },
      "phone": "9876543212",
      "properties": [
        {
          "name": "plan",
          "value": "Estate"
        }
      ]
    },
    "actor": {
      "type": "agent",
      "id": "98c76ba0-6b38-499b-9c37-e104774276b8",
      "first_name": "Jon",
      "last_name": "Snow",
      "email": "jon.snow@freshworks.com",
      "avatar": {
        "url": "https://s3.amazonaws.com/fresh-chat-names/img/jon_snow.png"
      }
    },
    "associations": {},
    "changes": {
      "model_changes": {
        "first_name": [
          "Dancing  Wayfarer",
          "John"
        ]
      }
    }
  },
  "region": "US",
  "account_id": "235086843748457",
  "event": "onUserUpdate",
  "timestamp": 1571040876177,
  "version": "1.0.0"
}

EXPAND ↓

The following table lists the attributes of the user object.

ATTRIBUTE	TYPE	DESCRIPTION
created_time	string	Time when the user information is created, specified in the date-time format.
id	string	Identifier of the user.
reference_id	string	Reference ID of the user.
first_name	string	Business name of the user.
last_name	string	Last name of the user.
email	string	Email address of the user.
avatar	image object	Image associated with the user. Attribute of the image object: url (string): Link from which the image is fetched.
phone	string	Phone number of the user.
properties	array of property object	Key value pairs containing names and values of the custom user properties.

The following table lists the attributes of the actor object.

ATTRIBUTE	TYPE	DESCRIPTION
type	string	Descriptive identifier of the person who made the changes. Possible values (enum): agent
id	string	Identifier of the agent.
first_name	string	Business name of the agent.
last_name	string	Last name of the agent.
email	string	Email address of the agent.
avatar	image object	Image associated with the actor. Attribute of the image object: url (string): Link from which the image is fetched.

The following table lists the attributes of the changes object.

ATTRIBUTE	TYPE	DESCRIPTION
model_changes	object	Names of the agents who updated the user details.

Testing

Note: Use the latest version of Chrome browser.

You can easily test your app in your machine by simulating events. Also, you can test different scenarios by directly modifying the payload.

Note: As the testing is only a simulation of events, an actual event will not be recorded in the back end. If you need an actual conversation to be created, you can publish your app as a custom app and test the operation manually.

To simulate events for testing, follow the procedure outlined below.

From the command prompt, navigate to the project directory and execute the following command. $ fdk run
In your browser, enter the following URL: http://localhost:10001/web/test.
Select the event that you want to simulate.
Once you select an event, the corresponding event payload is displayed. Edit the values and then click Simulate. When you edit the payload, ensure that you adhere to the JSON format.
If the event is successfully simulated, Success is displayed.
If there is a problem, Failed is displayed. Check if the payload is valid and then resume testing.

Overview

App Setup Events

Log in with your Freshchat account

Enter your helpdesk URL to proceed to login

Proceed

By clicking "Proceed", you agree to our Terms of Use.

Don't have a Freshdesk account?

Signup for free