Chat

Fetch all data related to ImBox Chat

listConversations

Lists all conversations within a given timespan.

Parameters

Name	Type	Description
apiKey*	String	Your API Key
userId*	String	Your userId
fromDate*	String	Format: YYYY-MM-DD
toDate*	String	Format: YYYY-MM-DD
pageFilterId	Array<String>	Page filters

Usage

curl -X GET "https://apiv2.imbox.io/message/listConversations/apiKey/userId/fromDate/toDate?pageFilterId=1&pageFilterId=2"

Response

{
  "result": "success",
  "json": [
    {
      "sid": 1, // userId
      "conversationID": "V1", // Channel / ConversationId
      "date": "2020-01-01T00:00:00.000Z" // Created date
    },
    {
      "sid": 1,
      "conversationID": "V18751500044654323221",
      "date": "2020-01-01T00:00:00.000Z"
    }
  ],
  "length": 2
}

grabConversation

Get a conversation by conversation id.

Parameters

Name	Type	Description
apiKey*	String	Your API Key
userId*	String	Your userId
conversationId*	String	You can get the conversationId from listConversations

Usage

curl -X GET "https://apiv2.imbox.io/message/grabConversation/apiKey/userId/conversationID"

Response

{
  "result": "success",
  "json": [
    {
      "id": 1, // messageId
      "sid": 1,
      "conversationID": "V1",
      "from": "John", // Name of sender
      "message": "Hello",
      "date": "2020-01-01T00:00:00.000Z",
      "agentID": 1 // agentId of sender, will be 0 if from Visitor and null if from system
    },
    {
      "id": 2,
      "sid": 1,
      "conversationID": "V1",
      "from": "John",
      "message": "how can i help you today? :)",
      "date": "2020-01-01T00:00:00.000Z",
      "agentID": 1
    },
    {
      "id": 702005,
      "sid": 1,
      "conversationID": "V1",
      "from": "V1",
      "message": "Hi, where can i find the documentation page?",
      "date": "2020-01-01T00:00:00.000Z",
      "agentID": 0
    },
    {
      "id": 702004,
      "sid": 1,
      "conversationID": "V1",
      "from": "system",
      "message": "{\"type\":\"visitorJoin\",\"currentPage\":\"https://example.org/support\"}",
      "date": "2020-01-01T00:00:00.000Z",
      "agentID": null
    }
  ],
  "length": 4
}

grabVisitorInfo

Get information about a visitor.

Parameters

Name	Type	Description
apiKey*	String	Your API Key
userId*	String	Your userId
conversationId*	String	You can get the conversationId from listConversations

Usage

curl -X GET "https://apiv2.imbox.io/message/grabVisitorInfo/apiKey/userId/conversationID"

Response

{
  "result": "success",
  "json": [
    {
      "trafficType": "Direct", // Direct|Organic|www.referral-domain.com
      "se_type": "", // If organic traffic: Google|Bing|Yahoo|etc
      "sid": 1,
      "conversationID": "V1",
      "last_visit": "2020-01-01T00:00:00.000Z",
      "browser": "Chrome 50.0.0",
      "os": "Windows 7 0.0.0",
      "user_city": "Stockholm",
      "user_country": "Sweden",
      "exitPage": "https://imbox.se/"
    }
  ]
}

grabVisitorTags

Get the tags set on a visitor conversation.

Parameters

Name	Type	Description
apiKey*	String	Your API Key
userId*	String	Your userId
conversationId*	String	You can get the conversationId from listConversations

Usage

curl -X GET "https://apiv2.imbox.io/message/grabVisitorTags/apiKey/userId/conversationID"

Response

{
  "result": "success",
  "json": [
    {
      "sid": 1,
      "conversationID": "V1",
      "createdDate": "2020-01-01T00:00:00.000Z",
      "tag": "John Doe",
      "type": 0 // Type 0 is the visitors name, can be set in client or via changeName widget api.
    },
    {
      "sid": 1,
      "conversationID": "V1",
      "createdDate": "2020-01-01T00:00:00.000Z",
      "tag": "Custom tag",
      "type": 1 // Regular tag set on visitor
    }
  ],
  "length": 2
}

grabVisitorLabels

Get labels set on a visitor conversation.

Parameters

Name	Type	Description
apiKey*	String	Your API Key
userId*	String	Your userId
conversationId*	String	You can get the conversationId from listConversations

Usage

curl -X GET "https://apiv2.imbox.io/message/grabVisitorLabels/apiKey/userId/conversationID"

Response

{
  "result": "success",
  "json": [
    {
      "conversationID": "V1",
      "createdDate": "2020-01-01T00:00:00.000Z",
      "label": "Support"
    },
    {
      "conversationID": "V1",
      "createdDate": "2020-00-00T00:00:00.000Z",
      "label": "BankId Verified"
    }
  ]
}

grabVisitorCards

Get data set by insertCard widget api.

Read more here: insertCard

Parameters

Name	Type	Description
apiKey*	String	Your API Key
userId*	String	Your userId
conversationId*	String	You can get the conversationId from listConversations

Usage

curl -X GET "https://apiv2.imbox.io/message/grabVisitorCards/apiKey/userId/conversationID"

Response

{
  "result": "success",
  "json": [
    {
      "dataID": "1", // Id inserted with insertCard
      "data": "Name: John Doe", // Data inserted with insertCard
      "sid": 1, // userId
      "conversationID": "V1",
      "createdDate": "2020-01-01T00:00:00.000Z",
      "updatedDate": "2020-01-01T00:00:00.000Z"
    }
  ]
}

grabAgent

Get an agent.

Parameters

Name	Type	Description
apiKey*	String	Your API Key
userId*	String	Your userId
agentId*	String	AgentId

Usage

curl -X GET "https://apiv2.imbox.io/message/grabAgent/apiKey/userId/agentId"

Response

{
  "result": "success",
  "json": [
    {
      "agentID": 1,
      "sid": 1, // userId
      "agentName": "John",
      "agentEmail": "john.doe@example.org",
      "agentPicture": "https://example.org/avatar.png",
      "agentLastActive": "2020-01-01T00:00:00.000Z",
      "department": "Support",
      "isBackOffice": "0", // 0 or 1
      "groups": "Sales,Support"
    }
  ]
}

grabAgents

Lists all agents.

Parameters

Name	Type	Description
apiKey*	String	Your API Key
userId*	String	Your userId

Usage

curl -X GET "https://apiv2.imbox.io/message/grabAgents/apiKey/userId"

Response

{
  "result": "success",
  "json": [
    {
      "agentID": 1,
      "sid": 1,
      "agentName": "John Doe",
      "agentEmail": "john.doe@example.org",
      "agentPicture": "https://example.org/avatar.png",
      "agentLastActive": "2020-01-01T00:00:00.000Z",
      "department": "Support",
      "isBackOffice": "0",
      "groups": "Sales,Support"
    },
    {
      "agentID": 2,
      "sid": 1,
      "agentName": "Jane Doe",
      "agentEmail": "jane.doe@example.org",
      "agentPicture": "https://example.org/avatar.png",
      "agentLastActive": "2020-01-01T00:00:00.000Z",
      "department": "Marketing",
      "isBackOffice": "1",
      "groups": "Marketing"
    }
  ],
  "length": 2
}

chatStatistics

Get chat statistics within a given timespan (Maximum 365 days per request).

Parameters

Name	Type	Description
apiKey*	String	Your API Key
userId*	String	Your userId
startTime*	String	Format: 2020-01-01T00:00:00.000Z
endTime	String	Format: 2020-01-01T00:00:00.000Z – Default: Current timestamp
agentId	String	AgentId
agentIds	Array<String>	Filter by multiple ids
channel	String	Conversation id / Channel
channels	Array<String>	Filter by multiple conversations
fileType	String	”csv”|”json” Default: ”json”
timezone	String	Your userId
pageFilterId	Array<String>	Filter using page filters ids

Usage

curl -X GET "https://apiv2.imbox.io/message/chatStatistics/apiKey/userId?startTime=2020-01-01T00%3A00%3A00.000Z&endTime=2020-01-01T00%3A00%3A00.000Z&agentIds=1&agentIds=2&channel=V1"

Response

{
    "result": "success",
    "json": [{
        "channel": "V1",
        "agentName": "John Doe",
        "agentEmail": "john.doe@example.org",
        "referral": "Direct",
        "searchEngine": "",
        "exitPage": "https://example.org/",
        "browser": "Chrome 50.0.0",
        "os": "OS X",
        "city": "Stockholm",
        "country": "Sweden",
        "labels": ["label1", "label2"],
        "tags": ["tag1", "tag2"],
        "duration": 100000, // Chat duration in MS
        "rating": 4,
        "responseTime": 5000, // Agent response time in MS
        "startedAt": "2020-01-01T00:00:00.000Z"
    }, {
        "channel": "V1",
        "agentName": "John Doe",
        "agentEmail": "john.doe@example.org",
        "referral": "Direct",
        "searchEngine": "",
        "exitPage": "https://example.org/",
        "browser": "Chrome 50.0.0",
        "os": "OS X",
        "city": "Stockholm",
        "country": "Sweden",,
        "labels": [],
        "tags": [],
        "startedAt": "2020-01-01T00:00:00.000Z",
        "duration": null, // No answer from agent
        "rating": null,
        "responseTime": null // No answer from agent
    }],
    "length": 2
}

pageFilters

List all pageFilters.

Parameters

Name	Type	Description
apiKey*	String	Your API Key
userId*	String	Your userId

Usage

curl -X GET "https://apiv2.imbox.io/message/pageFilters/apiKey/userId"

Response

{
  "result": "success",
  "json": [
    {
      "id": 1,
      "sid": 1,
      "searchFilter": "searchFilter",
      "searchName": "searchName",
      "matchType": "like"
    }
  ],
  "length": 1
}