Webhooks - Zoho SalesIQ

Webhooks

What are Webhooks?

Webhooks operate on the concept of “event reaction” and thus avoids the need for constant polling of the server-side application by the client-side application. Therefore, rather than the client-side application constantly polling the server-side application to check for new events, the server-side application calls the client-side application (by invoking a client provided webhook URL) anytime the server-side has something new to report to the client. This is the core concept of the webhook. 

Benefits:

  1. With webhooks, you can get push notifications when certain events happen on the server. You do not need to poll the API anymore to observe if these events have occurred. You can just ‘subscribe’ to an event with webhooks. 
  2. Webhooks are powerful resources that you can use to automate your use cases and improve your productivity. Unlike the API resources, which represent static data that you can create, update and retrieve as needed, webhooks represent dynamic resources. You can configure them to automatically notify you when a customer has taken a particular action, such as initiating or replying to a conversation.

Creating and Managing Webhooks

You can create and manage the webhooks with the REST API available  here . 

Trusted source validation (via signature):

What is a public key and how to generate it via API?
SalesIQ signs every webhook event passed on to the endpoint URL using RSA Cryptosystem.
  1. We use SHA256 with RSA as the signature algorithm.
  2. The signature is Base64 encoded
  3. The charset used is UTF-8
The generated Public key can be copied and saved in the endpoint server, which can later be used to check the authenticity of the data received with the signature attached. We will generate a public and a private key pair.
To  generate the public key  use the following API:
  1. API: /api/v2/{screenname}/webhooks/{id}/keys
  2. METHOD : POST
  3. Scope: SalesIQ.webhooks.CREATE
To  delete the public key  use the following API:
  1. API: /api/v2/{screenname}/webhooks/{id}/keys/{keyid}
  2. METHOD : DELETE
  3. Scope: SalesIQ.webhooks.DELETE 
The trusted source validation is to secure the Webhooks, i.e., for you (integration services) to verify the data sent is from SalesIQ services by getting the public key in the API response and validating the signature available in the x-siqsignature request headers for that data. If the signature is valid, then the source can be trusted. This process is to secure the Webhooks from unauthorized access.

To validate the source with the help of signature header:
  1. HEADERS : 
  2. {
  3. x-siqsignature : $signature 
  4. }
If you wish to set up a secure callback, then create the webhook and set the secure as true ("secured:true".)
  1. Payload: 
  2. {
  3. webhook : {
  4. url : $webhookurl,
  5. secured : <boolean>},
  6. published : <boolean>
  7. } 
Note:
  1. Maximum Admin webhooks allowed per portal is 3
  2. Maximum auto retry count for a webhook is 3
  3. Auto retry occur after a minute
  4. Timeout per execution is 5 seconds
  5. Default error log retention period is 60 days
  6. Webhooks are available only in the Enterprise plan

Webhook Payload

The webhook is invoked when the event you've subscribed occur in SalesIQ. For example, if you have subscribed for conversation.visitor.replied then when a visitor replies to the chat then you'll be notified with some data. 

Payload definition:

  1. version - The version of the webhook payload.
  2. event - The event notified.
  3. event_time - The time at which the event happened
  4. org_id - Your SalesIQ portal ID
  5. app_id - Your embed ID, available only for data events
  6. attempt - The number of attempts made to notify an event through webhook
  7. entity - The entity of the event occurred
  8. entity_type - The type of the entity (ex: Bot, department, operator)
  9. entity_id - Unique id of the entity. For ex, conversation id in case of conversation.* events
  10. modified_fields - List of properties modified
The payload should be received in the below format.
  1. {
  2. "version" : "1",
  3. "event" : "operator.created",
  4. "event_time" : $time of event,
  5. "org_id" : $soid,
  6. "app_id" : $appid,
  7. "attempt" : $count of retry,
  8. "entity_type" : $type of entity,
  9. "entity_id" : $ID,
  10. "entity" : {
  11. $ENTITY OBJECT
  12. },
  13. "modified_fields" : [ ]
  14. }
Example:
  1. {
  2. "entity_type":"conversation",
  3.  "org_id":"14327896",
  4.  "event":"conversation.operator.replied",
  5.  "entity_id":"8000000004009",
  6.  "attempt":1,
  7.  "version":"1",
  8. "app_id":8000000000047,
  9.  "entity":{
  10.       "id":"8000000004009",
  11.       "message":{
  12.       "sender":{
  13.       "name":"Tricia",
  14.       "id":"8000000000005"
  15. },
  16.  "msgid":"1566480708251",
  17.  "text":"Hello, I need some help with the shipping status"
  18. }
  19. },
  20.  "event_time":1566480708268
  21. }

Webhook Pre-requisites

  1. The "https" URL is recommended for security reasons. 
  2. Our server can not connect with the URL with the port number.
  3. Make sure the URL can be accessed in public API clients such as Postman and Talend API Tester to be accessible in our server.
  4. Once the URL is provided, it will be pinged to get validated with the read time out of 5 seconds. 
  5. If it is not reached within 5 seconds, an HTTP HEAD request gets triggered to the URL to check the status code 200.
  6. Ensure the webhook returns the response within 10 seconds. If not, the bot will not work. 

Cases where webhook will be disabled: 

Case 1: When the webhook returns HTTP code 400 and above which fails to return success acknowledgment continuously, the portal owner and webhook creator will receive a set of warnings via email. 
  1. The first warning mail will be triggered when the webhook fails continuously for 3 hours, and a second warning mail will be triggered when it fails for 6 hours. 
  2. The webhook will be disabled and a final mail will be triggered when the webhook fails for 12 hours continuously. 
Case 2: When the webhook returns HTTP code 410 while posting the registered events. The SalesIQ system will delete the webhook, and both the portal owner and webhook creator will receive an email.  
Note: If the webhook returns success response during this period, it works as usual. However, if it fails again, the above cycle will begin from the first.

Events:

With Webhooks, you can get notified when certain events happen on SalesIQ. If you have subscribed to the following list of events then you will be notified with the data when the respective event occur. 

Webhook Modules:

The following modules are available and you can be notified when an action relating to that module occurs. 
  1. Conversation : A conversation lets you track and describe communications with your website visitors. The conversation can have the visitor/operator messages, the operator involved, the admin/supervisor assigned to the conversation and other information related to the conversation.
  2. Department : The departments is an administration event, you can subscribe to the event and get notified when a new department is created, updated or deleted. There are two different types of event in the Webhooks: Data and administration. 

Conversation

A conversation lets you track and describe communications with your website visitors. The conversation can have the visitor/operator message, the operator involved, the admin/supervisor assigned to the conversation and other information related to the conversation.

List of conversation events:
  1. conversation.created
  2. conversation.attender.updated
  3. conversation.missed
  4. conversation.completed
  5. conversation.rated
  6. conversation.visitor.replied
  7. conversation.operator.replied

conversation.created

You can subscribe to this event if you wish to be notified when a visitor initiates a chat.

  2. Payload:
  3. {
  4.   "id": "17000000004021",
  5.   "visitor_conversation_id": "ad433hjdid546f8n4b734j4omfhjsrwnet46fklf7",
  6.   "reference_id": "1",
  7.   "opened_time": "1556866331533",
  8.   "attended_time": "1556866331553",
  9.   "end_time": "1556866331929",
  10.   "missed_time": "1556866333232",
  11.   "app_id": "30185567778889",
  12.   "department_id": "301050000004",
  13.   "owner": {
  14.     "id": "30102333033335",
  15.     "name": "Patricia",
  16.     "email_id": "patricia@zylker.com"
  17.   },
  18.   "visitor":{
  19.         "email_id":"tricia@zylker.com",
  20.         "phone":"1234354",
  21.         "name":"Tricia",
  22.         "channel":"website",
  23.         "type" : "contact",
  24.         "id": "30000000090034"
  25.   },
  26.   "question": "Hi, I need some assistance in buying a dining set.",
  27.   "supervisors": [
  28.     "30102333033336",
  29.     "30102333033337"
  30.   ],
  31.   "participants": [
  32.     "30102333033336",
  33.     "30102333033337"
  34.   ],
  35.   "status": "Live",
  36.   "chat_status": {
  37.     "status_code": [
  38.       "1,2"
  39.     ],
  40.     "state": [
  41.       "1,2,3,4"
  42.     ],
  43.     "label": "Live"
  44.   }
  45. }

conversation.attender.updated

You can subscribe to this event if you wish to be notified when operators pick up a chat.

  2. Payload:

  4. {
  5.   "id": "17000000004021",
  6.   "visitor_conversation_id": "ad433hjdid546f8n4b734j4omfhjsrwnet46fklf7",
  7.   "reference_id": "1",
  8.   "opened_time": "1556866331533",
  9.   "attended_time": "1556866331553",
  10.   "end_time": "1556866331929",
  11.   "missed_time": "1556866333232",
  12.   "app_id": "30185567778889",
  13.   "department_id": "301050000004",
  14.   "owner": {
  15.     "id": "30102333033335",
  16.     "name": "Patricia",
  17.     "email_id": "patricia@zylker.com"
  18.   },
  19.   "visitor":{
  20.         "email_id":"tricia@zylker.com",
  21.         "phone":"124534354",
  22.         "name":"Tricia",
  23.        "channel":"website",
  24.         "type" : "contact",
  25.         "id": "30000000090034"
  26.      }
  27.   },
  28.   "question": "Hi, I need some assistance in buying a dining set.",
  29.   "supervisors": [
  30.     "30102333033336",
  31.     "30102333033337"
  32.   ],
  33.   "participants": [
  34.     "30102333033336",
  35.     "30102333033337"
  36.   ],
  37.   "status": "Connected",
  38.   "chat_status": {
  39.     "status_code": [
  40.       "1,2"
  41.     ],
  42.     "state": [
  43.       "1,2,3,4"
  44.     ],
  45.     "label": "Attended Online"
  46.   }
  47. }

conversation.missed

You can subscribe to this event if you wish to be notified when a chat initiated by the visitor is not picked by any operator and missed.

  2. Payload:
  3. {
  4.   "id": "17000000004021",
  5.   "visitor_conversation_id": "ad433hjdid546f8n4b734j4omfhjsrwnet46fklf7",
  6.   "reference_id": "1",
  7.   "opened_time": "1556866331533",
  8.   "attended_time": "1556866331553",
  9.   "end_time": "1556866331929",
  10.   "missed_time": "1556866333232",
  11.   "app_id": "30185567778889",
  12.   "department_id": "301050000004",
  13.   "owner": {
  14.     "id": "30102333033335",
  15.     "name": "Patricia",
  16.     "email_id": "patricia@zylker.com"
  17.   },
  18.   "visitor":{
  19.         "email_id":"tricia@zylker.com",
  20.         "phone":"12344354",
  21.         "name":"Tricia",
  22.        "channel":"website",
  23.         "type" : "contact",
  24.         "id": "30000000090034"
  25.   },
  26.   "question": "Hi, I need some assistance in buying a dining set.",
  27.   "supervisors": [
  28.     "30102333033336",
  29.     "30102333033337"
  30.   ],
  31.   "participants": [
  32.     "30102333033336",
  33.     "30102333033337"
  34.   ],
  35.   "status": "Missed",
  36.   "chat_status": {
  37.     "status_code": [
  38.       "1,2"
  39.     ],
  40.     "state": [
  41.       "1,2,3,4"
  42.     ],
  43.     "label": "Tracked in CRM"
  44.   }
  45. }

conversation.operator.replied

You can subscribe to this event if you wish to be notified when an operator replies to the chat initiated by the visitor.

  1. Payload for text messages:
  2. {
  3. "id":"8000000004009",
  4. "message":{
  5. "sender":{
  6. "name":"Tricia",
  7. "id":"8000000000005"
  8. },
  9. "msgid":"1566480708251",
  10. "text":"Hi, I need some assistance in buying a dining set."
  11. },
  12. "visitor":{
  13. "email_id":"tricia@zylker.com",
  14. "phone":"12344354",
  15. "name":"Tricia",
  16. "type" : "contact",
  17. "id": "30000000090034"
  18. },
  19. "owner":{
  20. "id":"30102333033335",
  21. "name":"Patricia",
  22. "email_id":"patricia@zylker.com"
  23. },
  24. "version":1
  25. }

  27. Payload for file attachements:
  28. {
  29. "id":"8000000004009",
  30. "message":{
  31. "sender":{
  32. "name":"Tricia",
  33. "id":"8000000000005"
  34. },
  35. "msgid":"1566480708251",
  36.         "file":{
  37.         "dimensions":{
  38.          "height":700.0,
  39.           "width":525.0
  40.          },
  41.         "name":"pricing-details.jpg",
  42.         "comment":"Here is the pricing details."
  43.         "url":"/attachments/734343/A_16872571388888",
  44.         "id":"A_16872571388888",
  45.         "blur_image":"/9j/4AAQSkZJRgABAgAAAQABAAD/2wBDABwfijweifweijfiwjnefojnwiefowXRTc4UG1RV19iZ2hnPk1xeXBkeFxlZ2P/2wBDARESEhgVGC8aGi9jQjhCY2Nj",
  46.         "attachment_id":68564000016029999,
  47.         "type":"image/jpeg",
  48.         "extension":"image/jpeg",
  49.          "size":40078
  50.          }
  51. },
  52. "visitor":{
  53. "email_id":"tricia@zylker.com",
  54. "phone":"12344354",
  55. "name":"Tricia",
  56. "type" : "contact",
  57. "id": "30000000090034"
  58. },
  59. "owner":{
  60. "id":"30102333033335",
  61. "name":"Patricia",
  62. "email_id":"patricia@zylker.com"
  63. },
  64. "version":1
  65. }
  1. Bot conversation payload for text messages:
  2. {
  3. message : {
  4. "sender" : {
  5. "id" : $sender wms id,
  6. "name" : $sender name
  7. },
  8. "text" : $msg, // Absent for bot message
  9. "msgid" : $msg id, // Absent for bot message
  10. "meta" : $meta data, ---> applicable for bot message
  11. "list" : [
  12. $MESSAGE LIST
  13. ]

  15. }
  16. }

  18. Bot conversation payload for file attachements:
  19. message : {
  20.     "sender" : {
  21.     "id" : $sender wms id,
  22.     "name" : $sender name
  23.     },
  24.     "file":{
  25.         "dimensions":
  26.         {
  27.          "height":700.0,
  28.           "width":525.0
  29.         },
  30.         "name":"tricia-proof.jpg",
  31.         "comment":"Here is my ID for the verfication."
  32.         "url":"/attachments/734343/A_16872571311111",
  33.         "id":"A_16872571311111",
  34.         "blur_image":"/9j/4AAQSkZJRgABAgAAAQABAAD/2wBDwojrngovjwnrojngwojrnfvw9PDkzODdASFxOQERXRTc4UG1RV19iZ2hnPk1xeXBkeFxlZ2P/2wBDARESEhgVGC8aGi9jQjhCY2Nj",
  35.         "attachment_id":68564000016011111,
  36.         "type":"image/jpeg",
  37.         "extension":"image/jpeg",
  38.         "size":49078
  39.         }
  40.     "msgid" : $msg id,   // Absent for bot message
  41.     "meta" : $meta data, ---> applicable for bot message
  42.     "list" : [
  43.     $MESSAGE LIST
  44.              ]

  46.     }
  47. }

conversation.visitor.replied

You can subscribe to this event if you wish to be notified when a visitor replies.
  1. Payload for text messages:
  2. {
  3.   "id": "8000000005001",
  4.   "message": {
  5.     "sender": {
  6.       "name": "Tricia",
  7.       "id": "$2463902591169630574"
  8.     },
  9.     "msgid": "1566481170562",
  10.     "text": "Hi, i need some assistance in buying a dining set"
  11.   },
  12.   "owner": {
  13.     "id": "30102333033335",
  14.     "name": "Patricia",
  15.     "email_id": "patricia@zylker.com"
  16.   },
  17.   "visitor":{
  18.         "email_id":"tricia@zylker.com",
  19.         "phone":"1234354",
  20.         "name":"Tricia",
  21.         "type" : "contact",
  22.         "id": "30000000090034"
  23.   },
  24.   "version": 1
  25. }

  27. Payload for file attachments:
  28. {
  29.     "id": "8000000004009",
  30.     "message": {
  31.         "sender": {
  32.             "name": "Tricia",
  33.             "id": "8000000000005"
  34.         },
  35.         "msgid": "1566480708251",
  37.         "file":{
  38.         "dimensions":{
  39.          "height":700.0,
  40.           "width":525.0
  41.          },
  42.         "name":"tricia-proof.jpg",
  43.         "comment":"Here is my ID for the verfication."
  44.         "url":"/attachments/734343/A_16872571322222",
  45.         "id":"A_16872571322222",
  46.         "blur_image":"/9j/4AAQSkZJRgABAgAAAQABAAD/2wBDABALDA4MChAODQ4SERATGCgaGBYWGDEjJR0oOjM9PDkzODdASFxOQERXRTc4UG1RV19iZ2hnPk1xeXBkeFxlZ2P/2wBDARESEhgVGC8aGi9jQjhCY2Nj",
  47.         "attachment_id":68564000016021057,
  48.         "type":"image/jpeg",
  49.         "extension":"image/jpeg",
  50.          "size":49078
  51.          }
  52.     },
  53.     "visitor": {
  54.         "email_id": "tricia@zylker.com",
  55.         "phone": "12344354",
  56.         "name": "Tricia",
  57.         "type": "contact",
  58.         "id": "30000000090034"
  59.     },
  60.     "owner": {
  61.         "id": "30102333033335",
  62.         "name": "Patricia",
  63.         "email_id": "patricia@zylker.com"
  64.     },
  65.     "version": 1
  66. }

conversation.completed

You can subscribe to this event if you wish to be notified when a chat conversation ends.

  2. Payload:
  3. {
  4.   "id": "17000000004021",
  5.   "visitor_conversation_id": "ad433hjdid546f8n4b734j4omfhjsrwnet46fklf7",
  6.   "reference_id": "1",
  7.   "opened_time": "1556866331533",
  8.   "attended_time": "1556866331553",
  9.   "end_time": "1556866331929",
  10.   "missed_time": "1556866333232",
  11.   "app_id": "30185567778889",
  12.   "department_id": "301050000004",
  13.   "owner": {
  14.     "id": "30102333033335",
  15.     "name": "Patricia",
  16.     "email_id": "patricia@zylker.com"
  17.   },
  18.   "visitor":{
  19.      "email_id":"tricia@zylker.com",
  20.      "phone":"12344354",
  21.      "name":"Tricia",
  22.       "channel":"website",
  23.      "type" : "contact",
  24.      "id": "30000000090034"
  25.   },
  26.   "question": "Hi, I need some assistance in buying a dining set.",
  27.   "supervisors": [
  28.     "30102333033336",
  29.     "30102333033337"
  30.   ],
  31.   "participants": [
  32.     "30102333033336",
  33.     "30102333033337"
  34.   ],
  35.   "status": "Closed",
  36.   "chat_status": {
  37.     "status_code": [
  38.       "1,2"
  39.     ],
  40.     "state": [
  41.       "1,2,3,4"
  42.     ],
  43.     "label": "Attended by Email"
  44.   }
  45. }

conversation.rated

You can subscribe to this event if you wish to be notified when the visitor rate or provide feedback for the chat conversation they had with the operator.

  2. Payload for rating:
  3. {
  4.   "rating": 4,
  5.   "feedback": "Good support",
  6.   "owner": {
  7.     "id": "30102333033335",
  8.     "name": "Patricia",
  9.     "email_id": "patricia@zylker.com"
  10.   },
  11.   "visitor":{
  12.         "email_id":"tricia@zylker.com",
  13.         "phone":"12344354",
  14.         "name":"Tricia",
  15.        "channel":"website",
  16.         "type" : "contact",
  17.         "id": "30000000090034"
  18.   }
  19. }

  21. Payload for feedback:

  23. {
  24.   "entity_type": "conversation",
  25.   "org_id": "55778119",
  26.   "event": "conversation.rated",
  27.   "entity_id": "40526000001808033",
  28.   "attempt": 1,
  29.   "version": "1",
  30.   "app_id": 40526000000002040,
  31.   "entity": {
  32.     "owner": {
  33.       "name": "Patricia",
  34.       "email_id": "patricia@zylker.com"
  35.       "id": "40526000000002001"
  36.     },
  37.     "feedback": "Awesome support from the reps!",
  38.     "id": "40526000001808033",
  39.     "status": "Ended",
  40.     "visitor":{
  41.         "email_id":"tricia@zylker.com",
  42.         "phone":"12344354",
  43.         "name":"Tricia",
  44.         "type" : "contact",
  45.         "id": "30000000090034"
  46.        }
  47.   },
  48.   "event_time": "1567065865617"
  49. }

conversation.transfer.initiated

You can subscribe to this event if you wish to be notified when a conversation transfer is initiated.
Payload:
  1. {
  2.     "owner": {
  3.         "email_id": "patricia@zylker.com",
  4.         "name": "patricia@zylker.com",
  5.         "id": "30000000099007"
  6.     },
  7.     "transfer": {
  8.         "note": "More info required",
  9.         "type": "user|department",
  10.         "department_id": "30000000148001",
  11.         "transferred_by": {
  12.             "type": "bot|operator",
  13.             "email_id": "patricia@zylker.com",
  14.             "name": "patricia@zylker.com",
  15.             "id": "30000000099007"
  16.         },
  17.         "transferred_to": [
  18.             {
  19.                 "id": "30000000000006",
  20.                 "name": "Patricia",
  21.                 "email_id": "patricia@zylker.com"
  22.             }
  23.         ]
  24.     },
  25.     "waiting_time": "60",
  26.     "question": "Hi, I need some assistance in buying a dining set",
  27.     "department_id": "30000000000018",
  28.     "id": "30000000095001",
  29.     "visitor_conversation_id": "2d665c42a02e919ac0f91f62fa78581d",
  30.     "visitor": {
  31.         "email_id": "tricia@zylker.com",
  32.         "phone": "1234354",
  33.         "name": "Tricia",
  34.         "type": "contact",
  35.         "id": "30000000090034"
  36.     }

conversation.transfer.accepted

You can subscribe to this event if you wish to be notified when a transferred chat is accepted by the operator.
  1. Payload:
  2.  {
  3.     "accepted_by": {
  4.         "name": "Patricia",
  5.         "id": "30000000000006",
  6.         "email_id": "patricia@zylker.com"
  7.     },
  8.     "question": "Hi, i need some assistance in buying a dining set",
  9.     "department_id": "30000000000018",
  10.     "id": "30000000158001",
  11.     "visitor": {
  12.         "email_id": "tricia@zylker.com",
  13.         "phone": "1234354",
  14.         "name": "Tricia",
  15.         "type": "contact",
  16.         "id": "30000000090034"
  17.     },
  18.     "visitor_conversation_id": "2d665c42a02e919a171b7845509162e6"
  19. }

conversation.transfer.rejected

You can subscribe to this event if you wish to be notified when a transferred chat is rejected by the operator.
  1. Payload:
  2. {
  3.     "rejected_by": {
  4.         "type": "auto | manual",
  5.         "name": "Patricia",
  6.         "id": "30000000000006",
  7.         "email_id": "patricia@zylker.com"
  8.     },
  9.     "question": "Hi, i need some assistance in buying a dining set",
  10.     "department_id": "30000000000018",
  11.     "id": "30000000158001",
  12.     "visitor": {
  13.         "email_id": "tricia@zylker.com",
  14.         "phone": "1234354",
  15.         "name": "Tricia",
  16.         "type": "contact",
  17.         "id": "30000000090034"
  18.     },
  19.     "visitor_conversation_id": "2d665c42a02e919ac0f91f62fa78581d"
  20. }

conversation.participants.added

You can subscribe to this event if you wish to be notified when participants are invited to the chat.
  1. Payload:
  2. {
  3.     "question": "Hi, i need some assistance in buying a dining set",
  4.     "department_id": "30000000000018",
  5.     "id": "30000000095001",
  6.     "invite": {
  7.         "note": "asdfqsf",
  8.         "added_by": {
  9.             "name": "patricia@zylker.com",
  10.             "id": "30000000099007",
  11.             "email_id": "patricia@zylker.com"
  12.         },
  13.         "added_operators": [
  14.             {
  15.                 "name": "Patricia",
  16.                 "id": "30000000000006",
  17.                 "email_id": "patricia@zylker.com"
  18.             }
  19.         ]
  20.     },
  21.     "visitor_conversation_id": "2d665c42a02e919ac0f91f62fa78581d",
  22.     "visitor": {
  23.         "email_id": "tricia@zylker.com",
  24.         "phone": "1234354",
  25.         "name": "Tricia",
  26.         "type": "contact",
  27.         "id": "30000000090034"
  28.     },
  29.     "owner": {
  30.         "name": "Patricia",
  31.         "id": "30000000000006",
  32.         "email_id": "patricia@zylker.com"
  33.     }
  34. }

conversation.participants.deleted

You can subscribe to this event if you wish to be notified when a participant is removed from a conversation.
  1. Payload:
  2. {
  3.     "question": "Hi, i need some assistance in buying a dining set",
  4.     "department_id": "30000000000018",
  5.     "deleted_by": {
  6.         "name": "Patricia",
  7.         "id": "30000000000006",
  8.         "email_id": "patricia@zylker.com"
  9.     },
  10.     "deleted_operators": [
  11.         {
  12.             "name": "Patricia+1",
  13.             "id": "30000000000106",
  14.             "email_id": "patricia@zylker.com"
  15.         }
  16.     ],
  17.     "visitor": {
  18.         "email_id": "tricia@zylker.com",
  19.         "phone": "1234354",
  20.         "name": "Tricia",
  21.         "type": "contact",
  22.         "id": "30000000090034"
  23.     },
  24.     "owner": {
  25.         "name": "Patricia",
  26.         "id": "30000000000006",
  27.         "email_id": "patricia@zylker.com"
  28.     },
  29.     "id": "30000000095001",
  30.     "visitor_conversation_id": "2d665c42a02e919ac0f91f62fa78581d"
  31. }

conversation.supervisor.added

You can subscribe to this event if you wish to be notified when a supervisor is added to the chat.
  1. Payload:
  2. {
  3.     "added_operators": [
  4.         {
  5.             "name": "Patricia",
  6.             "id": "30000000000006",
  7.             "email_id": "patricia@zylker.com"
  8.         }
  9.     ],
  10.     "id": "30000000095001",
  11.     "question": "Hi, I need some assistance in buying a dining set",
  12.     "department_id": "30000000000018",
  13.     "visitor": {
  14.         "email_id": "tricia@zylker.com",
  15.         "phone": "1234354",
  16.         "name": "Tricia",
  17.         "type": "contact",
  18.         "id": "30000000090034"
  19.     },
  20.     "owner": {
  21.         "name": "Patricia+1",
  22.         "id": "30000000000106",
  23.         "email_id": "patricia@zylker.com"
  24.     },
  25.     "visitor_conversation_id": "2d665c42a02e919ac0f91f62fa78581d"
  26. }

conversation.message.edited

You can subscribe to this event if you wish to be notified when a message is edited in chat.
  1. Payload:
  2. {
  3.     "id": "8000000005001",
  4.     "message": {
  5.         "sender": {
  6.             "name": "Patricia",
  7.             "id": "30000000000006"
  8.         },
  9.         "msgid": "1566481170562",
  10.         "text": "abcc"
  11.     },
  12.     "visitor": {
  13.         "email_id": "tricia@zylker.com",
  14.         "phone": "1234354",
  15.         "name": "Tricia",
  16.         "type": "contact",
  17.         "id": "30000000090034"
  18.     },
  19.     "owner": {
  20.         "name": "Patricia+1",
  21.         "id": "30000000000106",
  22.         "email_id": "patricia@zylker.com"
  23.     },
  24.     "visitor_conversation_id": "2d665c42a02e919ac0f91f62fa78581d"
  25. }

conversation.message.deleted

You can subscribe to this event if you wish to be notified when a message is deleted in chat.
  1. Payload:
  2. {
  3.     "id": "8000000005001",
  4.     "message": {
  5.         "sender": {
  6.             "name": "Patricia",
  7.             "id": "30000000000006"
  8.         },
  9.         "msgid": "1566481170562"
  10.     },
  11.     "visitor": {
  12.         "email_id": "tricia@zylker.com",
  13.         "phone": "1234354",
  14.         "name": "Tricia",
  15.         "type": "contact",
  16.         "id": "30000000090034"
  17.     },
  18.     "owner": {
  19.         "name": "Patricia+1",
  20.         "id": "30000000000106",
  21.         "email_id": "patricia@zylker.com"
  22.     },
  23.     "visitor_conversation_id": "2d665c42a02e919ac0f91f62fa78581d",
  24. }

Departments:

There are two different types of event in the Webhooks: Data and administration. The departments is an administration event, you can subscribe to the event and get notified when a new department is created, updated or deleted.

List of department events:
  1. department.created
  2. department.deleted
  3. department.updated

department.created

You can subscribe to this event if you wish to notify whenever a new department is created inside the portal.

  2. Payload:

  4. {
  5.   "entity_type": "department",
  6.   "org_id": "55778119",
  7.   "event": "department.created",
  8.   "entity_id": "40526000001808025",
  9.   "attempt": 1,
  10.   "version": "1",
  11.   "entity": {
  12.     "is_enabled": "true",
  13.     "created_time": "1571032858870",
  14.     "modified_time": "1571032858870",
  15.     "operators": [
  16.       "6000000000005"
  17.     ],
  18.     "is_system_generated": "false",
  19.     "name": "Support",
  20.     "is_public": "true",
  21.     "email_configurations": {
  22.       "missedchat_recipients": "",
  23.       "cc_recipients": "",
  24.       "is_blockip_mail_enabled": "true",
  25.       "from_email": "tricia@zylker.com",
  26.       "transcript_recipients": "tricia@zylker.com",
  27.       "is_feedback_mail_enabled": "true",
  28.       "blockip_recipients": "",
  29.       "feedback_recipients": "",
  30.       "is_missedchat_mail_enabled": "true",
  31.       "is_cc_mail_enabled": "true",
  32.       "is_transcript_mail_enabled": "true"
  33.     },
  34.     "description": "A team to support the visitors on your site",
  35.     "id": "6000000009015",
  36.     "display_name": "Zylker-support",
  37.     "created_by": "6000000000005"
  38.   },
  39.   "event_time": "1567065647511"
  40. }

department.deleted

You can subscribe to this event if you wish to get notified when a department is deleted in the portal. 

  2. Payload:

  4. {
  5.   "entity_type": "department",
  6.   "org_id": "55778119",
  7.   "event": "department.deleted",
  8.   "entity_id": "40526000001808025",
  9.   "attempt": 1,
  10.   "version": "1",
  11.   "event_time": "1567065647511"
  12. }

department.updated

You can subscribe to this event if you wish to get notified when a details in the department is updated.

  2. Payload:

  4. {
  5.   "entity_type": "department",
  6.   "org_id": "55778119",
  7.   "event": "department.updated",
  8.   "entity_id": "40526000001808025",
  9.   "attempt": 1,
  10.   "version": "1",
  11.   "entity": {
  12.     "is_enabled": "true",
  13.     "created_time": "1571032858870",
  14.     "modified_time": "1571032858870",
  15.     "operators": [
  16.       "6000000000005"
  17.     ],
  18.     "is_system_generated": "false",
  19.     "name": "Support",
  20.     "is_public": "true",
  21.     "email_configurations": {
  22.       "missedchat_recipients": "",
  23.       "cc_recipients": "",
  24.       "is_blockip_mail_enabled": "true",
  25.       "from_email": "tricia@zylker.com",
  26.       "transcript_recipients": "tricia@zylker.com",
  27.       "is_feedback_mail_enabled": "true",
  28.       "blockip_recipients": "",
  29.       "feedback_recipients": "",
  30.       "is_missedchat_mail_enabled": "true",
  31.       "is_cc_mail_enabled": "true",
  32.       "is_transcript_mail_enabled": "true"
  33.     },
  34.     "description": "A team to support the visitors on your site",
  35.     "id": "6000000009015",
  36.     "display_name": "Zylker-support",
  37.     "created_by": "6000000000005"
  38.   },
  39.   "event_time": "1567065647511"
  40. }

Operators

There are two different types of events in the Webhooks: Data and administration. The Operators are an administration event, you can subscribe to this and get notified when an operator event is performed.

List of Operator events:
  1. operator.created
  2. operator.updated
  3. operator.deleted
  4. operator.departments.associated
  5. operator.departments.dissociated

operator.created

You can subscribe to this event if you wish to get notified whenever a new operator is added to your organization.

Payload:
  1. {
  2.     "entity_type": "operator",
  3.     "org_id": "15188410",
  4.     "event": "operator.created",
  5.     "entity_id": "115000000029087",
  6.     "attempt": 1,
  7.     "version": "1",
  8.     "entity": {
  9.         "email_id": "patricia@zylker.com",
  10.         "access_levels": [
  11.             "chat",
  12.             "tracking"
  13.         ],
  14.         "role": "Administrator",
  15.         "signature": "2e8132839ffef039e24ab8e162b5b1f1",
  16.         "date_of_birth": "",
  17.         "description": "",
  18.         "language": "",
  19.         "chat_enabled": true,
  20.         "type": "Salesiq User",
  21.         "locale": "",
  22.         "confirmed": false,
  23.         "enabled": true,
  24.         "notify": {
  25.             "return_visit": false,
  26.             "new_visit": false
  27.         },
  28.         "modified_time": "1596093400214",
  29.         "id": "115000000029087",
  30.         "departments": [
  31.             "115000000004001",
  32.             "115000000000018"
  33.         ],
  34.         "first_name": "",
  35.         "owner": false,
  36.         "created_time": "1596093400198",
  37.         "time_format": "12 hours",
  38.         "address": {
  39.             "country": "",
  40.             "pincode": "",
  41.             "city": "",
  42.             "street": "",
  43.             "state": ""
  44.         },
  45.         "maximum_concurrent_chat": "none",
  46.         "image_url": "",
  47.         "mobile": "",
  48.         "last_name": "",
  49.         "time_zone": "",
  50.         "locale_country": "",
  51.         "deleted": false,
  52.         "phone": "",
  53.         "nick_name": "Patricia",
  54.         "social_media": {
  55.             "twitter": {
  56.                 "profile_url": ""
  57.             },
  58.             "linkedin": {
  59.                 "profile_url": ""
  60.             },
  61.             "enabled": false
  62.         },
  63.         "status": "Available"
  64.     },
  65.     "event_time": "1596093402483"
  66. }

operator.updated

You can subscribe to this event if you wish to be notified whenever an operator's setting is modified.

Payload:
  1. {
  2.     "entity_type": "operator",
  3.     "org_id": "15188410",
  4.     "event": "operator.updated",
  5.     "entity_id": "115000000000094",
  6.     "attempt": 1,
  7.     "version": "1",
  8.     "entity": {
  9.         "email_id": "patricia@zylker.com",
  10.         "access_levels": [
  11.             "chat",
  12.             "tracking"
  13.         ],
  14.         "role": "Administrator",
  15.         "signature": "2e8132839ffef039e7eaaa00748b47ec",
  16.         "date_of_birth": "",
  17.         "description": "",
  18.         "language": "en",
  19.         "chat_enabled": true,
  20.         "type": "Salesiq User",
  21.         "locale": "en",
  22.         "confirmed": true,
  23.         "enabled": true,
  24.         "notify": {
  25.             "return_visit": false,
  26.             "new_visit": false
  27.         },
  28.         "modified_time": "1596092957234",
  29.         "id": "115000000000094",
  30.         "departments": [
  31.             "115000000000018"
  32.         ],
  33.         "first_name": "Patricia",
  34.         "owner": false,
  35.         "created_time": "1594720783132",
  36.         "time_format": "12 hours",
  37.         "address": {
  38.             "country": "us",
  39.             "pincode": "625012",
  40.             "city": "Malibu",
  41.             "street": "Pacific Coast Highway",
  42.             "state": "California"
  43.         },
  44.         "maximum_concurrent_chat": "none",
  45.         "image_url": "",
  46.         "mobile": "08903694722",
  47.         "last_name": "Smith",
  48.         "time_zone": "United States/California",
  49.         "zuid": "15102744",
  50.         "locale_country": "us",
  51.         "deleted": false,
  52.         "phone": "1234567890",
  53.         "nick_name": "Patricia",
  54.         "social_media": {
  55.             "twitter": {
  56.                 "profile_url": ""
  57.             },
  58.             "linkedin": {
  59.                 "profile_url": ""
  60.             },
  61.             "enabled": false
  62.         },
  63.         "status": "Available"
  64.     },
  65.     "event_time": "1596092957257"
  66. }

operator.deleted

You can subscribe to this event if you wish to be notified when an operator is removed.

Payload:
  1. {
  2.     "entity_type": "operator",
  3.     "org_id": "15188410",
  4.     "entity_id": "115000000029087",
  5.     "event": "operator.deleted",
  6.     "version": "1",
  7.     "attempt": 1,
  8.     "event_time": "1596093526367"
  9. }

operator.departments.associated

You can subscribe to this event if you wish to get notified whenever an operator is associated with a department.
Payload:
  1. {
  2.     "entity_type": "operator",
  3.     "org_id": "15188410",
  4.     "event": "operator.departments.associated",
  5.     "entity_id": "115000000000006",
  6.     "attempt": 1,
  7.     "version": "1",
  8.     "entity": {
  9.         "departments": [
  10.             "115000000004001"
  11.         ],
  12.         "id": "115000000000006"
  13.     },
  14.     "event_time": "1596094781678"
  15. }

operator.departments.dissociated

You can subscribe to this event if you wish to get notified when an operator is removed from a department.
Payload:
  1. {
  2.     "entity_type": "operator",
  3.     "org_id": "15188410",
  4.     "event": "operator.departments.dissociated",
  5.     "entity_id": "115000000000006",
  6.     "attempt": 1,
  7.     "version": "1",
  8.     "entity": {
  9.         "departments": [
  10.             "115000000004001"
  11.         ],
  12.         "id": "115000000000006"
  13.     },
  14.     "event_time": "1596094781678"
  15. }

Visitors

There are two different types of events in the Webhooks: Data and administration. The Visitors are data event, you can subscribe to this and get notified when a visitor event is performed.

List of Visitor events:
  1. visitor.updated

visitor.updated

You can subscribe to this event if you wish to be notified when a piece of visitor information is updated.

Case 1: You will receive this payload when lead information is updated.

Payload:
  1. {
  2.     "id": "30000000095001",
  3.     "type": "lead ",
  4.     "first_name": "Scott",
  5.     "last_name": "Smith",
  6.     "modifier": {
  7.         "type": "operator",
  8.         "email_id": "patricia@zylker.com",
  9.         "name": "patricia@zylker.com",
  10.         "id": "30000000099007"
  11.     }
  12. }
Case 2: You will receive this payload when contact information is added to a lead

Note: A lead will be converted as a contact when information such as email or phone is provided for the first time.

Payload:
  1. {
  2.     "id": "30000000095001",
  3.     "type": "contact",
  4.     "first_name": "Scott",
  5.     "last_name": "Smith",
  6.     "email_id": "scottsmith@zylker.com",
  7.     "phone": "9123459876",
  8.     "lead": {
  9.         "id": "30000000090034"
  10.     },
  11.     "modifier": {
  12.         "type": "operator",
  13.         "email_id": "patricia@zylker.com",
  14.         "name": "patricia@zylker.com",
  15.         "id": "30000000099007"
  16.     }
  17. }
Case 3: You will receive this payload when a contact's information is updated.

Payload:
  1. {
  2.     "id": "30000000095001",
  3.     "type": "contact",
  4.     "first_name": "Scott",
  5.     "last_name": "Smith",
  6.     "email_id": "scottsmith@zylker.com",
  7.     "phone": "91234598121",
  8.     "modifier": {
  9.         "type": "operator",
  10.         "email_id": "patricia@zylker.com",
  11.         "name": "patricia@zylker.com",
  12.         "id": "30000000099007"
  13.     }
  14. }

How can I set up Webhooks?

To setup webhooks,
  1. Inside the SalesIQ dashboard, navigate to Settings > Developers > Webhooks .
  2. Here, you can add portal-based and embed-based events through webhooks in the Administration and Data modules respectively. You will be notified to the specified URL when an event occurs.

How to add a portal-based webhook in the Administration module?

Inside the Administration module, you can create webhooks based on portal operations. On subscription, you will be notified every time a portal event occurs. To add a new webhook,
  1. Click Add .
  2. Enter the URL that has to be invoked.
  3. Choose the events that you want to associate with the webhook.

  1. Finally, click Create Webhook and your webhook will be created. 
  2. You will also be able to see the Webhook instructions here.


How to delete a portal-based webhook in the Administration Module?

To delete a webhook,
  1. In the dashboard, hover over the webhook that you want to delete and then click on the delete icon on the far right.

  1. A confirmation pop-up appears. Click Delete and the webhook will be deleted.

How to enable/disable a webhook in the Administration module?

To enable/disable a webhook,
  1. Click the toggle button that appears on the right end of each webhook.

How to add an embed-based webhook in the Data module?

Inside the Data module, you can create webhooks based on embed operations. On subscription, you will be notified every time an embed event occurs. To add a new webhook,
  1. Click  Add .
  2. Choose the SalesIQ app(s) that you want to create a webhook for.

  1. Enter the URL that has to be invoked.
  2. Choose the events that you want to associate with the webhook.

  1. Finally, click  Create Webhook  and your webhook will be created.
  2. You will also be able to see the Webhook instructions here.



How to delete an embed-based webhook in the Data Module?

To delete a webhook,
  1. In the dashboard, hover over the webhook that you want to delete and then click on the delete icon on the far right.

  1. A confirmation pop-up appears. Click Delete and the webhook will be deleted.


How to enable/disable a webhook in the Data module?

To enable/disable a webhook,
  1. Click the toggle button that appears on the right end of each webhook.

Dashboard:

Inside the webhook dashboard, you will be able to view the following details:
  1. Failures: The number of times the webhook has failed
  2. Last Triggered: When the webhook was last triggered
  3. App: A list of the apps the webhook is associated with



    Zoho CRM Training Programs

    Learn how to use the best tools for sales force automation and better customer engagement from Zoho's implementation specialists.

    Zoho CRM Training
      Redefine the way you work
      with Zoho Workplace
      Start your free trial

        Zoho DataPrep Personalized Demo

        If you'd like a personalized walk-through of our data preparation tool, please request a demo and we'll be happy to show you how to get the best out of Zoho DataPrep.

        Zoho CRM Training

          Create, share, and deliver

          beautiful slides from anywhere.

          Get Started Now


            Zoho Sign now offers specialized one-on-one training for both administrators and developers.

            BOOK A SESSION






                          Zoho Pagesense Resources


                                You are currently viewing the help pages of Qntrl’s earlier version. Click here to view our latest version—Qntrl 3.0's help articles.


                                  Zoho Survey Resources
                                    Features
                                    Survey Templates
                                    Integrations
                                    Community
                                    iOS Mobile Surveys
                                    Pricing
                                    Android Mobile Surveys
                                    Insurvey Blogs
                                    Insight Blogs
                                    Tips & Tricks


                                    Manage your brands on social media
                                    Access Zoho Social


                                      Zoho Desk Resources

                                      • Desk Community Learning Series


                                      • Digest


                                      • Functions


                                      • Meetups


                                      • Kbase


                                      • Resources


                                      • Glossary


                                      • Desk Marketplace


                                      • MVP Corner


                                      • Word of the Day


                                        Zoho Marketing Automation

                                          Zoho Sheet Resources

                                           

                                              Zoho Forms Resources


                                                Features

                                                Form Templates

                                                Customers

                                                Mobile Forms

                                                Pricing

                                                Integrations

                                                Blogs

                                                Ebooks

                                                Tips & Tricks

                                                Community

                                                Terms of Use

                                                Secure your business
                                                communication with Zoho Mail
                                                Get started


                                                Mail on the move with
                                                Zoho Mail mobile application
                                                Go Mobile

                                                  Stay on top of your schedule
                                                  at all times
                                                  Get started


                                                  Carry your calendar with you
                                                  Anytime, anywhere
                                                  Get started


                                                    Latest Announcements


                                                        Zoho Sign Resources

                                                          What's new
                                                          Help Guide
                                                          Solutions Guide
                                                          API
                                                          Blogs
                                                          FAQ's
                                                          Legal Guide
                                                          Forums
                                                          Webinars

                                                          Sign, Paperless!

                                                          Sign and send business documents on the go!

                                                          Get Started Now


                                                              Zoho SalesIQ Resources


                                                                  Zoho TeamInbox Resources



                                                                        Latest Feature Updates

                                                                          Zoho DataPrep Resources



                                                                            Zoho DataPrep Demo

                                                                            Get a personalized demo or POC

                                                                            REGISTER NOW


                                                                              Design. Discuss. Deliver.

                                                                              Create visually engaging stories with Zoho Show.

                                                                              Get Started Now






                                                                                        Latest Feature Updates

                                                                                            You are currently viewing the help articles of Sprints 1.0. If you are a user of 2.0, please refer here.

                                                                                            You are currently viewing the help articles of Sprints 2.0. If you are a user of 1.0, please refer here.



                                                                                                Setup Zoho Bigin in 30 Minitues
                                                                                                Latest Feature Updates

                                                                                                  • Related Articles

                                                                                                  • LINE Chat Integration with Zoho SalesIQ

                                                                                                    Integrating LINE Chat with Zoho SalesIQ allows your customers to connect with your operators directly using LINE Chat. Operators can instantly pick up conversations directly within Zoho SalesIQ. Integrating LINE chat with brands If you want to ...

                                                                                                  • Create Zobot for your website

                                                                                                    In the Zoho SalesIQ dashboard, navigate to Settings > Bot, and click Zobot. Inside the bot builder, give your bot a Name. Then, Choose a platform to structure, configure, and create your bot. These are the available platforms: SalesIQ Platforms ...

                                                                                                  • Reports 2.0 (Beta)

                                                                                                    Overview The Reports module will provide you with a full overview of the overall performance of your brands and support operations on Zoho SalesIQ. You can track various data such as your operators' performance, volume of bot conversations, visitor ...
                                                                                                    Bootcamp
                                                                                                    Community
                                                                                                    Pricing
                                                                                                    Webinars
                                                                                                    What's New
                                                                                                    Integrations
                                                                                                    Contact Support
                                                                                                    Contact Sales
                                                                                                    Wherever you are is as good as
                                                                                                    your workplace
                                                                                                    Workplace on mobile

                                                                                                      Resources

                                                                                                      Videos

                                                                                                      Watch comprehensive videos on features and other important topics that will help you master Zoho CRM.



                                                                                                      eBooks

                                                                                                      Download free eBooks and access a range of topics to get deeper insight on successfully using Zoho CRM.



                                                                                                      Webinars

                                                                                                      Sign up for our webinars and learn the Zoho CRM basics, from customization to sales force automation and more.



                                                                                                      CRM Tips

                                                                                                      Make the most of Zoho CRM with these useful tips.



                                                                                                        Zoho Show Resources