Freshworks Developer Platform Docs

Data method is an interface that the developer platform provides to enable your app to retrieve product data (in the form of JSON payloads).

When an app is initialized successfully, the parent app (Freshworks product) passes a client reference to your app. Your app can use this reference and the developer platform’s data method to retrieve the different objects on the Freshworks product UI, as payloads.

To enable your app to retrieve product data, in the app.js file,

Subscribe to the app.initialized event, through an event listener. When the app is initialized, the parent application passes a client reference to the app.
After app initialization, use the data method - client.data.get(<objectName>) - to retrieve the specified object (<objectName>) from the product UI.

As part of the app logic, your app can process the retrieved payload to derive meaningful results.

This section,

Lists all the objects that can be retrieved by using the data method.
Describes all the attributes of the retrieved object.

Data objects accessible from all pages

These objects are available in all pages of the product UI. Irrespective of the page on which the app is deployed, when you use the data method and retrieve these objects, the corresponding payload is retrieved.

An app can retrieve the following objects irrespective of where the app is deployed:

currentHost

A global app, with module-specific app logic, can be deployed on various Freshworks products. currentHost refers to the Freshworks product on which the app is currently running. Based on the currentHost, from the back-end, we retrieve the modules that the app user working on the currentHost has subscribed to. Based on the subscribed modules, we can retrieve the product-specific urls that the app built for the modules can use, to access the product resources. The organization domain associated with the account can also be retrieved, which can be pre-populated during the app installation using utils.set(); method in the onFormLoad() callback function definition. For information on the onFormLoad() function, see Make your installation page dynamic.

For more information on currentHost, see Global app concepts.

Use the sample code shown on the right pane > Sample code tab, to retrieve the currentHost object that contains information on,

All modules that the app user using the currentHost has access to and applicable to the app.
All product names and the corresponding account urls through which the app built for the subscribed modules can access product resources.

Attributes of the currentHost object

subscribed_modulesarray of strings
All modules that the app user has subscribed to and present in the app manifest.
endpoint_urlsobject
Product name and account url (domain name) to access product resources, specified as a key (product name) - value (account URL) pair.
You can use the domain name to construct api calls that can access product resources.
org_domainstring
Organization domain is the domain value in the organization URL. This organization domain is created when you first sign up for a Freshworks product and is tied to all your accounts across different Freshworks products. You can use this value to pre-populate the organization domain value during app installation.

Sample code

Sample payload

async function getCurrentHostData() {
  try {
    const data = await client.data.get("currentHost");
    // success operation
    // "data" is {subscribed_modules: [“contact”, “deal”, ... }}
  } catch (error) {
    // failure operation
  }
}

getCurrentHostData();

Note:: The org_domain attribute will only be retrieved as a part of currentHost object in app installation page and edit settings page.

loggedInAgent

Use the sample code shown on the right pane > Sample code tab, to retrieve information on the agent logged into the Freshworks product UI.

Attributes of the loggedInAgent object

idinteger
Identifier of the agent, auto-generated when the agent’s information is configured in the system.
emailstring
Email address of the agent specified when the agent information is created in the Freshworks product system.
avatarobject
Details of the image used as the avatar in the agent profile.
- urlstring
  Link to the location from where the image can be retrieved.
phonestring
Phone number of the agent.
biographystring
Description of the agent.
first_namestring
First name of the agent.
last_namestring
Last name of the agent.
role_idinteger
Identifier of the role assigned to the agent.
Roles can be created with different scopes, which define access and permissions according to the organization's requirements.
role_namestring
Name of the role assigned to the agent.
Roles can be created with different scopes, which define access and permissions according to the organization's requirements.
social_profilesobject
Information pertaining to the social profiles associated with the agent.
- typestring
  Name of the social platform.
  Possible values: facebook, twitter, skype, linkedin.
- idstring
  Social profile ID of the agent.

Sample code

Sample payload

async function getLoggedInAgentData() {
  try {
    const data = await client.data.get("loggedInAgent");
    // success operation
    // "data" is {loggedInAgent: {‘available’: “true”, ... }}
  } catch (error) {
    // failure operation
  }
}

getLoggedInAgentData();

Inbox page

An app deployed on the Inbox page can use the client.data.get(<objectName>) data method and retrieve the following objects:

user

Use the sample code shown on the right pane > Sample code tab, to retrieve information about the user who is a part of the conversation.

Attributes of the user object

idstring
Identifier of the user.
emailstring
Email address of the user.
avatarobject
Details of the image used as the avatar in the user profile.
- urlstring
  Link to the location from where the image can be retrieved.
phonestring
Phone number of the user.
propertiesobject
Key-value pairs containing names and values of the custom user properties.
reference_idstring
External ID used to restore logged-in users.
created_timestring
Timestamp in UTC format, YYYY-MM-DDTHH:MM:SSZ.
first_namestring
First name of the user.
last_namestring
Last name of the user.
social_profilesobject
Information pertaining to the social profiles associated with the user.
- typestring
  Name of the social platform.
  Possible values: facebook, twitter, skype, linkedin.
- idstring
  Social profile ID of the user.

Sample code

Sample payload

async function getUserData() {
  try {
    const data = await client.data.get("user");
    // success operation
    // "data" is {user: {"id": "2681d294-3460-4f32-b5fb-828958995b5c", ... }}
  } catch (error) {
    // failure operation
  }
}

getUserData();

conversation

Use the sample code shown on the right pane > Sample code tab, to retrieve information about the conversation.

Attributes of the conversation object

conversation_idstring
Identifier of the conversation.
conversation_urlstring
URL of the conversation.
app_idstring
Identifier of the Freshchat account.
idstring
Numerical identifier of the conversation.
statusstring
Conversation status value.
assigned_agent_idstring
Identifier of the assigned agent.
assigned_group_idstring
Identifier of the assigned group.
messagesarray of objects
Information pertaining to the message.
- message_partsarray of object
  Information pertaining to the parts in the message.
  textobject
  Contains the content value.
  imageobject
  Contains the image URL.
  url_buttonobject
  Contains details of the URL button.
  urlstring
  Contains the URL value.
  labelstring
  Contains the label value.
  targetstring
  Enum of only two allowed values: _self and _blank.
  quick_reply_buttonobject
  Key value pairs containing the custom reply text and label.
  collectionarray of message sub-parts
  Can contain combinations of text, image, url_button, and quick_reply_button.
- app_idstring
  Identifier of the app.
- actor_idstring
  Identifier of the actor.
- idstring
  Identifier of the message.
- channel_idstring
  Identifier of the channel.
- conversation_idstring
  Identifier of the conversation.
- message_typestring
  Type of message.
- actor_typestring
  Type of actor, user, or agent.
- created_timestring
  Timestamp of when the conversation was created in the Freshchat system, specified in the UTC format.
agentsobject
Information pertaining to the agent involved in the conversation.
usersobject
Information pertaining to the user involved in the conversation.

Sample code

Sample payload

async function getConversationData() {
  try {
    const data = await client.data.get("conversation");
    // success operation
    //data: {conversation: {“conversation_id": “c2937604-0a08-43c2-a09c-e77f5f565a0e”, ...}}
  } catch (error) {
    // failure operation
  }
}

getConversationData();

emailConfig

Freshchat allows you to configure email to send and receive messages as conversations directly within the platform. For more information on setting up email for forwarding, see how to add support emails in Freschat.

Use the sample code shown on the right pane > Sample code tab, to retrieve details of email configurations set up for the Email Editor in the conversation inbox.

Attributes of the emailConfig object

assignToGroupIdinteger
Identifier of the group to which the email conversations are assigned.
The emails sent to the support email can be set for forwarding to create email conversations in the Freshchat inbox page.
forwardingEmailstring
Email address to which the support emails are forwarded.
idstring
Identifier of the emailConfig object, auto-generated when an email conversation is initiated in the Freshchat system.
replyEmailstring
Email address from which the reply email is to be sent.
senderNamestring
Sender name defined while setting up a support email for forwarding.
topicIdinteger
Identifer of the topic that the email conversation is categorized under.
Topics can be set up to categorize different issues based on which conversations can be assigned to the relevant group/agent.

Sample code

Sample payload

async function getEmailConfigData() {
  try {
    const data = await client.data.get("emailConfig");
    // success operation
    // "data" is {emailConfig: {‘available’: “true”, ... }}
  } catch (error) {
    // failure operation
  }
}
getEmailConfigData();

Use data methodOn this page

Data objects accessible from all pages

currentHost

loggedInAgent

Inbox page

user

conversation

emailConfig

Use data method