NAV

Introduction

All API methods should be called on the onLoad event

HFCHAT_CONFIG.onload = function() {

 var HappyFoxChat = this;

};

HappyFox Chat JavaScript API provides you more control over the chat widget. You can customize the widget behavior programmatically.

All API methods should be called only after the script is loaded.


HappyFox Chat REST API provides you options to fetch your data in a RESTful way. As of now you can only “fetch” data. Over time we will be adding methods for you to create/update objects.

JavaScript API

Set Visitor Info

To Set Visitor Info

HappyFoxChat.setVisitorInfo({
 'name': 'Bob',
 'email': '[email protected]',
 'phoneNumber': '+18005251415'
}, function(err, resp) {
  /**
  * err  -> Incase of failure this will have error object
  * resp -> Passed visitor info object (Here: { 'name': 'Bob', 'email': '[email protected]', 'phoneNumber': '+18005251415' })
  */
  if(err) {
    console.error('Failed to set visitor details. Error:', err);
  } else {
    console.log('Added visitor details:', resp);
  }
});

You can send in your signed-in user’s name and email by simply calling the setVisitorInfo method to pass those details. This is will skip the pre-chat form for the users.

Mandatory properties that needs to be set:

Syntax - setVisitorInfo

HappyFoxChat.setVisitorInfo(<visitorInfoObject>, <callback>);

Get Visitor Info

To Get Visitor Info

HappyFoxChat.getVisitorInfo(function(err, resp) {
  /**
  * err  -> Incase of failure this will have error object
  * resp -> Visitor Info object (Example: { 'name': 'Bob', 'email': '[email protected]', phoneNumber: '+18005251415' })
  */
  if(err) {
    console.error('Failed to set visitor details. Error:', err);
  } else {
    console.log('Got visitor info:', resp);
  }
});

Properties returned by this method:

Syntax - getVisitorInfo

HappyFoxChat.getVisitorInfo(<callback>);

Unset Visitor

To Unset Visitor

HappyFoxChat.unsetVisitor(function(err) {
 if (err) {
  console.error('Failed to reset the visitor. Error:', err);
 } else {
  console.log('Visitor reset successful');  
 }
});

If you want to clear or unset the visitor details when your visitor logs off, you can call the method unsetVisitor API to clear the pre-filled data.

Syntax - unsetVisitor

HappyFoxChat.unsetVisitor(<callback>);

Set Custom Fields

To Set Custom Fields

HappyFoxChat.setCustomFields({
 'Account Number': '1234567890',
 'Branch': 'CA',
 'Type': 'Free'
}, function(err, resp) {
 if(err) {
  console.error('Failed to add given properties to custom fields. Error:', err);
 } else {
  console.log('Added custom field properties:', resp);
 }
});

HappyFoxChat.unsetCustomFields([
 'Account Number',
 'Branch'
], function(err, resp) {
 /**
  * err  -> Incase of failure this will have error object
  */
 if(err) {
  console.error('Failed to unset given custom field values. Error:', err);
 } else {
  console.log('Successfully unset custom fields');
 }
});

The custom field is a way to pass more data about visitors from your website to HappyFox Chat without any action needed from them. Using this API, you can set or unset custom field values.

<customField[Object]> should have properties defined inside HappyFox Chat

Syntax - setCustomFields

HappyFoxChat.setCustomFields(<customFieldObject>, <callback>);

Syntax - unsetCustomFields

HappyFoxChat.unsetCustomFields(["<customFieldName>", "<customFieldName>", ... ], <callback>);

Get Custom Field

To Get Custom Field

HappyFoxChat.getCustomField("Type", function (err, value) {
 /**
  * err  -> Incase of failure this will have error object
  */
 if(err) {
  console.error('Failed to unset given custom field values. Error:', err);
 } else {
  console.log('Successfully got custom field value. Value:', value);
 }
});

Get a custom field value from the chat widget. This function will throw an error if the field is not set previously or if the field is not created in your account.

Syntax - getCustomField

HappyFoxChat.getCustomField("<customFieldName>", <callback>);

Set Preferred Department

To Set Preferred Department By Department Name

HappyFoxChat.setPreferredDepartmentByName('Sales', function (err) {
  if (err) {
    console.error('Error while trying to set preferred department. Error:', err)
  } else {
    console.log('Successfully set preferred department')
  }
})

To Set Preferred Department By Department ID

HappyFoxChat.setPreferredDepartment('5f74b35853c1ef806d56e765', function (err) {
  if (err) {
    console.error('Error while trying to set preferred department by ID. Error:', err)
  } else {
    console.log('Successfully set preferred department by ID')
  }
})

You can set the department to which the chat should be routed by using following methods.

Syntax - setPreferredDepartmentByName

Syntax - setPreferredDepartment

Unset Preferred Department

To Unset Preferred Department

HappyFoxChat.unsetPreferredDepartment(function (err) {
  if (err) {
    console.error('Error while trying to unset preferred department. Error:', err)
  } else {
    console.log('Successfully unset preferred department')
  }
})

You can unset the already set preferred department by using following method.

Syntax - unsetPreferredDepartment

Get Current Preferred Department

To Get Current Preferred Department

HappyFoxChat.getPreferredDepartment(function (err, departmentObject) {
  if (err) {
    console.error('Error while trying to get current preferred department. Error:', err)
  } else {
    console.log('Current preferred department is: ', departmentObject)
  }
})

Sample Department Object

{
  "_id": "5ffdb3447a8ce53deb6d77b6",
  "name": "Sales",
  "isDefault": false,
  "isAvailable": true,
  "isBusy": false,
  "isAvailableAndFree": true
}

You can get the already set preferred department by using following method.

Syntax - getPreferredDepartment

Department Object:

Property Type Description
_id String ID of the department.
name String Name of the department.
isDefault Boolean Will be true if current deparment is the default department of the profile (Default department has all agents in it).
isAvailable Boolean Will be true if at-least one agent of the department is online and available.
isBusy Boolean Will be true if all available agents of the department are busy.
isAvailableAndFree Boolean Will be true if at-least one agent of the department is available and not busy.

Get All Departments

To Get All Departments

HappyFoxChat.getDepartments(function (err, departmentObjects) {
  if (err) {
    console.error('Error while trying to get all departments. Error:', err)
  } else {
    console.log('Departments:', departmentObjects)
  }
})

Sample Department Objects

[
  {
    "_id": "7ffdb3447a8ce53deb6d77b9",
    "name": "Default",
    "isDefault": true,
    "isAvailable": true,
    "isBusy": false,
    "isAvailableAndFree": true
  },
  {
    "_id": "5ffdb3447a8ce53deb6d77b6",
    "name": "Sales",
    "isDefault": false,
    "isAvailable": true,
    "isBusy": false,
    "isAvailableAndFree": true
  }
]

You can get available departments of the profile by using following method.

Syntax - getDepartments

Department Object:

Property Type Description
_id String ID of the department.
name String Name of the department.
isDefault Boolean Will be true if current deparment is the default department of the profile (Default department has all agents in it).
isAvailable Boolean Will be true if at-least one agent of the department is online and available.
isBusy Boolean Will be true if all available agents of the department are busy.
isAvailableAndFree Boolean Will be true if at-least one agent of the department is available and not busy.

Add Custom Styles

To Add Custom Styles

HappyFoxChat.addCustomStyles('.hfc-title-text { color: #0000FF !important; } .hfc-title-bar { background-color: #00FF00 !important; }', function(err) {
 /**
  * err  -> Incase of failure this will have error object
  */
  if (err) {
    console.error('Failed to add custom styles. Error:', err);
  } else {
    console.log('Added custom styles');
  }
});

To make CSS customization or to change the style of the widget, use the below API.

Syntax - addCustomStyles

HappyFoxChat.addCustomStyles(<customStyle>);

Add Custom CSS File

To Add Custom CSS File

HappyFoxChat.addCustomCSSFile('http://mydomain.com/css/happyfoxchat-custom.css', function(err) {
 /**
  * err  -> Incase of failure this will have error object
  */
 if(err) {
  console.error('Failed to add custom CSS file. Error:', err);
 } else {
  console.log('Added custom CSS file');
 }
});

Pass in the URL of your own CSS file to customise the look & feel according to your brand aesthetics.

Syntax - addCustomCSSFile

HappyFoxChat.addCustomCSSFile(<customCSSFileUrl>);

Expand/Collapse Chatbox

To Expand/Collapse Chatbox

HappyFoxChat.expandChatbox(function(err) {
 /**
  * err  -> Incase of failure this will have error object
  */
 if(err) {
  console.error('Failed to expand chatbox. Error:', err);
 } else {
  console.log('Expanded chatbox');
 }
});

Expand and Collapse the chat widget programmatically using this function. This is of great use when you want to expand/collapse the chat widget for certain scenarios in your page. For exampe - you can expand the chat widget when users click “Chat with us” link anywhere on your website.

Syntax - expandChatbox

HappyFoxChat.expandChatbox(<callback>);

Syntax - collapseChatbox

HappyFoxChat.collapseChatbox(<callback>);

Track page navigation

To programmatically capture page navigation

HappyFoxChat.pageLoaded(function (err) {
  if (err) {
    console.error('Failed to capture page navigation. Error:', err)
    return
  }
  console.log('Successfully captured page navigation')
})

React Single Page Application Example Usage

history.listen(function (location) {
  console.log('Page navigated to', location.pathname)
  HappyFoxChat.pageLoaded()
})

Programmatically capture page navigations using this function. This can come handy when you install chat widget on a Single Page Application (SPA) where the internal page navigations cannot be tracked by default by the chat widget and has to be tracked manually. There are lot of Single Page Application frameworks out there and all most of the framework provides hooks for internal page navigation action, these hooks can be used to let the chat widget know that internal page navigation has happened. Please refer example for usage.

Syntax

HappyFoxChat.pageLoaded(<callback>)

Show/Hide Widget

Show and hide the chat widget programmatically using this function. This is of great use when you want to optionally show the widget on some pages in your website.

Syntax - showWidget

HappyFoxChat.showWidget(<callback>);

Syntax - hideWidget

HappyFoxChat.hideWidget(<callback>);

Show/Hide Badge

Show and hide the Badge on chat widget programmatically using this function.

Syntax - showBadge

HappyFoxChat.showBadge(<callback>);

Syntax - hideBadge

HappyFoxChat.hideBadge(<callback>);

Unload widget

To unload widget from webpage

HappyFoxChat.destroy(function (err) {
  if (err) {
    console.error('Failed to destroy widget. Error:', err)
    return
  }
  console.log('Successfully destroyed widget')
})

Unload widget from the webpage.

Syntax HappyFoxChat.destroy(<callback>)

Get Agents Availability

To Get Agents Availability

HappyFoxChat.getAgentsAvailability(function (err, agentsAvailability) {
  ...
});

Using this function, you can check whether your chat support agents are available to chat now.

Get Visitor State

To Get Visitor State

HappyFoxChat.getVisitorState(function (err, visitorState) {
  ...
  visitorState can be "passive"/"waiting_for_agent"/"chattting"
});

Using this function, you can fetch the Visitor’s current chat state.

Get Proactive Message

To Get Proactive Message

HappyFoxChat.getProactiveMessage(function (err, proactiveMessage) {
  ...
});

Get Widget Properties

To Get Widget Properties

HappyFoxChat.getWidgetProperties(function (err, widgetProperties) {
  ...
});

Config

To Set Config Options

HFCHAT_CONFIG.options = {
  forceShowWidget: true, // If true then it will show widget no matter what Chat status admin sets
  showBadge: false,  // Will hide badge permanently
  showBadgeOnLoad: false,  // Will hide badge only on load, if user opens widget once [by invoking HappyFoxChat.expandChatbox()] then it will start to show the badge
  customStyles: '.hfc-title-text { color: #0000FF !important; } .hfc-title-bar { background-color: #00FF00 !important; }',
  customCSSFiles: ['http://mydomain.com/css/happyfoxchat-custom.css'],
  proactiveRequestDropTimeout: 5 * 60 * 1000, // 5 mins
  waitingMessage: 'Please wait for our agents to reply', // This feature is available only in specific plans
  waitingMessageDelay: 30 // in seconds
};

You can configure the widget using the HFCHAT_CONFIG.options object.

Events

To Listen Events

HappyFoxChat.on('click:badge', function () {
  console.log('Chat with us badge clicked');
});

You can listen to various events from the widget.

Supported Events:

REST API

Authentication

HappyFox Chat REST API uses API Tokens to allow access to the API. Admins can create new API Tokens in apps > Goodies section.

HappyFox Chat expects the API Token to be included in all API requests made to the server in the header with the following format:

Authorization: Bearer [API Token] (without the square brackets).

Pagination

All ‘LIST’ endpoints by default provides paginated response. Paginated responses have properties - meta, data and links.

Corresponding endpoints’ sections below can be referred for sample responses.

Page and Limit

The Page number and Number of records per page can be specified through query params page and limit respectively.

Meta

meta property has members page and totalPages indicating the current page and total number of pages for that request.

Data

data property contains the actual data that was queried for. data is of type array and may be empty or may contain one or more records, depending on the request.

links object contains properties with urls as their values. If there are more results available, property next is present, which can be used to fetch the next set of results.

API Rate Limit

All API endpoints have fixed Rate Limit. As of now it is 100 req/minute. If you want a higher limit, contact [email protected] .

Transcripts

Get All Transcripts

curl "https://api.happyfoxchat.com/v1/transcripts?page=1&limit=2"
  -H "Authorization: Bearer [API Token]"

The above command returns JSON structured like this:

{
  "meta": {
      "page": 1,
      "totalPages": 6
  },
  "data": [
      {
        "_id": "5979bdee49eca059dae452cc",
        "visitor": {
          "_id": "5979bdee49eca059dae452cb",
          "createdAt": "2017-07-27T10:18:22.151Z",
          "updatedAt": "2017-07-27T10:18:22.151Z",
          "repeatVisitor": false,
          "stats": {
            "ipAddress": "182.73.135.26",
            "utmParams": null,
            "browser": {
                "patch": "3071",
                "minor": "0",
                "major": "59",
                "family": "Chrome"
            },
            "os": {
                "patchMinor": null,
                "patch": "5",
                "minor": "12",
                "major": "10",
                "family": "Mac OS X"
            },
            "device": {
                "family": "Other"
            },
            "timezone": "Asia/Calcutta",
            "pages": [
                {
                    "title": "HappyFox Live Chat",
                    "domain": "https://happyfoxchat.com",
                    "url": "https://happyfoxchat.com/chat/2c768310-6dd7-11e7-ae75-a9ecadeb7ee6",
                    "referrer": "",
                    "userAgent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_12_5) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/59.0.3071.115 Safari/537.36",
                    "timestamp": "Thu, 27 Jul 2017 10:17:45 GMT",
                    "dimension": {
                        "width": 1440,
                        "height": 900
                    }
                }
            ]
          },
          "email": "[email protected]",
          "name": "Viktor",
          "visitorChatId": 23485,
          "__v": 0,
          "lastEventTimestamp": "2017-07-27T10:18:20.000Z",
          "id": "5979bdee49eca059dae452cb"
        },
        "timestamp": "2017-07-27T10:17:59.000Z",
        "profile": {
          "_id": "597193eaa32cb73021e37420",
          "name": "Support"
        },
        "totalMessages": "3",
        "firstMessage": "Hello",
        "companyChatId": 2886,
        "hasTranslatedText": false,
        "rating": {
          "feedback": "Very Poor service",
          "pattern": "star",
          "ratedOn": "2017-07-27T10:18:48.417Z",
          "type": "visitor-given",
          "value": 1
        },
        "integrationLogs": [],
        "tags": [
          "63970836c73762460361b475",
          "63970836d086dd461040f1d0"
        ],
        "tagsDetails": [
          {
            "_id": "63970836c73762460361b475",
            "name": "bug"
          },
          {
            "_id": "63970836d086dd461040f1d0",
            "name": "critical"
          }
        ],
        "messages": [
          {
            "type": "VisitorSessionBegan",
            "timestamp": "2017-07-27T10:17:59.000Z"
          },
          {
            "messageId": 1,
            "type": "VisitorMessage",
            "author": {
                "id": 23485,
                "name": "Viktor"
            },
            "text": "Hello",
            "timestamp": "2017-07-27T10:18:01.000Z",
            "subType": ""
          },
          {
            "type": "AgentJoined",
            "author": {
                "id": 3872,
                "name": "Sam Mendis"
            },
            "timestamp": "2017-07-27T10:18:05.000Z"
          },
          {
            "messageId": 2,
            "type": "AgentMessage",
            "author": {
                "id": 3872,
                "name": "Sam Mendis"
            },
            "text": "Good Morning, How may I help you?",
            "timestamp": "2017-07-27T10:18:09.000Z",
            "subType": ""
          },
          {
            "messageId": 3,
            "type": "VisitorMessage",
            "author": {
                "id": 23485,
                "name": "Viktor"
            },
            "text": "Will there be a Black Friday Sale?",
            "timestamp": "2017-07-27T10:18:15.000Z",
            "subType": ""
          },
          {
            "type": "VisitorBecameInactive",
            "endEvent": "VisitorEndedTheConversation",
            "timestamp": "2017-07-27T10:18:20.000Z"
          }
        ],
        "stats": {
          "waitingTime": 8,
          "averageResponseTime": 8,
          "totalChatDuration": 14
        },
        "departments": [
          {
            "_id": "597193eca32cb73021e37421",
            "name": "Default"
          }
        ],
        "agents": [
          {
            "agentChatId": 3872,
            "name": "Sam Mendis",
            "_id": "5979bdee49eca059dae452cd"
          }
        ],
        "isMissed": false,
        "isTriggeredChat": true,
        "isProactiveChat": false,
        "agent_names": "Sam Mendis",
        "id": "5979bdee49eca059dae452cc"
    }
  ],
  "links": {
      "next": "https://api.happyfox.com/v1/transcripts?page=2&limit=1"
  }
}

This endpoint retrieves all Transcripts.

HTTP Request

GET https://api.happyfoxchat.com/v1/transcripts

REQUEST HEADER

Header Value
Timezone Timezone String

eg: America/New_York, Asia/Calcutta etc.

URL Queries

Query Description
agent_email e-mail of the agent, transcripts featuring whom needs to be retrieved.
agent_id ID of the agent, transcripts featuring whom needs to be retrieved.
visitor_email e-mail of the visitor, transcripts featuring whom needs to be retrieved.
visitor_id ID of the visitor, transcripts featuring whome needs to be retrieved.
department_id ID of the department to which the transcripts need to belong.
profile_id ID of the widget profile in which the transcripts need to have taken place.
date_from The start of the date range, after which the transcript has to have taken place.
date_to The end of the date range, before which the transcript has to have taken place.
time_period Time periods to which the transcripts should belong can be specified.
page Page number of the list of transcripts.
limit Number of transcripts per response for a given page number.
agents Agents participated in the Chat.

Get a Specific Transcript

curl "https://api.happyfoxchat.com/v1/transcripts/<transcriptId>"
  -H "Authorization: Bearer [API Token]"

The above command returns JSON structured like this:

{
    "_id": "5979bdee49eca059dae452cc",
    "visitor": {
      "_id": "5979bdee49eca059dae452cb",
      "createdAt": "2017-07-27T10:18:22.151Z",
      "updatedAt": "2017-07-27T10:18:22.151Z",
      "repeatVisitor": false,
      "stats": {
        "ipAddress": "182.73.135.26",
        "utmParams": null,
        "browser": {
            "patch": "3071",
            "minor": "0",
            "major": "59",
            "family": "Chrome"
        },
        "os": {
            "patchMinor": null,
            "patch": "5",
            "minor": "12",
            "major": "10",
            "family": "Mac OS X"
        },
        "device": {
            "family": "Other"
        },
        "timezone": "Asia/Calcutta",
        "pages": [
            {
                "title": "HappyFox Live Chat",
                "domain": "https://happyfoxchat.com",
                "url": "https://happyfoxchat.com/chat/2c768310-6dd7-11e7-ae75-a9ecadeb7ee6",
                "referrer": "",
                "userAgent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_12_5) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/59.0.3071.115 Safari/537.36",
                "timestamp": "Thu, 27 Jul 2017 10:17:45 GMT",
                "dimension": {
                    "width": 1440,
                    "height": 900
                }
            }
        ]
      },
      "email": "[email protected]",
      "name": "Viktor",
      "visitorChatId": 23485,
      "__v": 0,
      "lastEventTimestamp": "2017-07-27T10:18:20.000Z",
      "id": "5979bdee49eca059dae452cb"
    },
    "timestamp": "2017-07-27T10:17:59.000Z",
    "profile": {
      "_id": "597193eaa32cb73021e37420",
      "name": "Support"
    },
    "totalMessages": "3",
    "firstMessage": "Hello",
    "companyChatId": 2886,
    "hasTranslatedText": false,
    "rating": {
      "feedback": "Very Poor service",
      "pattern": "star",
      "ratedOn": "2017-07-27T10:18:48.417Z",
      "type": "visitor-given",
      "value": 1
    },
    "integrationLogs": [],
    "tags": [
      "63970836c73762460361b475",
      "63970836d086dd461040f1d0"
    ],
    "tagsDetails": [
      {
        "_id": "63970836c73762460361b475",
        "name": "bug"
      },
      {
        "_id": "63970836d086dd461040f1d0",
        "name": "critical"
      }
    ],
    "messages": [
      {
        "type": "VisitorSessionBegan",
        "timestamp": "2017-07-27T10:17:59.000Z"
      },
      {
        "messageId": 1,
        "type": "VisitorMessage",
        "author": {
            "id": 23485,
            "name": "Viktor"
        },
        "text": "Hello",
        "timestamp": "2017-07-27T10:18:01.000Z",
        "subType": ""
      },
      {
        "type": "AgentJoined",
        "author": {
            "id": 3872,
            "name": "Sam Mendis"
        },
        "timestamp": "2017-07-27T10:18:05.000Z"
      },
      {
        "messageId": 2,
        "type": "AgentMessage",
        "author": {
            "id": 3872,
            "name": "Sam Mendis"
        },
        "text": "Good Morning, How may I help you?",
        "timestamp": "2017-07-27T10:18:09.000Z",
        "subType": ""
      },
      {
        "messageId": 3,
        "type": "VisitorMessage",
        "author": {
            "id": 23485,
            "name": "Viktor"
        },
        "text": "Will there be a Black Friday sale",
        "timestamp": "2017-07-27T10:18:15.000Z",
        "subType": ""
      },
      {
        "type": "VisitorBecameInactive",
        "endEvent": "VisitorEndedTheConversation",
        "timestamp": "2017-07-27T10:18:20.000Z"
      }
    ],
    "stats": {
      "waitingTime": 8,
      "averageResponseTime": 8,
      "totalChatDuration": 14
    },
    "departments": [
      {
        "_id": "597193eca32cb73021e37421",
        "name": "Default"
      }
    ],
    "agents": [
      {
        "agentChatId": 3872,
        "name": "Sam Mendis",
        "_id": "5979bdee49eca059dae452cd"
      }
    ],
    "isMissed": false,
    "isTriggeredChat": true,
    "isProactiveChat": false,
    "agent_names": "Sam Mendis",
    "id": "5979bdee49eca059dae452cc"
}

This endpoint retrieves a specific Transcript.

HTTP Request

https://api.happyfoxchat.com/v1/transcripts/<transcriptId>

URL Parameters

Parameter Description
transcriptId The _id of the Transcript to retrieve.
Transcript Property Description
_id ID of the given transcript.
agents Agents associated with the Chat.
departments Departments associated with the Chat.
visitor Details of the visitor associated with the Chat.
companyChatId Secondary identifier of your Company.
stats Stats pertaining to the visitor associated with the Chat.
rating Rating provided by the Visitor for the Chat session.
createdAt Date when Transcript created.
updatedAt Date when Transcript updated.
timestamp Timestamp of the first user-message.
messages All messages under the transcript.
firstMessage First user-message in the Transcript.
totalMessages Total number of user-messages in the Transcript.
tags IDs of tags that are assigned to the Transcript.
tagsDetails Details of the tags that are assigned to the Transcript.
customFields Custom Field values set via the JavaScript API.
profile Profile of the widget in which the Chat took place.
hasTranslatedText Boolean indicating whether or not the chat contains Live Translated content.
sourceLangCode Actual language the Chat took place in.
targetLangCode The Language to which the Chat was translated to.
isMissed Boolean indicating whether or not the chat is a Missed Chat.
isTriggeredChat Boolean indicating whether or not the chat is a Triggered Chat.
isProactiveChat Boolean indicating whether or not the chat is a Proactive Chat.

Offline Messages

Get All Offline Messages

curl "https://api.happyfoxchat.com/v1/offline-messages?page=1&limit=2"
  -H "Authorization: Bearer [API Token]"

The above command returns JSON structured like this:

{
  "meta": {
      "page": 1,
      "totalPages": 5
  },
  "data": [
    {
      "_id": "59788ac89051246e91e1c7af",
      "profileId": "597193eaa32cb73021e37420",
      "message": "Hi, please get back to me.",
      "createdAt": "2017-10-24T06:04:48.073Z",
      "chatFromUrl": "https://happyfoxchat.com/chat/2c768310-6dd7-11e7-ae75-a9ecadeb7ee6",
      "name": "Xavier Brown",
      "email": "[email protected]",
      "phoneNumber": "+919380358107",
      "department": "597193eca32cb73021e37421",
      "tags": [
        "63970836c73762460361b475",
        "63970836d086dd461040f1d0"
      ],
      "events": [],
      "profileId": "597193eaa32cb73021e37420"
    },
    {
      "_id": "59788ac89051246e91e1c7aa",
      "profileId": "597193eaa32cb73021e37420",
      "message": "Hi, please get back to me.",
      "createdAt": "2017-10-27T06:04:48.073Z",
      "chatFromUrl": "https://happyfoxchat.com/chat/2c768310-6dd7-11e7-ae75-a9ecadeb7ee6",
      "name": "Xavier Brown",
      "email": "[email protected]",
      "department": "597193eca32cb73021e37421",
      "tags": [
        "63970836c73762460361b475",
        "63970836d086dd461040f1d0"
      ],
      "events": [],
      "profileId": "597193eaa32cb73021e37420"
    }
  ],
  "links": {
    "next": "https://api.happyfox.com/v1/offline-messages?page=2&limit=2"
  }
}

This endpoint retrieves all Offline Messages.

HTTP Request

GET https://api.happyfoxchat.com/v1/offline-messages

REQUEST HEADER

Header Value
Timezone Timezone String

eg: America/New_York, Asia/Calcutta etc.

URL Queries

Query Description
page Page number of the list of Offline Messages.
limit Number of Offline Messages per response for a given page number.

Get a Specific Offline Message

curl "https://api.happyfoxchat.com/v1/offline-messages/<offlineMessageId>"
  -H "Authorization: Bearer [API Token]"

The above command returns JSON structured like this:

{
  "_id": "59788ac89051246e91e1c7af",
  "profileId": "597193eaa32cb73021e37420",
  "message": "Hi, please get back to me.",
  "createdAt": "2017-10-27T06:04:48.073Z",
  "chatFromUrl": "https://happyfoxchat.com/chat/2c768310-6dd7-11e7-ae75-a9ecadeb7ee6",
  "name": "Xavier Brown",
  "email": "[email protected]",
  "department": "597193eca32cb73021e37421",
  "tags": [
    "63970836c73762460361b475",
    "63970836d086dd461040f1d0"
  ],
  "events": []
}

This endpoint retrieves a particular Offline Message

HTTP Request

https://api.happyfoxchat.com/v1/offline-messages/<offlineMessageId>

URL Parameters

Parameter Description
offlineMessageId The _id of the Offline Message to retrieve.
Offline Message Property Description
_id ID of the given Offline Message.
name Name of the Visitor.
phoneNumber Phone Number of the Visitor.
email e-mail of the Visitor.
message Message from the Visitor.
department Department the Visitor intended to contact.
profileId ID of the profile of widget, via which the Visitor left a message.
createdAt Date when Offline Message was created.
updatedAt Date when Offline Message last updated.
tags IDs of tags that are assigned to the Offline Message.
events Events associated with the Offline Message.
chatFromUrl URL of the page, from where the Visitor left the message.
customFields Custom Field values, if set via the JavaScript API.

Agents

Get All Agents

curl "https://api.happyfoxchat.com/v1/agents?limit=2"
  -H "Authorization: Bearer [API Token]"

The above command returns JSON structured like this:

{
  "meta": {
    "page": 1,
    "totalPages": 5
  },
  "data": [
    {
      "_id": "597193e2a32cb73021e3741e",
      "name": "Sam Mendis",
      "email": "[email protected]",
      "isAdmin": true,
      "agentChatId": 3873,
      "displayName": "Sam Mendis",
      "chatLimit": 4,
      "createdAt": "2017-07-13T11:09:11.913Z",
      "updatedAt": "2017-06-04T07:52:54.369Z",
      "deleted": false,
      "timezone": "UTC",
      "isOwner": true
    },
    {
      "_id": "59719494a32cb73021e37424",
      "name": "Mark Rylance",
      "agentChatId": 3872,
      "email": "[email protected]",
      "isAdmin": false,
      "invitedBy": "597193e2a32cb73021e3741e",
      "displayName": "Mark Rylance",
      "chatLimit": 0,
      "createdAt": "2017-07-13T12:08:11.913Z",
      "updatedAt": "2017-06-04T10:12:54.369Z",
      "ratings": {
          "average": 3.875,
          "totalRatedChats": 16,
          "fiveStarCount": 5,
          "fourStarCount": 8,
          "threeStarCount": 0,
          "twoStarCount": 2,
          "oneStarCount": 1
      },
      "deleted": false,
      "timezone": "UTC",
      "isOwner": false
    }
  ],
  "links": {
    "next": "https://api.happyfoxchat.com/v1/agents?page=2&limit=2"
  }
}

This endpoint retrieves all agents. data will consist of an array of agents.

HTTP Request

GET https://api.happyfoxchat.com/v1/agents

URL Queries

Query Description
page Page number of the list of agents.
limit Number of agents per response for a given page number.

Get a Specific Agent

curl "https://api.happyfoxchat.com/v1/agents/<agentId>"
  -H "Authorization: Bearer [API Token]"

The above command returns JSON structured like this:

  {
      "_id": "59719494a32cb73021e37424",
      "name": "Mark Rylance",
      "agentChatId": 3872,
      "email": "[email protected]",
      "displayName": "Mark Rylance",
      "displayImageUrl": "https://cdn1.iconfinder.com/data/icons/ninja-things-1/1772/ninja-simple-512.png",
      "timezone": "UTC",
      "isOwner": false,
      "isAdmin": false,
      "invitedBy": "597193e2a32cb73021e3741e",
      "deleted" : false,
      "createdAt": "2017-07-13T12:08:11.913Z",
      "updatedAt": "2017-06-04T10:12:54.369Z",
      "ratings": {
        "oneStarCount" : 1,
        "twoStarCount" : 0,
        "threeStarCount" : 0,
        "fourStarCount" : 0,
        "fiveStarCount" : 0,
        "totalRatedChats" : 1,
        "average" : 1
      },
      "chatLimit": 0
  }

This endpoint retrieves a specific agent.

HTTP Request

https://api.happyfoxchat.com/v1/agents/<agentId>

URL Parameters

Parameter Description
agentId The _id of the Agent to retrieve.
Agent Property Description
_id ID of the given agent
name Name of the image as entered while Signing up.
email e-mail ID of the agent.
displayName Display name of the agent if set by them, also shown to visitors.
displayImageUrl URL of the Display Image as set by the agent.
agentChatId Secondary identifier of the given agent.
timezone Timezone of the agent.
isOwner Boolean indicating whether the agent is the Owner.
isAdmin Boolean indicating whether the agent is an Admin.
invitedBy Agent ID of agent who invited the given agent, If joined through invitation.
createdAt Date when agent created.
updatedAt Date when agent updated.
deleted Boolean indicating whether the agent has been deleted or not.
ratings Ratings received by the agent.
chatLimit Number of chats the agent can handle, if set by an Admin.

Visitors

Get All Visitors

curl "https://api.happyfoxchat.com/v1/visitors?page=1&limit=1"
  -H "Authorization: Bearer [API Token]"

The above command returns JSON structured like this:

{
    "meta": {
        "page": 1,
        "totalPages": 5
    },
    "data": [
      {
        "_id": "5979bdee49eca059dae452cb",
        "createdAt": "2017-07-13T11:09:11.913Z",
        "updatedAt": "2017-06-04T07:52:54.369Z",
        "repeatVisitor": false,
        "stats": {
            "ipAddress": "182.73.135.26",
            "utmParams": null,
            "browser": {
                "patch": "3071",
                "minor": "0",
                "major": "59",
                "family": "Chrome"
            },
            "os": {
                "patchMinor": null,
                "patch": "5",
                "minor": "12",
                "major": "10",
                "family": "Mac OS X"
            },
            "device": {
                "family": "Other"
            },
            "timezone": "America/Chicago",
            "pages": [
              {
                  "title": "HappyFox Live Chat",
                  "domain": "https://happyfoxchat.com",
                  "url": "https://happyfoxchat.com/chat/2c768310-6dd7-11e7-ae75-a9ecadeb7ee6",
                  "referrer": "",
                  "userAgent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_12_5) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/59.0.3071.115 Safari/537.36",
                  "timestamp": "Thu, 27 Jul 2017 10:17:45 GMT",
                  "dimension": {
                      "width": 1440,
                      "height": 900
                  }
              }
            ]
          },
        "email": "[email protected]",
        "name": "Haley Mancini",
        "lastEventTimestamp": "2017-07-27T10:18:20.000Z"
      }
    ],
    "links": {
        "next": "https://api.happyfox.com/v1/visitors?page=2&limit=1"
    }
}

This endpoint retrieves all visitors.

HTTP Request

GET https://api.happyfoxchat.com/v1/visitors

URL Queries

Query Description
page Page number of the list of visitors.
limit Number of visitors per response for a given page number.

Get a Specific Visitor

curl "https://api.happyfoxchat.com/v1/visitors/<visitorId>"
  -H "Authorization: Bearer [API Token]"

The above command returns JSON structured like this:

{
  "_id": "5979afd50fdf371ad634dbc2",
  "createdAt": "2017-07-13T11:09:11.913Z",
  "updatedAt": "2017-06-04T07:52:54.369Z",
  "repeatVisitor": false,
  "stats": {
    "ipAddress": "182.73.135.26",
    "utmParams": null,
    "browser": {
      "patch": "3071",
      "minor": "0",
      "major": "59",
      "family": "Chrome"
    },
    "os": {
      "patchMinor": null,
      "patch": "5",
      "minor": "12",
      "major": "10",
      "family": "Mac OS X"
    },
    "device": {
        "family": "Other"
    },
    "timezone": "Asia/Calcutta",
    "pages": [
      {
        "title": "HappyFox Live Chat",
        "domain": "https://happyfoxchat.com",
        "url": "https://happyfoxchat.com/chat/2c768310-6dd7-11e7-ae75-a9ecadeb7ee6",
        "referrer": "",
        "userAgent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_12_5) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/59.0.3071.115 Safari/537.36",
        "timestamp": "Thu, 27 Jul 2017 09:12:56 GMT",
        "dimension": {
            "width": 1440,
            "height": 900
        }
      }
    ]
  },
  "email": "[email protected]",
  "name": "Brad Hunt",
  "lastEventTimestamp": "2017-07-27T09:16:09.000Z"
}

This endpoint retrieves a specific visitor.

HTTP Request

https://api.happyfoxchat.com/v1/visitors/<visitorId>

URL Parameters

Parameter Description
visitorId The _id of the Visitor to retrieve.
Visitor Property Description
_id ID of the given agent
createdAt Date when Visitor was created.
updatedAt Date when Visitor was last updated.
repeatVisitor Boolean indicating whether the visitor has already been.
stats Stats of the user.
email e-mail address of the visitor.
phoneNumber Phone Number of the visitor.
name Name of the visitor.
lastEventTimestamp Timestamp of the last know event performed by the visitor.

Profiles

Get All Profiles

curl "https://api.happyfoxchat.com/v1/profiles"
  -H "Authorization: Bearer [API Token]"

The above command returns JSON structured like this:

{
  "meta": {
    "page": 1,
    "totalPages": 1
  },
  "data": [
    {
        "_id": "597195bea32cb73021e3742c",
        "createdAt": "2017-07-21T05:48:48.862Z",
        "updatedAt": "2017-08-25T09:34:27.259Z",
        "embedToken": "4362c740-6dd8-11e7-ae75-a9ecadeb7ee6",
        "name": "Checkout Page Widget",
        "url": "acme.com/checkout",
        "timezone": "Asia/Calcutta",
        "broadcastDepartment": "597195c2a32cb73021e3742d",
        "liveTranslationTargetLangCode": "en",
        "workHours": [],
        "isWorkHoursEnabled": false,
        "offline": {
            "phoneNumber": {
                "enabled": false
            }
        },
        "prechat": {
            "department": {
                "enabled": false
            },
            "phoneNumber": {
                "optional": true,
                "enabled": false
            },
            "email": {
                "optional": false,
                "enabled": true
            },
            "name": {
                "optional": false,
                "enabled": true
            },
            "enabled": true
        },
        "routing": {
            "queueWelcomeMessage": "Hey {visitorName}, All our agents are busy at the moment. You will be attended in a bit.",
            "isQueueEnabled": false,
            "agentsChatLimit": 4,
            "isMaxChatLimitEnabled": false,
            "reassignmentTimeLimit": 60,
            "isReassignmentChatEnabled": false,
            "mode": "broadcast"
        },
        "isDepartmentsEnabled": false,
        "isDeleted": false,
        "isDefault": false,
        "isInstalled": [],
        "language": "en",
        "general": {
            "transcriptEmail": {
                "active": false,
                "email": ""
            }
        },
        "text": {
            "departmentPickerLabel": "Select Department",
            "offlineSendMessageButton": "Leave a message",
            "startButton": "Start Live Chat",
            "companyGreetingSubtitle": "Live Chat",
            "companyGreeting": "Welcome!",
            "welcomeTextTitle": "Hey there!",
            "firstMessage": "Hi {visitorName}, how can we help you today?",
            "offlineBadge": "Leave us a message!",
            "badge": "Chat with us!",
            "titleBar": "Live Chat",
            "offlineWelcomeText": "Sorry, we are away. Leave us a message and we'll get back to you.",
            "welcomeText": "Welcome to Happyfox Chat. We are here to help you with all the questions you have."
        },
        "appearance": {
            "badgeStyle": "full",
            "showAgentPicture": true,
            "position": "bottomRight",
            "secondaryColor": "ffffff",
            "primaryColor": "d014ff",
            "theme": "flat"
        },
        "hideWidgetWhenOffline": false,
        "removeHfcBranding": false,
        "hideRatingForm": true,
        "maximizedOnLoad": false,
        "hideChatWidget": false,
        "hexColorCode": "cc8be0"
      }
  ],
  "links": {}
}

This endpoint retrieves all Profiles.

HTTP Request

GET https://api.happyfoxchat.com/v1/profiles

URL Queries

Query Description
page Page number of the list of profiles.
limit Number of profiles per response for a given page number.

Get a Specific Profile

curl "https://api.happyfoxchat.com/v1/profiles/<profileId>"
  -H "Authorization: Bearer [API Token]"

The above command returns JSON structured like this:

{
  "_id": "597195bea32cb73021e3742c",
  "createdAt": "2017-07-21T05:48:48.862Z",
  "updatedAt": "2017-08-25T09:34:27.259Z",
  "embedToken": "4362c740-6dd8-11e7-ae75-a9ecadeb7ee6",
  "name": "Checkout Page Widget",
  "url": "acme.com/checkout",
  "timezone": "Asia/Calcutta",
  "broadcastDepartment": "597195c2a32cb73021e3742d",
  "liveTranslationTargetLangCode": "en",
  "workHours": [],
  "isWorkHoursEnabled": false,
  "offline": {
      "phoneNumber": {
          "enabled": false
      }
  },
  "prechat": {
      "department": {
          "enabled": false
      },
      "phoneNumber": {
          "optional": true,
          "enabled": false
      },
      "email": {
          "optional": false,
          "enabled": true
      },
      "name": {
          "optional": false,
          "enabled": true
      },
      "enabled": true
  },
  "routing": {
      "queueWelcomeMessage": "Hey {visitorName}, All our agents are busy at the moment. You will be attended in a bit.",
      "isQueueEnabled": false,
      "agentsChatLimit": 4,
      "isMaxChatLimitEnabled": false,
      "reassignmentTimeLimit": 60,
      "isReassignmentChatEnabled": false,
      "mode": "broadcast"
  },
  "isDepartmentsEnabled": false,
  "isDeleted": false,
  "isDefault": false,
  "isInstalled": [],
  "language": "en",
  "general": {
      "transcriptEmail": {
          "active": false,
          "email": ""
      }
  },
  "text": {
      "departmentPickerLabel": "Select Department",
      "offlineSendMessageButton": "Leave a message",
      "startButton": "Start Live Chat",
      "companyGreetingSubtitle": "Live Chat",
      "companyGreeting": "Welcome!",
      "welcomeTextTitle": "Hey there!",
      "firstMessage": "Hi {visitorName}, how can we help you today?",
      "offlineBadge": "Leave us a message!",
      "badge": "Chat with us!",
      "titleBar": "Live Chat",
      "offlineWelcomeText": "Sorry, we are away. Leave us a message and we'll get back to you.",
      "welcomeText": "Welcome to Happyfox Chat. We are here to help you with all the questions you have."
  },
  "appearance": {
      "badgeStyle": "full",
      "showAgentPicture": true,
      "position": "bottomRight",
      "secondaryColor": "ffffff",
      "primaryColor": "d014ff",
      "theme": "flat"
  },
  "hideWidgetWhenOffline": false,
  "removeHfcBranding": false,
  "hideRatingForm": true,
  "maximizedOnLoad": false,
  "hideChatWidget": false,
  "hexColorCode": "cc8be0"
}

This endpoint retrieves a specific Department.

HTTP Request

https://api.happyfoxchat.com/v1/profiles/<profileId>

URL Parameters

Parameter Description
profileId The _id of the Profile to retrieve.
Profile Property Description
_id ID of the given profile.
name Name of the department.
url Website URL provided at the time of profile creation.
prechat Prechat form settings of the given profile.
routing Routing preferences for the given profile.
broadcastDepartment Default department to route visitors to, if visitors not allowed to choose departments.
text Text information shown to the user under the given profile.
appearance Appearance preferences of the given profile.
general general settings of the given profile.
hideChatWidget Boolean indicating whether or not to hide the Widget.
hideRatingForm Boolean indicating whether ratings prompt has to be shown.
hideWidgetWhenOffline Boolean indicating whether widget has to be hidden, when all agents are offline.
maximizedOnLoad Boolean indicating whether or not the widget should appear maximized, when loaded.
isInstalled Array of page URLs, on which the widget was embedded.
isDeleted Boolean indicating whether the profile has been deleted or not.
embedToken Embed Token for the given profile.
language Language preference for the given profile.
hexColorCode Hex Color Code of the profile.
isDefault Boolean indicating whether or not the Profile is a Default Profile.
timezone Timezone setting for the given Profile.
isWorkHoursEnabled Boolean indicating whether the Work Hour setting is enabled for the profile.
offline Profile settings that are applied when all agents are offline.
removeHfcBranding Boolean indicating whether HappyFox Chat branding has to be removed from Widgets.
isDepartmentsEnabled Boolean indicating whether the visitor should be prompted to choose a department before chat.
createdAt Date when Profile created.
updatedAt Date when Profile updated.
workHours Work Hours Timings.
liveTranslationTargetLangCode Language to be translated to, If Live Translation is enabled.

Departments

Get All Departments

curl "https://api.happyfoxchat.com/v1/departments"
  -H "Authorization: Bearer [API Token]"

The above command returns JSON structured like this:

{
  "meta": {
    "page": 1,
    "totalPages": 1
  },

  "data": [
    {
      "_id": "59719576a32cb73021e37428",
      "name": "Sales",
      "profileId": "597193eaa32cb73021e37420",
      "createdBy": "597193e2a32cb73021e3741e",
      "updatedBy": "597193e2a32cb73021e3741e",
      "createdAt": "2017-07-21T05:50:26.884Z",
      "updatedAt": "2017-10-25T12:12:38.852Z",
      "isDefault": false,
      "isDeleted": false,
      "agents": [
        "597193e2a32cb73021e3741e",
        "59719494a32cb73021e37424"
      ]
    },
    {
      "_id": "59719576a32cb73021e37427",
      "name": "Default",
      "profileId": "597193eaa32cb73021e37420",
      "createdBy": "597193e2a32cb73021e3741e",
      "updatedBy": "597193e2a32cb73021e3741e",
      "createdAt": "2017-05-28T07:38:32.884Z",
      "updatedAt": "2017-10-25T12:12:38.852Z",
      "isDefault": true,
      "isDeleted": false,
      "agents": [
        "597193e2a32cb73021e3741c",
        "59719494a32cb73021e37419"
      ]
    },
    {
      "_id": "59719588a32cb73021e37429",
      "name": "Support",
      "profileId": "597193eaa32cb73021e37420",
      "createdBy": "597193e2a32cb73021e3741e",
      "updatedBy": "597193e2a32cb73021e3741e",
      "createdAt": "2017-07-21T05:50:05.536Z",
      "updatedAt": "2017-10-25T12:12:38.852Z",
      "isDefault": false,
      "isDeleted": false,
      "agents": [
        "597193e2a32cb73021e3741e",
        "597194aba32cb73021e37425"
      ]
    }
  ],
  "links": {}
}

This endpoint retrieves all Departments.

HTTP Request

GET https://api.happyfoxchat.com/v1/departments

URL Queries

Query Description
page Page number of the list of departments.
limit Number of departments per response for a given page number.
profile_id ID of Profile to which the departments trying to be retrieved have to belong to.

Get a Specific Department

curl "https://api.happyfoxchat.com/v1/departments/<departmentId>"
  -H "Authorization: Bearer [API Token]"

The above command returns JSON structured like this:

{
  "_id": "59719576a32cb73021e37428",
  "name": "Sales",
  "profileId": "597193eaa32cb73021e37420",
  "createdBy": "597193e2a32cb73021e3741e",
  "updatedBy": "597193e2a32cb73021e3741e",
  "createdAt": "2017-07-21T05:50:05.536Z",
  "updatedAt": "2017-10-25T12:12:38.852Z",
  "isDefault": false,
  "isDeleted": false,
  "agents": [
    "597193e2a32cb73021e3741e",
    "59719494a32cb73021e37424"
  ]
}

This endpoint retrieves a specific Department.

HTTP Request

https://api.happyfoxchat.com/v1/departments/<departmentId>

URL Parameters

Parameter Description
departmentId The _id of the Department to retrieve.
Department Property Description
_id ID of the given Department.
name Name of the department.
profileId ID of the widget profile the department belongs to.
createdBy ID of the agent who created the department.
updatedBy ID of the agent who last updated the department properties.
createdAt Date when created.
updatedAt Date when last updated.
agents Agents belonging to the department.
isDefault Boolean indicating whether or not the department is a Default Department.
isDeleted Boolean indicating whether the departments has been deleted or not.

Canned Responses

Get All Canned Responses

curl "https://api.happyfoxchat.com/v1/canned-responses"
  -H "Authorization: Bearer [API Token]"

The above command returns JSON structured like this:

{
  "meta": {
    "page": 1,
    "totalPages": 1
  },
  "data": [
    {
      "_id": "5979c42933054d5ada8cd63f",
      "profileId": "597193eaa32cb73021e37420",
      "agentId": "597193e2a32cb73021e3741e",
      "createdAt": "2017-10-13T10:12:54.913Z",
      "updatedAt": "2017-10-04T10:12:54.369Z",
      "isPublic": true,
      "text": "Hi, for pricing details kindly visit https://acme.com/pricing.",
      "shortcode": "pricing"
    },
    {
      "_id": "5979c43d33054d5ada8cd640",
      "profileId": "597193eaa32cb73021e37420",
      "agentId": "597193e2a32cb73021e3741e",
      "createdAt": "2017-10-13T10:54:33.913Z",
      "updatedAt": "2017-10-04T10:54:33.369Z",
      "isPublic": false,
      "text": "Hello, this is Sam, how may I help you today?",
      "shortcode": "hello"
    }
  ],
  "links": {}
}

This endpoint retrieves all Canned Responses.

HTTP Request

GET https://api.happyfoxchat.com/v1/canned-responses

URL Queries

Query Description
page Page number of the list of canned responses.
limit Number of canned responses per response for a given page number.

Get a Specific Canned Response

curl "https://api.happyfoxchat.com/v1/canned-responses/<cannedResponseId>"
  -H "Authorization: Bearer [API Token]"

The above command returns JSON structured like this:

{
  "_id": "5979c42933054d5ada8cd63f",
  "profileId": "597193eaa32cb73021e37420",
  "agentId": "597193e2a32cb73021e3741e",
  "createdAt": "2017-10-13T10:12:54.913Z",
  "updatedAt": "2017-10-04T10:12:54.369Z",
  "isPublic": false,
  "text": "Hi, for pricing details kindly visit https://acme.com/pricing.",
  "shortcode": "pricing"
}

This endpoint retrieves a specific Canned Response.

HTTP Request

https://api.happyfoxchat.com/v1/canned-responses/<cannedResponseId>

URL Parameters

Parameter Description
cannedReponseId The _id of the Canned Response to retrieve.
Canned Response Property Description
_id ID of the given Canned Response.
createdAt Date when Canned Response created.
updatedAt Date when Canned Response updated.
profileId The ID of the profile under which the Canned Response is nested.
agentId The ID of the agent who created the Canned Response.
isPublic Boolean indicating whether the Canned Response is shared by all Agents.
text The Canned Reponse text.
shortcode The shortcode with which the agent can use the Canned Response text in chats.

Custom Fields

Get All Custom Fields

curl "https://api.happyfoxchat.com/v1/custom-fields"
  -H "Authorization: Bearer [API Token]"

The above command returns JSON structured like this:

{
  "meta": {
    "page": 1,
    "totalPages": 1
  },
  "data": [
    {
      "_id": "5979ea52034476cfdfa8a2de",
      "createdAt": "2017-07-27T13:27:46.997Z",
      "updatedAt": "2017-07-27T13:27:46.997Z",
      "label": "Plan",
      "type": "string",
      "required": false
    },
    {
      "_id": "5979ea67034476cfdfa8a2df",
      "createdAt": "2017-07-27T13:28:07.013Z",
      "updatedAt": "2017-07-27T13:28:07.013Z",
      "label": "Subscription Months",
      "type": "number",
      "required": false
    }
  ],
  "links": {}
}

This endpoint retrieves all Custom Fields.

HTTP Request

GET https://api.happyfoxchat.com/v1/custom-fields

URL Queries

Query Description
page Page number of the list of custom fields.
limit Number of custom fields per response for a given page number.

Get a Specific Custom Field

curl "https://api.happyfoxchat.com/v1/custom-fields/<customFieldId>"
  -H "Authorization: Bearer [API Token]"

The above command returns JSON structured like this:

{
  "_id": "5979ea52034476cfdfa8a2de",
  "createdAt": "2017-07-27T13:27:46.997Z",
  "updatedAt": "2017-07-27T13:27:46.997Z",
  "label": "CustomerID",
  "type": "string",
  "required": false
}

This endpoint retrieves a specific Custom Field.

HTTP Request

https://api.happyfoxchat.com/v1/custom-fields/<customFieldId>

URL Parameters

Parameter Description
customFieldId The _id of the Custom Field to retrieve.
Custom Field Property Description
_id ID of the given Custom Field.
label The key of the Custom Field.
type The type of the value of the Custom Field expected.
createdAt Date when Custom Field created.
updatedAt Date when Custom Field created.
required Boolean indicating whether or not Custom Field is mandatory.

Triggered Chats

Get All Triggers

curl "https://api.happyfoxchat.com/v1/triggered-chats"
  -H "Authorization: Bearer [API Token]"

The above command returns JSON structured like this:

[
    {
        "_id": "5979ebd4034476cfdfa8a2e0",
        "createdAt": "2017-07-13T12:08:11.913Z",
        "updatedAt": "2017-06-04T10:12:54.369Z",
        "name": "Pricing Trigger",
        "description": "",
        "active": true,
        "profile": "597193eaa32cb73021e37420",
        "departmentChoice": "597193eca32cb73021e37421",
        "agent": "597193e2a32cb73021e3741e",
        "message": "Hi {visitorName}, need help choosing the right plan for you?",
        "conditions": [
            {
                "type": "url",
                "evaluator": "equals",
                "value": "https://acme.com/pricing"
            },
            {
                "type": "time",
                "evaluator": "gt",
                "value": "60"
            }
        ],
        "conjunction": "and"
    },
    {
        "_id": "5979ec3e034476cfdfa8a2e1",
        "name": "Checkout",
        "description": "",
        "active": true,
        "profile": "597193eaa32cb73021e37420",
        "departmentChoice": "59719576a32cb73021e37428",
        "agent": "597193e2a32cb73021e3741e",
        "message": "Hi {visitorName}, Just let me know If you need help placing an order. I'm right here for ya!",
        "conditions": [
            {
                "type": "visitor",
                "evaluator": "true",
                "value": "first"
            },
            {
                "type": "url",
                "evaluator": "equals",
                "value": "https://acme.com/checkout"
            }
        ],
        "conjunction": "or"
    }
]

This endpoint retrieves all Triggers.

HTTP Request

GET https://api.happyfoxchat.com/v1/triggered-chats

URL Queries

Query Description
page Page number of the list of triggers.
limit Number of triggers per response for a given page number.

Get a Specific Trigger

curl "https://api.happyfoxchat.com/v1/triggered-chats/<triggerId>"
  -H "Authorization: Bearer [API Token]"

The above command returns JSON structured like this:

{
    "_id": "5979ebd4034476cfdfa8a2e0",
    "name": "Pricing Trigger",
    "createdAt": "2017-07-13T12:08:11.913Z",
    "updatedAt": "2017-06-04T10:12:54.369Z",
    "description": "",
    "active": true,
    "profile": "597193eaa32cb73021e37420",
    "departmentChoice": "597193eca32cb73021e37421",
    "agent": "597193e2a32cb73021e3741e",
    "message": "Hi {visitorName}, need help choosing the right plan for you?",
    "conditions": [
        {
            "type": "url",
            "evaluator": "equals",
            "value": "https://acme.com/pricing"
        },
        {
            "type": "time",
            "evaluator": "gt",
            "value": "60"
        }
    ],
    "conjunction": "and"
}

This endpoint retrieves a specific Trigger.

HTTP Request

https://api.happyfoxchat.com/v1/triggered-chats/<triggerId>

URL Parameters

Parameter Description
triggerId The _id of the Trigger to retrieve.
Trigger Property Description
_id ID of the given Trigger.
name Name of the Trigger.
createdAt Date when Trigger created.
updatedAt Date when Trigger updated.
active Boolean indicating whether or not the Trigger is active.
profile Widget Profile, under which the Trigger is available.
agent ID of the agent who created the Trigger.
message Message sent to the user when triggered.
description Description of the Trigger.
departmentChoice Department to which the Trigger reply is to be sent to.
conditions Conditions for the trigger.
conjunction Factor to decide if any or all conditions must be met to trigger.

Webhooks

Webhooks are HTTP POST requests we send for the following events in your account.

Webhook Events

  1. Chat ended
  2. Offline message posted

Configuration

To configure webhooks for a specific profile, please go to Manage > Webhooks section and pick a Profile under the profile switcher. Input a valid http(s) webhook URL in the text field shown & click on Save. From then on, whenever any new transcript/offline message is created for that profile, it will be posted to the configured URL as a HTTP POST request.

You can choose to have same or different webhook URLs for each profile based on your use case.

Payload details

The HTTP POST webhook request will be a JSON request with two keys under it:

Chat ended event payload

JSON structure of received payload:

{   
    "type": "transcript",
    "payload": {
      "_id": "5979bdee49eca059dae452cc",
      "visitor": {
        "_id": "5979bdee49eca059dae452cb",
        "createdAt": "2017-07-27T10:18:22.151Z",
        "updatedAt": "2017-07-27T10:18:22.151Z",
        "repeatVisitor": false,
        "stats": {
          "ipAddress": "182.73.135.26",
          "utmParams": null,
          "browser": {
              "patch": "3071",
              "minor": "0",
              "major": "59",
              "family": "Chrome"
          },
          "os": {
              "patchMinor": null,
              "patch": "5",
              "minor": "12",
              "major": "10",
              "family": "Mac OS X"
          },
          "device": {
              "family": "Other"
          },
          "timezone": "Asia/Calcutta",
          "pages": [
              {
                  "title": "HappyFox Live Chat",
                  "domain": "https://happyfoxchat.com",
                  "url": "https://happyfoxchat.com/chat/2c768310-6dd7-11e7-ae75-a9ecadeb7ee6",
                  "referrer": "",
                  "userAgent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_12_5) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/59.0.3071.115 Safari/537.36",
                  "timestamp": "Thu, 27 Jul 2017 10:17:45 GMT",
                  "dimension": {
                      "width": 1440,
                      "height": 900
                  }
              }
          ]
        },
        "email": "[email protected]",
        "name": "Viktor",
        "visitorChatId": 23485,
        "__v": 0,
        "lastEventTimestamp": "2017-07-27T10:18:20.000Z",
        "id": "5979bdee49eca059dae452cb"
      },
      "timestamp": "2017-07-27T10:17:59.000Z",
      "profile": {
        "_id": "597193eaa32cb73021e37420",
        "name": "Support"
      },
      "totalMessages": "3",
      "firstMessage": "Hello",
      "hasTranslatedText": false,
      "integrationLogs": [],
      "tags": [
        "63970836c73762460361b475",
        "63970836d086dd461040f1d0"
      ],
      "messages": [
        {
          "type": "VisitorSessionBegan",
          "timestamp": "2017-07-27T10:17:59.000Z"
        },
        {
          "messageId": 1,
          "messageId_v2": "5f0586b0285db15efaf845f0",
          "type": "VisitorMessage",
          "author": {
              "id_v2": "5ebe50602aa6b25addf08278f",
              "name": "Viktor"
          },
          "text": "Hello",
          "timestamp": "2017-07-27T10:18:01.000Z",
          "subType": ""
        },
        {
          "type": "AgentJoined",
          "author": {
              "id_v2": "5ebe50602aa6b25addf08278f",
              "name": "Sam Mendis"
          },
          "timestamp": "2017-07-27T10:18:05.000Z"
        },
        {
          "messageId": 2,
          "messageId_v2": "5f0586b0285db15efaf845f0",
          "type": "AgentMessage",
          "author": {
              "id_v2": "5ebe50602aa6b25addf08278f",
              "name": "Sam Mendis"
          },
          "text": "Good Morning, How may I help you?",
          "timestamp": "2017-07-27T10:18:09.000Z",
          "subType": ""
        },
        {
          "messageId": 3,
          "messageId_v2": "5f0586b0285db15efaf845f0",
          "type": "VisitorMessage",
          "author": {
              "id_v2": "5ebe50602aa6b25addf08278f",
              "name": "Viktor"
          },
          "text": "Will there be a Black Friday sale",
          "timestamp": "2017-07-27T10:18:15.000Z",
          "subType": ""
        },
        {
          "type": "VisitorBecameInactive",
          "endEvent": "VisitorEndedTheConversation",
          "timestamp": "2017-07-27T10:18:20.000Z"
        }
      ],
      "stats": {
        "waitingTime": 8,
        "averageResponseTime": 8,
        "totalChatDuration": 14
      },
      "departments": [
        {
          "_id": "597193eca32cb73021e37421",
          "name": "Default"
        }
      ],
      "agents": [
        {
          "agentChatId_v2": "5ebe50602aa6b25addf08278f",
          "name": "Sam Mendis",
          "_id": "5979bdee49eca059dae452cd"
        }
      ],
      "isMissed": false,
      "isTriggeredChat": true,
      "isProactiveChat": false,
      "agent_names": "Sam Mendis",
      "id": "5979bdee49eca059dae452cc"
    }
}

The webhook URL would receive a POST request with type as transcript whenever a chat is ended & transcript is created under the profile.

Transcript Property Type Description
_id String ID of the given transcript.
agents Array[Object] Agents associated with the Chat.
departments Array[Object] Departments associated with the Chat.
visitor Object Details of the visitor associated with the Chat.
stats Object Stats pertaining to the visitor associated with the Chat.
createdAt String Date when Transcript created.
updatedAt String Date when Transcript updated.
timestamp String Timestamp of the first user-message.
messages Array[Object] All messages under the transcript.
firstMessage String First user-message in the Transcript.
totalMessages String Total number of user-messages in the Transcript.
tags Array[String] IDs of tags that are assigned to the Transcript.
customFields Object Custom Field values set via the JavaScript API.
profile Object Profile of the widget in which the Chat took place.
hasTranslatedText Boolean Boolean indicating whether or not the chat contains Live Translated content.
sourceLangCode String Actual language the Chat took place in.
targetLangCode String The Language to which the Chat was translated to.
isMissed Boolean Boolean indicating whether or not the chat is a Missed Chat.
isTriggeredChat Boolean Boolean indicating whether or not the chat is a Triggered Chat.
isProactiveChat Boolean Boolean indicating whether or not the chat is a Proactive Chat.

Offline message posted event payload

The JSON structure of the request body when posting offline message to a webhook URL is:

{
  "type": "offline_message",
  "payload": {
    "_id": "59788ac89051246e91e1c7af",
    "profileId": "597193eaa32cb73021e37420",
    "message": "Hi, please get back to me.",
    "createdAt": "2017-10-27T06:04:48.073Z",
    "chatFromUrl": "https://happyfoxchat.com/chat/2c768310-6dd7-11e7-ae75-a9ecadeb7ee6",
    "name": "Xavier Brown",
    "email": "[email protected]",
    "department": "597193eca32cb73021e37421",
    "tags": [
      "63970836c73762460361b475",
      "63970836d086dd461040f1d0"
    ],
    "events": []
  }
}

The webhook URL receives a POST request with type offline_message whenever an offline message is created under the profile.

Offline Message Property Type Description
_id String ID of the given Offline Message.
name String Name of the Visitor.
phoneNumber String Phone Number of the Visitor.
email String e-mail of the Visitor.
message String Message from the Visitor.
department String Department the Visitor intended to contact.
profileId String ID of the profile of widget, via which the Visitor left a message.
createdAt String Date when Offline Message was created.
updatedAt String Date when Offline Message last updated.
tags Array[String] IDs of tags that are assigned to the Offline Message.
events Array[Object] Events associated with the Offline Message.
chatFromUrl String URL of the page, from where the Visitor left the message.
customFields Object Custom Field values, if set via the JavaScript API.

Signature Verification

Sample code (in NodeJS) to demonstrate signature verification using secret key:


function computeSignature (secretKey, reqBody) {
  return crypto.createHmac('sha256', secretKey).update(JSON.stringify(reqBody)).digest('hex').toString()
}

function validateSignature (secretKey) {
  return headers['X-HFC-SIGNATURE'] ===  computeSignature(secretKey, reqBody)
}

// check if this computed signature is same as the value of the header x-hfc-signature,
// else ignore the POST request

All webhook requests will have X-HFC-SIGNATURE header.

Header Value
X-HFC-SIGNATURE HMAC-SHA256 encrypted hash

When a webhook url is registered for a profile, a secret key is generated and will be displayed right below the webhook url. Secret Key is an security measure which allows you to verify the authenticity of the request and validate if the POST request is sent from HappyFox Chat only. You must copy this secret key and keep it safe.

While sending webhook requests to the configured URL, we compute a signature by hashing entire JSON request body using HMAC SHA-256 algorithm & the secret key and place the hash string in X-HFC-SIGNATURE header.

To verify this signature at your end, you have to create a signature out of full JSON request body that you received, HMAC SHA-256 algorithm and the secret key. If the signature you computed is same as the one X-HFC-SIGNATURE request header, then the request is said to be authentic. We highly recommend you to verify/validate the signature before processing the webhook request.

Properties required for verifying the hmac signature:

Webhook retries

Occasionally your webhook URL might be down or unavailable. Until your webhook URL sends us a success HTTP response with 2XX status code, we will keep retrying to post that webhook every 10 minutes. After 3 failed attempts we will stop retrying for that particular transcript/offline message event.