Set Up and Use the IM Session Status Webhook in Zoho Desk

Set Up IM Message and Session Status Webhooks

Never miss a conversation update in IM! With the IM webhooks, you’ll know right away when a live chat or instant message session changes status, so you can respond quickly, keep your team informed.


IM Message Add Event

This event is triggered whenever an incoming or outgoing instant message (IM) is received. It helps you track individual message-level activity within a chat session. Learn more
Event Type: IM_Message_Add

[{
  "payload": {
    "actor": {
      "contactId": "186543000000451259",
      "name": "Kamal Nayan",
      "externalId": "+919878765654",
      "type": "ENDUSER"
    },
    "messageType": "TEXT",
    "meta": {
      "DESK_TICKET_ID": "186543000001543003",
      "DESK_TICKET_NUMBER": "434"
    },
    "integration": "WHATSAPP",
    "createdTime": "1710293987000",
    "sessionId": "3942000001025025",
    "id": "3942000001321149",
    "text": "This is Zykler Cares. I have some issues with my phone",
    "channelId": "3942000000995017",
    "direction": "IN",
    "status": "SAVED"
  },
  "eventTime": "1710313788286",
  "eventType": "IM_Message_Add",
  "orgId": "78412359"
}]

What can you achieve with the IM Session Status webhook?   

Stay in control of every customer conversation. The IM Session Status webhook notifies you automatically the moment a chat session:
  1. Is picked up by an agent or a bot
  2. Goes on hold or ends
  3. Gets assigned, blocked, or switched between open and active states
 
This lets you:
  1. Trigger internal workflows instantly (like reassigning a ticket or updating a dashboard)
  2. Analyze support team performance in real time
  3. Monitor customer engagement across channels

Steps to set up your webhook for IM Session Status updates   

  1. Navigate to Setup > Automation > Webhooks.
  2. Click Create Webhook.
  3. Select the IM Session Status event.
  4. Enter your Webhook URL. This is where notifications will be sent.
  5. Save and test.

What information do you get in each webhook notification?   

 
Every time a chat/IM session’s status changes, you’ll get a payload like this at your webhook endpoint:
json
 [{
  "payload": {
    "currentAssigneeId": "106554156",
    "sessionStatus": "ON_HOLD",
    "replyStatus": "ACCEPTED",
    "sessionOldStatus": "ENDED",
    "sessionId": "65403000000038063",
    "messagesCount": "23",
    "assigneeType": "AGENT",
    "channelId": "65403000000038011"
  },
  "eventTime": "1751022087019",
  "eventType": "IM_Session_Status",
  "orgId": "106553778"
}] 
See the official step-by-step webhook setup

Payload field description
Payload field description
Field
Description
currentAssigneeId
Agent or bot ID currently handling the session.
sessionStatus
Current status of the conversation (e.g., ON_PROGRESS, ENDED).
replyStatus
If messages can be sent/received for this session (see below for all possible statuses).
sessionOldStatus
Previous status of the session. This helps with tracking changes.
sessionId
Unique identifier for the session.
messagesCount
Total number of messages exchanged so far.
assigneeType
Identifies if the current handler is an ‘AGENT’ or a ‘BOT’.
channelId
ID of the channel (chat, social, etc.) where the session occurred.
eventTime
Timestamp of event occurrence.
eventType
The type of webhook event received (IM_Session_Status).
orgId
Your Zoho Desk organization ID.
   

Status Values Cheat Sheet   

Session Status
Reply Status
Session Status
Value
Description
CREATED
New conversation started by an end user.
OPEN
Waiting to be handled by an agent or bot.
ON_PROGRESS
Agent/bot is actively involved in the session.
ON_HOLD
Picked up, but no response sent yet.
ENDED
Agent/bot has ended the session.
BLOCKED
Session is blocked; no further messages allowed.
Reply Status
Value
What It Means
ACCEPTED
Messages can be exchanged.
CHANNEL_INACTIVE
Channel is inactive. Messages cannot be sent.
CHANNEL_REVOKED
Channel revoked. Messages cannot be sent.
SESSION_ENDED
Session ended and communication is closed.
SESSION_BLOCKED
Blocked by agent. No messages allowed.
SESSION_EXPIRED
Expired session. The user must send another message to resume.
UNASSIGNED
Not assigned to anyone.
NOT_AN_ASSIGNEE
Handler is not actually assigned to the session.
CREDIT_EXHAUSTED
Message credit exhausted and no more can be sent.
ACCESSTOKEN_EXPIRED
(FB/Instagram only) Access token expired, needs reauthentication.
PERMISSION_REVOKED
(FB/Instagram only) Page permission revoked.
UNEXPECTED_ERROR
Error sending message. There may be a misconfiguration.
PAGE_REMOVED
Page/channel deleted or deactivated.
SANDBOX_LIMIT_REACHED
Sandbox daily message limit reached.
CHANNEL_DELETED
Channel deleted; messaging disabled.
ENDUSER_OFFLINE
(ZBM sessions) End user is offline; only receive messages.
CONFIG_SKIPPED_CHANNEL
Configuration skipped.
OUTGOING_LIMIT_REACHED
Message limit reached for outbound messages.
ASSIGNED_TO_OTHER_SERVICE
Handled by another Zoho service.


Practical use cases   

  1. Real-time Agent Routing: Reassign chats when status is "ON_HOLD" too long.
  2. Performance Tracking: Log all ENDED sessions for service-quality reviews.
  3. Queue Monitoring: Alert supervisors when sessions stay "OPEN" with no assignee.
  4. Omnichannel Insights: Tie chat behavior to other channel data with the unique session or channel ID.

Advanced tips and integration examples   

Automating escalations
  1. Connect the webhook to your ticketing or incident management system.
  2. Trigger auto-escalation for sessions blocked, left open, or ended abruptly.
Live analytics dashboard
  1. Feed webhook data into a dashboard tool for up-to-the-minute session trends, agent workloads, and engagement stats.

Custom notifications
  1. Use payload data to build targeted email, SMS, or app notifications for your team.
  2. Send alerts for "BLOCKED" or "CREDIT_EXHAUSTED" statuses to prevent lost conversations.


Best practices  

  1. Document Your Flows: Keep a record of each status transition for compliance and clarity.
  2. Regularly Review Status Definitions: Stay up to date with any new values Zoho adds.
  3. Test Thoroughly: Simulate all session states and statuses in a sandbox before going live.
  4. Secure Your Endpoint: Use authentication, validation, and logging to protect your webhook URL.

Troubleshooting & FAQ

Why am I not receiving any webook events?
  1. Double-check the destination URL. Ensure it is accessible, expects POST requests, and can parse JSON.
  2. Review authentication and firewall settings if you use a secured webhook endpoint.
Why is the data my webhook is receiving not useful?
  1. Make sure your logic checks for all possible statuses (such as "BLOCKED" or "SESSION_EXPIRED").
  2. Map sessionStatus and replyStatus values in your app to accurately reflect session lifecycles.
Can I use this webhook for Whatsapp/Facebook/Instagram?
  1. Yes! The payload includes helpful statuses for social channels. Look for replyStatus like ‘ACCESSTOKEN_EXPIRED’ or ‘PERMISSION_REVOKED’ for Facebook/Instagram integrations.