Product Events

Events that occur in the Freshchat product, such as initiating a conversation or resolving a conversation, are termed as product events. You can enable product events to trigger apps. To do this, configure event listeners in the manifest.json file. When a product event occurs, the corresponding event listener invokes a callback method defined in server.js. The app logic in the callback method runs with the help of the event-specific payload passed to the callback method.

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

Configure Events

To register a product event and the corresponding callback:

  1. From your app’s root directory, navigate to the manifest.json file.
  2. Include the events attribute, specifying the product event and the corresponding callback methods as follows:
    Copied Copy 
    1
    2
    3
    4
    5
    		"events": {
  "<eventName>": {
      "handler": "<eventCallbackMethod>"
  }
}

    Note: Include only one callback method for an event. Multiple events can access the same callback method.

  3. Navigate to the server.js file.
  4. In the exports block, enter the callback function definition as follows:
    Copied Copy 
    1
    2
    3
    4
    5
    6
    7
    		exports = {
      // args is a JSON block containing the payload information
      // args["iparam"] will contain the installation parameter values
      //eventCallbackMethod is the call-back function name specified in manifest.json
      eventCallbackMethod: function(args) {
        console.log("Logging arguments from the event: " + JSON.stringify(payload));
      }};

Payload Attributes

When a product event occurs, an event-specific payload is passed to the callback method.

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

The payload is a JSON object with the following attributes.

Attribute Type Description
account_id string Identifier of the Freshchat account, auto-generated when the account is configured for a business.
event string Name of the product event.
region string Region where the account is deployed.
Possible values: US, EU, EUC, AUS, and IND
timestamp number Timestamp of when the product event occurs, specified in the epoch format.
iparams object Installation parameters specified as a JSON object of <parameter name>: <parameter value> pairs.
data object Event-specific data, specified as a JSON object of key:value pairs.
onConversationCreate

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

Register the onConversationCreate event by using the following sample manifest.json content.

Copied Copy 
1
2
3
4
5
"events": {
  "onConversationCreate": {
    "handler": "onConversationCreateCallback"
  }
}

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

Copied Copy 
1
2
3
4
5
exports = {
  onConversationCreateCallback: function(payload) {
    console.log("Logging arguments from onConversationCreate event: " + JSON.stringify(payload));
  }
}
 Sample 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"
        }
      },
      "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",
  "domain": "web.freshchat.com",
  "event": "onConversationCreate",
  "timestamp": 1564392319214,
  "version": "1.0.0"
}
EXPAND ↓
Attributes of the data object
ATTRIBUTE TYPE DESCRIPTION
conversation conversation object Details of the conversation object created when the onConversationCreate event is triggered.
associations object Associated objects related to the conversation object.
actor actor object Details of the entity that triggered the onConversationCreate event. For onConversationCreate, it is a user.

Attributes of the conversation object
ATTRIBUTE TYPE DESCRIPTION
user_id string Identifier of the user who initiates the conversation, auto-generated when onConversationCreate is triggered.
reopened_time string Timestamp of when a conversation is reopened, specified in the UTC format. This value is null for onConversationCreate.
assigned_time string Timestamp of when a conversation is assigned to an agent or a group, specified in the UTC format. This value is null for onConversationCreate.
created_time string Timestamp of when the conversation object is created, specified in the UTC format.
response_due_type string Priority assigned to a conversation. This value is First Response Due for onConversationCreate.
conversation_id string Identifier of the conversation object, auto-generated when the conversation is initiated.
app_id string Alias of the Freshchat account ID.
messages array of message objects Message that constitutes the conversation.
status string Status of a conversation. This value is new for onConversationCreate.
channel_id string Identifier of the topic under which the user posted the message that triggered onConversationCreate.
assigned_group_id string Identifier of the group to which a conversation is assigned for resolution. This value is null for onConversationCreate.

Attributes of the message object
ATTRIBUTE TYPE DESCRIPTION
message_parts array of message_part objects Different parts of the message - plain text, images, url buttons, a combination of text and image, or a combination of text, image, and url buttons.
app_id string Alias of the Freshchat account ID.
actor_id string Identifier of the entity who posted the message. Here, it is the user_id.
id string Identifier of the message object. This is an auto-generated value.
channel_id string Identifier of the topic under which the message is posted. This is an auto-generated value.
conversation_id string Identifier of the conversation object. This is an auto-generated value.
message_type string Descriptive identifier specifying whether the message is a private or normal message. This value is normal for onConversationCreate.
actor_type string Descriptive identifier of the entity that posted the message in the conversation. This value is user for onConversationCreate.
created_time string Timestamp of when the conversation is created, specified in the UTC format.

Attributes of the message_part object

Only one attribute should be present in the message_part object.

ATTRIBUTE TYPE DESCRIPTION
text text_part object Text part of a message in the conversation.
Attribute of the text_part object:
content (string): Actual content of the text message.
image image_part object Image part of the message in the conversation.
Attribute of the image_part object:
url (string): Location of the image file.
url_button url_button_part object Links in the 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): Location where the link is opened.
Possible values (enum): _self, _blank
Default value: _blank
collection array of message sub-part object Combination of text, image, and url_button.

Attributes of the channel object
ATTRIBUTE TYPE DESCRIPTION
id string Identifier of the topic under which the message that triggered onConversationCreate is posted.
icon image object Pictorial representation of the topic.
Attribute of the image object:
url (string): Link from which the image is fetched.
updated_time string Timestamp of when the topic is last updated, specified in the UTC format.
enabled boolean Specifies whether all users can post messages under the topic.
Possible values: true, false
public boolean Specifies whether all users can post messages under the topic.
Possible values: true, false
name string Meaningful description of the topic. For example: Support, Billing
tags array of strings Labels with which topics are tagged for different users.
welcome_message welcome_message object Message that sets context about the purpose of the topic.

Attributes of the user object
ATTRIBUTE TYPE DESCRIPTION
properties array 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.
Attributes of the property object:
name (string): Name of the custom property.
value (string): Value of the custom property.
created_time string Timestamp of when the user information is created, specified in the UTC format.
id string Identifier of the user, auto-generated when the conversation is initiated.
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 Identifier of external references, such as email or phone number, input by the user.
avatar image object Image associated with the user.
Attribute of the image object:
url (string): Link from which the image is fetched.

Attributes of the actor object
ATTRIBUTE TYPE DESCRIPTION
type string Descriptive identifier of the entity who posted the message in the conversation. This value is user for onConversationCreate.
id string Identifier associated with the actor. Here, it is the user_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 or an existing conversation is assigned to an agent or a group, the onConversationUpdate event is invoked and the registered callback method is executed.

Register the onConversationUpdate event by using the following sample manifest.json content.

Copied Copy 
1
2
3
4
5
"events": {
  "onConversationUpdate": {
    "handler": "onConversationUpdateCallback"
  }
}

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

Copied Copy 
1
2
3
4
5
exports = {
  onConversationUpdateCallback: function(payload) {
    console.log("Logging arguments from onConversationUpdate event: " + JSON.stringify(payload));
  }
}
 Sample 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
{
  "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": "agent",
          "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"
        }
      },
      "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": "agent",
      "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",
  "domain": "web.freshchat.com",
  "event": "onConversationUpdate",
  "timestamp": 1564394238524,
  "version": "1.0.0"
}
EXPAND ↓
Attributes of the data object
ATTRIBUTE TYPE DESCRIPTION
conversation conversation object Details of the conversation whose status change triggered the onConversationUpdate event.
associations associations object Associated objects related to the conversation object.
actor actor object Details of the entity that triggered the onConversationUpdate event.
Possible values: agent, system
changes model_changes object Updated field values, specified as a JSON object in the following format. 
1
2
3
4
5
{
"assigned_agent_id": ["New value", "Old value"],
"assigned_group_id": ["New value", "Old value"],
"status": ["New value", "Old value"]
}

Attributes of the conversation object
ATTRIBUTE TYPE DESCRIPTION
user_id string Identifier of the user who initiated the conversation.
reopened_time string Timestamp of when the conversation is reopened, specified in the UTC format.
assigned_time string Timestamp of when the conversation is assigned to an agent or a group, specified in the UTC format.
created_time string Timestamp of when the conversation was created, specified in the UTC format.
response_due_type string Priority assigned to the conversation.
Possible values: First Response Due, No Response Due, Response Due
conversation_id string Identifier of the conversation object. This is an auto-generated value.
app_id string Alias of the Freshchat account ID.
messages array of message objects Messages that constitute the conversation.
status string Status of the conversation.
Possible values: new, resolved, assigned
channel_id string Identifier of the topic under which the entity posted the message.
assigned_agent_id string Identifier of the agent to whom the conversation is assigned for resolution.
assigned_group_id string Identifier of the group to which the conversation is assigned for resolution.

Attributes of the message object
ATTRIBUTE TYPE DESCRIPTION
message_parts array of message_part objects Different parts of the message - plain text, images, url buttons, a combination of text and image, or a combination of text, image, and url buttons.
app_id string Alias of the Freshchat account ID.
actor_id string Identifier of the entity who posted the message. This value is null, if the entity is system.
id string Identifier of the message object. This is an auto-generated value.
channel_id string Identifier of the topic under which the message is posted. This is an auto-generated value.
conversation_id string Identifier of the conversation object. This is an auto-generated value.
actor_type string Descriptive identifier of the entity that posted the message in the conversation.
Possible values: agent, system
created_time string Timestamp of when the conversation is created, specified in the UTC format.

Attributes of the message_part object
ATTRIBUTE TYPE DESCRIPTION
text text_part object Text part of the message in the conversation.
Attribute of the text_part object:
content (string): Actual content of the text message.

Attributes of the associations object
ATTRIBUTE TYPE DESCRIPTION
group group object Details of the group to which the conversation is assigned for resolution.
channel channel object Details of the topic under which the message is posted.
user user object Details of the user who initiated the conversation.
agent agent object Details of the agent to whom the conversation is assigned for resolution.

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 whether group members can accept auto-assigned conversations.
Possible values: Intelliassign, Disabled

Attributes of the channel object
ATTRIBUTE TYPE DESCRIPTION
id string Identifier of the topic under which the message that triggers onConversationUpdate is posted.
icon image object Pictorial representation of the topic.
Attribute of the image object:
url (string): Link from which the image is fetched.
updated_time string Timestamp of when the topic is last updated, specified in the UTC format.
enabled boolean Specifies whether all users can post messages under the topic. This value is true for onConversationUpdate.
public boolean Specifies whether all users can post messages under the topic.
Possible values: true, false
name string Meaningful description of the topic. For example: Support, Billing.
tags array of strings Labels with which topics are tagged for different users.
welcome_message welcome_message object Message that sets context about the purpose of the topic.

Attributes of the user object
ATTRIBUTE TYPE DESCRIPTION
properties array 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.
Attributes of the property object:
name (string): Name of the custom property.
value (string): Value of the custom property.
created_time string Timestamp of when the user information is created, specified in the UTC format.
id string Identifier of the user who initiated the conversation.
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 Identifier of external references, such as email or phone number, input by 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.

Attributes of the agent object
ATTRIBUTE TYPE DESCRIPTION
groups array of group objects Details of the groups to which the agent belongs.
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 objects 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.

Attributes of the actor object
ATTRIBUTE TYPE DESCRIPTION
type string Descriptive identifier of the entity that posted the message.
Possible values (enum): system, agent
id string Identifier associated with the actor. This value is null, if the entity is system.
first_name string Business name of the actor. This value is null, if the entity is system.
last_name string Last name of the actor. This value is null, if the entity is system.
email string Email address of the actor. This value is null, if the entity is system.
phone string Phone number of the actor. This value is null, if the entity is system.
avatar image object Image associated with the actor.
Attribute of the image object:
url (string): Link from which the image is fetched.
This value is null, if the entity is system.
onMessageCreate

When a message is posted, either by the agent or user, the onMessageCreate event is invoked and the registered callback method is executed.

Register the onMessageCreate event by using the following sample manifest.json content.

Copied Copy 
1
2
3
4
5
"events": {
  "onMessageCreate": {
    "handler": "onMessageCreateCallback"
  }
}

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

Copied Copy 
1
2
3
4
5
exports = {
  onMessageCreateCallback: function(payload) {
    console.log("Logging arguments from onMessageCreate event: " + JSON.stringify(payload));
  }
}
 Sample 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",
      "conversation_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"
        }
      },
      "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",
  "domain": "web.freshchat.com",
  "event": "onMessageCreate",
  "timestamp": 1564393556026,
  "version": "1.0.0"
}
EXPAND ↓
Attributes of the data object
ATTRIBUTE TYPE DESCRIPTION
message message object Details of the message that triggered the onMessageCreate event.
associations associations object Associated objects related to the message object.
actor actor object Details of the entity that posted the message.

Attributes of the message object
ATTRIBUTE TYPE DESCRIPTION
user_id string Identifier of the user who posted the message or to whom the message is posted. This is an auto-generated value.
reopened_time string Timestamp of when the conversation is reopened, specified in the UTC format.
assigned_time string Timestamp of when the conversation is assigned to an agent or a group, specified in the UTC format.
created_time string Timestamp of when the conversation is created, specified in the UTC format.
response_due_type string Priority assigned to the conversation.
Possible values: First Response Due, No Response Due, Response Due
conversation_id string Identifier of the conversation object. This is an auto-generated value.
app_id string Alias of the Freshchat account ID.
messages array of messages objects Messages that constitute the conversation.
status string Status of the conversation.
Possible values: new, resolved, assigned.
channel_id string Identifier of the topic under which the message that triggered onMessageCreate is posted.
assigned_group_id string Identifier of the group to which the conversation is assigned for resolution.

Attributes of the messages object
ATTRIBUTE TYPE DESCRIPTION
message_parts array of message_part objects 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 Alias of the Freshchat account ID.
actor_id string Identifier of the entity who posted the message that triggered the onMessageCreate event.
channel_id string Identifier of the topic under which the message is posted. This is an auto-generated value.
conversation_id string Identifier of the conversation object. This is an auto-generated value.
message_type string Descriptive identifier specifying the type of message.
Possible values: normal, private
actor_type string Descriptive identifier of the entity who posted the message.
Possible values: user, agent
created_time string Timestamp of when the message is created, specified in the UTC format.

Attributes of the message_part object

Only one attribute should be present in the message_part object.

ATTRIBUTE TYPE DESCRIPTION
text text_part object Text part of the message in the conversation.
Attribute of the text_part object:
content (string): Actual content of the text message.
image image_part object Image part of the message in the conversation.
Attribute of the image_part object:
url (string): Location of the image file.
url_button url_button_part object Links in the 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 objects Combinations of text, image, url_button, and quick_reply_button.

Attributes of the associations object
ATTRIBUTE TYPE DESCRIPTION
group group object Details of the group to which the conversation is assigned for resolution.
channel channel object Details of the topic under which the message is posted.
user user object Details of the user who posted the message or to whom the message is posted.

Attributes of the group object
ATTRIBUTE TYPE DESCRIPTION
id string Identifier of the group from which an agent has replied to the user message.
name string Descriptive identifier of the group.
description string Meaningful definition that specifies the purpose of the group.
routing_type string Specifies whether group members can accept auto-assigned conversations.
Possible values: Intelliassign, Disabled

Attributes of the channel object
ATTRIBUTE TYPE DESCRIPTION
id string Identifier of the topic under which the message is posted.
icon image object Pictorial representation of the topic.
Attribute of the image object:
url (string): Link from which the image is fetched.
updated_time string Timestamp of when the topic is last updated, specified in the UTC format.
enabled boolean Specifies whether all users can post messages under the topic.
Possible values: true, false
public boolean Specifies whether all users can post messages under the topic.
Possible values: true, false
name string Meaningful description of the topic. For example: Support, Billing
tags array of strings Labels with which topics are tagged for different users.
welcome_message welcome_message object Message that sets context about the purpose of the channel.

Attributes of the user object
ATTRIBUTE TYPE DESCRIPTION
properties array 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.
Attributes of the property object:
name (string): Name of the custom property.
value (string): Value of the custom property.
created_time string Timestamp of when the user information is created, specified in the UTC format.
id string Identifier of the user. This is an auto-generated value.
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 Identifier of external references, such as email or phone number, input by 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.

Attributes of the actor object
ATTRIBUTE TYPE DESCRIPTION
type string Descriptive identifier of the entity who posted the message.
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.

Register the onUserCreate event by using the following sample manifest.json content.

Copied Copy 
1
2
3
4
5
"events": {
  "onUserCreate": {
    "handler": "onUserCreateCallback"
  }
}

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

Copied Copy 
1
2
3
4
5
exports = {
  onUserCreateCallback: function(payload) {
    console.log("Logging arguments from onUserCreate event: " + JSON.stringify(payload));
  }
}
 Sample 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
{
    "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"
        },
        "properties": [
          {
            "name": "plan",
            "value": "Estate"
          }
        ]
      },
      "actor": {},
      "associations": {}
    },
    "region": "US",
    "account_id": "227655214724132",
    "domain": "web.freshchat.com",
    "event": "onUserCreate",
    "timestamp": 1571036504512,
    "version": "1.0.0"
  }
EXPAND ↓
Attributes of the user object
ATTRIBUTE TYPE DESCRIPTION
id string Identifier of the user. This value is auto-generated when the conversation is initiated.
reference_id string Identifier of external references, such as email or phone number, input by the user.
created_time string Timestamp of when the user information is created, specified in the UTC 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.
properties array 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.
Attributes of the property object:
name (string): Name of the custom property.
value (string): Value of the custom property.
actor actor object Details of the user who posted the message.
associations associations object Associated objects related to the message object. This value is null for the onUserCreate event.
onUserUpdate

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

Register the onUserUpdate event by using the following sample manifest.json content.

Copied Copy 
1
2
3
4
5
"events": {
  "onUserUpdate": {
    "handler": "onUserUpdateCallback"
  }
}

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

Copied Copy 
1
2
3
4
5
exports = {
  onUserUpdateCallback: function(payload) {
    console.log("Logging arguments from onUserUpdate event: " + JSON.stringify(payload));
  }
}
 Sample 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"
          },
          "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",
      "domain": "web.freshchat.com",
      "event": "onUserUpdate",
      "timestamp": 1571040876177,
      "version": "1.0.0"
    }
EXPAND ↓
Attributes of the data object
ATTRIBUTE TYPE DESCRIPTION
user user object Details of the user whose information change triggered the onUserUpdate event.
actor actor object Details of the person who modified the user information.
changes model_changes object Changes that triggered onUserUpdate, specified as a JSON object of the following format. 
1
2
3
{
"user object field that changed": ["New value", "Old value"]
}
.

Attributes of the user object
ATTRIBUTE TYPE DESCRIPTION
created_time string Timestamp of when the user information is created, specified in the UTC format.
id string Identifier of the user. This is an auto-generated value when the user object is created.
reference_id string Identifier of external references, such as email or phone number, input by 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 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.
Attributes of the property object:
name (string): Name of the custom property.
value (string): Value of the custom property.

Attributes of the actor object
ATTRIBUTE TYPE DESCRIPTION
type string Descriptive identifier of the entity who updated the user details.
Possible values: agent, user
id string Identifier associated with the actor, either agent_id or user_id .
first_name string Business name of the actor.
last_name string Last name of the actor.
email string Email address 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.
Testing
Notes:
  • To test a serverless app, use the latest version of Chrome.
  • As testing is only a simulation of events, actual data or record associated with the event is not created in the back-end. To create actual data and then test your event, publish your app as a custom app and test the events manually.
  • Ensure that the JSON files that contain the sample payloads to test events, are available at <app's root directory>/server/test_data.

To simulate an event and test your app:

  1. From the command line, navigate to the directory that contains the app related files and run the following command.$ fdk run

  2. In the address bar of the browser, enter https://localhost:10001/web/test. A dialog box is displayed.

  3. Click Select an event. The list of all events configured in the server.js file is displayed.

  4. Select an event. The corresponding payload is displayed. To test a different scenario other than the default, edit the payload.

  5. Click Simulate. If the event is successfully simulated, the Simulate button changes to a Success button. If the event simulation fails because of invalid payload data, the Simulate button changes to a Failed button. Modify the payload appropriately and click Simulate.