Rest API Documentation

Rest APIs

A REST API defines a set of functions which developers can perform requests and receive responses via HTTP protocol such as GET and POST.

Chat List

URL: https://salesiq.zoho.com/api/v1/<screenname>/chats

Example

https://salesiq.zoho.com/api/v1/zylker/chats?limit=15&fromtime=1459171743914&totime=1458795665587 

Success Response

{
  "data": [
    {
      "department_id": "4489000000002013",
      "chatinitiated_time": "1459171743914",
      "attender_name": "Patricia",
      "attender_email": "patricia@zylker.com",
      "attender_id": "4489000000002001",
      "country_code": "US",
      "participants": [
        "5000000000007"
      ],
      "embed_id": "4489000000002043",
       "supervisor":[
         "5000000000005"
      ],
      "chat_duration": "120000",
      "end_time": "1459171979283",
      "chat_id": "282",
      "visitor_ip": "192.168.141.236",
      "visitor_email": "tom@zylker.com",
      "visitor_name": "Tom",
      "question": "Running a test chat !",
      "department_name": "sales",
      "embed_name": "zylker",
      "pickup_time": "1459171840646",
      "waited_duration": "25000",
      "chat_title" : "Zylker"
    },
{
      "missed_time":"1458795725587",
      "visitor_phoneno": "1-541-754-3010",
      "customer_info": {
        "Expiry": "Jan 20, 2016",
        "Band": "Premium"
      },
      "crm_info":"Lead",
      "department_id": "4489000000002013",
      "chatinitiated_time": "1458795665587",
      "country_code": "US",
      "embed_id": "4489000000127003",
      "end_time": "1458795665587",
      "chat_id": "277",
      "visitor_ip": "192.168.141.236",
      "visitor_email": "tom@zylker.com",
      "visitor_name": "Tom",
      "description" : "Info about the list of chats in your departments",
      "question": "Running a test chat",
      "department_name": "sales",
      "embed_name": "zylker",
      "waited_duration": "60000"
    }
  ]
}

Error Codes - General Error

Internal Server error while retrieving the chat list
 code : 2010
 Error Message : "Unable to retrieve Chat list"
 

Error Response - Example

{
 "error" :
  {
           "message":"Unable to retrieve Chat list",
           "code":2010
    }
}
 

Description

You can use this API to get the complete list of chats and the info available about the chat in your department.

Response Format

JSON

HTTP Method

GET

Query Parameters

*limit : The Number of chats you would like to get (The default limit is 50.)

*fromtime : The Chats after the specified time will be retreived and displayed.

*totime : The Chats before the specified time will be retreived and displayed.

Pre-requisite

A valid OAuth Token is mandatory.

Click to view the list of Sample Response Params

Chat Info

https://salesiq.zoho.com/api/v1/<screenname>/chats/<chat_id>

Example

https://salesiq.zoho.com/api/v1/zylker/chats/150

Success Response

{
"data": {
      "department_id": "4489000000002013",
      "chatinitiated_time": "1459171743914",
      "attender_name": "Patricia",
      "attender_email": "patricia@zylker.com",
      "attender_id": "4489000000002001",
      "country_code": "US",
      "participants": [
        "5000000000007"
      ],
      "embed_id": "4489000000002043",
       "supervisor":[
         "5000000000005"
     ],
      "chat_duration": "120000",
      "end_time": "1459171979283",
      "chat_id": "282",
      "visitor_ip": "192.168.141.236",
      "visitor_email": "tom@zylker.com",
      "visitor_name": "Tom",
      "question": "Running a test chat !",
      "department_name": "sales",
      "embed_name": "zylker",
      "pickup_time": "1459171840646",
      "waited_duration": "25000",
      "chat_title" : "Zylker"
    }
}

Error Codes

1. General Error

Internal server error while retrieving chat info.
 code : 2020
 Error Message : "Unable to retrieve Chat info for the given chat_id"
 

2. Invalid chat_id

This error is sent when the chat_id given is wrong.
 code : 2021
 Error Message : "Invalid chat_id"
 

3. Requested Non-Department Chat Info

This error is sent when the chat corresponding to the given chat_id does not belong to user's department 
 code : 2022
 Error Message : "This chat belongs to a department you do not belong to"
 

Error Response - Example

{
 "error" :{
  "message": "Invalid chat_id",
         "code": 2021
  }
}
 

Description

You can get information about a specific chat in your department by providing the chat_id.

chat_id - A Unique ID provided to each chat.

Response Format

JSON

HTTP Method

GET

Pre-requisite

A valid OAuth Token is mandatory.

Chat Transcript

URL: https://salesiq.zoho.com/api/v1/<screenname>/chats/<chat_id>/transcript

Example

1. https://salesiq.zoho.com/api/v1/zylker/chats/150/transcript
2. https://salesiq.zoho.com/api/v1/zylker/chats/150/transcript?limit=15&fromtime=1459171743914&totime=1458795665587

Success Response

{
"data": [ {
"chatinitiated_time": "1459751530696",
 "visitor_name": "Tom",
 "question": "Hi"
 }, {
 "sender": "5000000000005",
 "time": "1459751548932",
 "dname": "Patricia",
 "msg": "Hello!"
 }, {
 "sender": "5000000000005",
 "time": "1459751549695",
 "dname": "Patricia",
 "msg": "How may i help you ?"
 }, {
 "time": "1459751550483",
 "dname": "Tom",
 "msg": "For how many days do you provide free subscription?"
 }, {
 "time": "1459751551267",
 "dname": "Tom",
 "msg": "Thankyou"
 } ]
}

Error Codes

1. General Error

This error is sent in case of internal server error while retrieving chat transcript.
 code : 2030
 Error Message : "Unable to retrieve chat transcript for the given chat_id	"
 

2. Invalid chat_id

This error is sent when the chat_id given is wrong.
 code : 2031
 Error Message : "Invalid chat_id"
 

3. Requested transcript for missed chat

This error is sent when the given chat_id corresponds to a missed chat.
 code : 2032
 Error Message : "No Chat Transcript Available : Missed Chat"
 

4. Requested Non-Department Chat Transcript

This error is sent when the chat corresponding to the given chat_id  does not belong to user's department.
 code : 2033
 Error Message : "This chat belongs to a department you do not belong to"
 

Error Response - Example

{
 "error" :
  {
         "message":"Invalid chat_id",
         "code":2031
  }
}
 

Description

You can get the transcript of a specific chat in your departments by providing the chat_id.

chat_id - A Unique ID provided to each chat.

Response Format

JSON

HTTP Method

GET

Query Parameters

*limit : The Number of chat message you would like to get (The default limit is 50.)

*fromtime : The Chat message after the specified time will be retreived and displayed.

*totime : The Chat message before the specified time will be retreived and displayed.

Pre-requisite

A valid OAuth Token is mandatory.

Click to view the list of Sample Response Params

Attachments

URL: https://salesiq.zoho.com/api/v1/<screenname>/chats/<chat_id>/<attachmenturl>

Example

https://salesiq.zoho.com/api/v1/zylker/chats/150/attachments/2285371691914775377/A_1461735476414

Success Response

The "data" param in the success response contains the keys present in the above table. The "download_url" value obtained is the temporary URL(unique for the attachment) which can be used for getting the file within 5 minutes of obtaining the response.

{
 "data": {
"content-length": 157932,
  "download_url": "https://salesiq.zoho.com/pubdownload/d66ad355-ee23-4b3c-9e5f-d80bb112a7fa"
  }
 }
 

Error Codes

1. General Error

This error is sent in case of internal server error while getting the temporary URL for the attachment.
 code : 2040
 Error Message : "Unable to retrieve the attachment"
 

2. Invalid chat_id

This error is sent when the chat_id given is wrong.
 code : 2041
 Error Message : "Invalid chat_id"
 

3. Attachments_empty

This error is sent when there are no attachments available for the given chat id.
 code : 2042
 Error Message : "No Attachments available for this chat"
 

4. Requested Invalid file

This error is sent when there is no attachment found for the given attachment URL.
 code : 2043
 Error Message : "File Not Found"
 

5. Requested Non-Department Chat Transcript

 This error is sent when the attachment requested does not belong to user's department.

 code : 2044
 Error Message : "This chat containing the attachment belongs to a department you do not belong to"
 

Error Response - Example

{
 "error" :
  {
          "message": "No Attachments available for this chat ",
          "code": 2042
  }
}
 

Description

To download a file attachment given the attachment url. The attachment url can be found in the chat transcript.

chat_id - A Unique ID is provided to each visitor on your website.

Sample transcript that contains an attachment

{
         "time":"1461321097487",
         "dname":"Djayakumar",
         "msg":{
            "dim":{ "height":"1280.0", "width":"720.0"},
            "content":"image\/png",
            "fileId":"A_1461321096778",
            "url":"/attachments/2285371690226238428/A_1461321096778",
            "fName":"2016-04-14-22-04-25.png",
            "size":"108388"
         },
         "mode":"att"
}

Response Format

JSON

HTTP Method

GET

Pre-requisite

A valid OAuth Token is mandatory.

Click to view the list of Sample Response Params

Visitor Details

https://salesiq.zoho.com/api/v1/<screenname>/visitorsview/<viewid>/visitors

Example

https://salesiq.zoho.com/api/v1/zylker/visitorsview/51841000001757005/visitors?startkey=3598-101

Success Response

{
{
 "data": 
 {
   "startkey": "3649-101",
   "visitorlist": [
    {
       "lastvisit_source": "Direct",
        "user_uniqueid": "d5fad88e-6b6c-43fd-bb88-3b0dd0eac868",
        "name": "John",
        "lastcontacted_mode": "Email",
        "id": "1310",
        "email": "John@zylker.com",
        "total_timespent": "1271421723",
        "lastvisit_time": "1487091571723",
        "customer_info" : {"band" : "premium", "plan" : "enterprise"},
        "leadscore" : "19056"   
      },
     {
        "country": "United Kingdom",
        "lastvisit_source": "Referrals",
        "user_uniqueid": "85a809b2-1ad7-4f69-8b2b-989f8d80a5e0",
        "lastcontacted_mode": "Email",
       "name": "Patricia",
       "id": "1761",
        "lastvisit_time": "1474478082951",
        "total_timespent": "467714508",
        "email": "Patricia@zylker.com"
      }
] }} 

Error Codes

1. General Error

Internal server error while fetching visitors list.
 code : 2210
 Error Message : "Unable to fetch Visitors List"
 

2. No Visitor Error

This error occur when the given viewid has no visitor.
 code : 2211
 Error Message : "No Visitor Found"
 

3. Invalid ViewID error

This error occur when the ViewID is invalid. 
 code : 2212
 Error Message : "Invalid Viewid"
 

Error Response - Example

{
 "error" :{
  "message": " Invalid Viewid",
         "code": 2212
  }
}
 

Description

You can use this API to get the visitors and their details for the given ViewID.

What is a ViewID?

In the Visitor History Tab of SalesIQ, you can create a view to filter the type of visitors based on the condition and criteria. The ID given to each view is known as ViewID.

Default Views and their viewIDs

Response Format

JSON

HTTP Method

GET

Query Parameters

startkey : The maximum number of visitors that can be present in a response JSON is 100. When the given view contains more visitors in the database, the response will contain a key named "startkey". This startkey should be given as a param in the next request, so as to get the next list of 100 visitors

Pre-requisite

A valid OAuth Token is mandatory.

Click to view the list of Sample Response Params

Update Visitor Info

URL: https://salesiq.zoho.com/api/v1/<screenname>/visitorsbyemail/<email>

Example

https://salesiq.zoho.com/api/v1/zylker/visitorsbyemail/patricia@zylker.com?customerinfo={"band":"premium", "nextpayment" :"June 20,2017"}

Success Response

{
 data : "patricia@zylker.com"
 }
 

Error Codes

1. General Error

This error is sent when you are not able to update the visitor info.
 code :  2310
 Error Message : "Unable to update customer info"
 

2. No Visitor Found

This error is sent if there are no visitors found for the given Email ID.
 code : 2311
 Error Message : "No Visitor found "
 

Error Response - Example

{
 "error" :
  {
          "message": "No Visitor found",
          "code": 2311
  }
}
 

Description

This API is used to update the custom visitor information for a particular visitor. The object given in the param will be appended to the existing visitor information.

Response Format

JSON

HTTP Method

POST

Query Parameters

customer info : A JSON object containing the visitor information.

Pre-requisite

A valid OAuth Token is mandatory.

Push Notification

URL: https://salesiq.zoho.com/api/v1/<screenname>/pushnotification

Example

https://salesiq.zoho.com/api/v1/zylker/pushnotification?email=patricia@zylker.com&message=hello&title=Zylker&badgecount=10&bundleids=com.zylker.test&addinfo={"imgpath":"https://upload.wikimedia.org/wikipedia/commons/thumb/5/5c/Chat_bubbles.svg/2000px-Chat_bubbles.svg.png"} 

Success Response

{
 data : "patricia@zylker.com"
 }
 

Error Codes

1. General Error

This error is displayed when the push notification is not sent.
 code :  2111
 Error Message : "Unable to send push notification"
 

2. Visitor not found for the email

This error is sent if there are no visitors found for the given Email ID.
 code :  2112
 Error Message : "No Visitor found for the given emailid"
 

3. Visitor not found for the bundleid:

This error is sent if there are no visitors found for the given bundle ID.
 code :  2113
 Error Message : " No Visitor found for the given bundleid"
 

4. Device not Registered

This error is sent if there are no visitors found for the given Email ID.
 code : 2114
 Error Message : "No Device Registered for the Visitor"
 

5. Push Notifications disabled in Configuration :

This error is sent when the Push Notification Settings for the app in SalesIQ is disabled .
 code : 2311
 Error Message : "Push Notification Settings for the app in SalesIQ is disabled "
 

Error Response - Example

{
 "error" :
  {
          "message": "No Visitor found for the given emailid",
          "code": 2112
  }
}
 

Description

This API is used to send PushNotification to the users who have given their email ID. The App which uses the SalesIQ SDK can route their app specific Notificaitons through SalesIQ server. That is, the info about the users of the App will be present in SalesIQ and hence the application developer can send a notification to the App users using this REST API.

Response Format

JSON

HTTP Method

POST

Query Parameters

You can call this API for two reasons:

  1. To Send Push Notifications :
    • email - Email ID corresponding to the visitor to whom PushNotification is to be sent (This email ID should be notified when user is connected to SDK in the app, using setEmail API)
    • title - Title for the PushNotification
    • message - Message to be shown in Push Notification
    • badgecount - The badgecount that has to be set for the App ( This will be added with the existing message count of SDK)
    • bundleids - Bundeids of the app for which notification needs to be sent (comma separated list)
    • addinfo - This JSON can contain any information in the form of key value pairs. if a image has to be shown in the pushnotification , the URL of the image can be given in the key "imgpath"

    Note:

    All the above params except "addinfo" are mandatory for sending a Push Notification.

  2. To clear the badgecount:
    • email - Email ID corresponding to the visitor
    • badgecount - This param should be set as 0 for resetting badgecount
    • bundleids - Bundeids of the app for which badgecount has to be cleared (comma separated list)

Pre-requisite