A chat session can change hands multiple times: from bot to agent, from active to on hold, from open to ended. The IM Session Status webhook triggers every time that happens, giving your team instant awareness so you can act, route, and report without delay.
What is the IM Session Status event?
This event triggers whenever the status of an IM conversation (session) changes, whether that is a customer being picked up by an agent, a session going on hold, an agent being reassigned, or the conversation ending. Unlike the IM_Message_Add event which tracks individual messages, this one tracks the overall state of the conversation.
Note
Event Type: IM_Session_Status
Sample Payload
Every time a chat or IM session's status changes, you will receive a payload like this at your webhook endpoint:
[{
"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"
}]
Payload fields reference
| Field |
Type |
Description |
| sessionId |
string |
Unique identifier for the conversation session |
| sessionStatus |
string |
The new or current status of the session (see Status Values below) |
| sessionOldStatus |
string |
The previous status before this change |
| currentAssigneeId |
string |
ID of the agent or bot currently handling the session) |
| assigneeType |
string |
AGENT or BOT: who currently owns the session |
| replyStatus |
string |
Whether a reply has been accepted: ACCEPTED or PENDING |
| messagesCount |
string |
Total number of messages exchanged in the session so far |
| channelId |
string |
ID of the IM channel where the session is happening |
| eventTime |
timestamp |
Unix epoch (milliseconds) of when the webhook event fired |
Session Status values
Use both sessionStatus and sessionOldStatus together to understand the exact transition. For example, ACTIVE to ON_HOLD tells you an agent paused an active conversation, which is different from OPEN to ON_HOLD.
| Status |
Meaning |
| OPEN |
Session created, waiting for assignment |
| ACTIVE |
Session is assigned and a conversation is ongoing |
| ON_HOLD |
Session is paused; agent or bot has placed it on hold |
| ENDED |
Session has been closed |
| ASSIGNED |
Session has been assigned to an agent or bot |
| BLOCKED |
Session is blocked; no further messages can be sent |
How to set it up
Follow these steps to configure the IM Session Status webhook in your portal:
Setup
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 payloads will be delivered.
5. Optionally, specify department IDs to scope notifications to specific departments only.
6. Click Save and test.
Note
The IM_Session_Status event does not support field-level filters. You receive the full payload on every status change. Use sessionStatus and sessionOldStatus in your own logic to act only on the transitions that matter to you.
Practical use cases
1. Real-time agent routing: act on sessions left on hold
When sessionStatus is ON_HOLD and a timer threshold is exceeded (for example, five minutes with no update), trigger a reassignment via the Zoho Desk API or alert a supervisor. This prevents customers from waiting indefinitely.
Log every ACTIVE to ENDED transition with its sessionId, messagesCount, currentAssigneeId, and eventTime. Aggregate these to measure average handling time, sessions per agent per day, and hold rates, all without touching Zoho Desk's UI.
3. Bot-to-agent handover tracking
When assigneeType changes from BOT to AGENT, log the handover event. This helps you measure how often your bot successfully resolves conversations without escalation, which is a key automation health metric.
4. Queue overflow alerting
When sessions pile up in OPEN status with no currentAssigneeId, your queue is backing up. Alert supervisors or trigger a Zoho Flow automation to redistribute load when the count of unassigned open sessions crosses a threshold.
5. Conversation-end audit trail
On every ENDED event, log the full session summary: sessionId, messagesCount, currentAssigneeId, and eventTime. This creates an audit trail for quality assurance, dispute resolution, and compliance review.
6. Proactive CRM updates
When a session ends (sessionStatus: "ENDED"), automatically close the linked Zoho Desk ticket or push a session summary note to the associated CRM contact. Use channelId and sessionId to look up the ticket via the Zoho Desk API.
Troubleshooting and FAQ
Q: I am not receiving any events. What should I check?
A: The most common causes are a disabled webhook, a slow or incorrect endpoint response, or a failed validation during webhook creation. Check your edition limits: Professional allows 5 active webhooks, Enterprise allows 10, and Ultimate allows 20. If you have hit your limit, newly created webhooks remain disabled. Also confirm that your endpoint responds with 200 OK within 5 seconds. When a webhook is created, Zoho sends a validation GET request to your URL first. If your endpoint does not return 200 OK, Zoho retries with a POST. Failure on both results in the webhook not being created at all.
Q: My endpoint returned a 410 Gone response. What happened?
A: A 410 Gone response tells Zoho Desk your endpoint no longer exists. Zoho automatically removes the webhook subscription when it receives this status code. You will need to recreate the webhook after fixing your endpoint.
Q: I am receiving events but cannot tell which transition triggered them.
A: Always check both sessionStatus (new state) and sessionOldStatus (previous state) together. For example, sessionOldStatus: "ACTIVE" with sessionStatus: "ON_HOLD" means an active chat was placed on hold, while sessionOldStatus: "OPEN" with sessionStatus: "ENDED" means a session was abandoned before anyone picked it up.
Q: Can I filter events to a specific department?
A: Yes. Pass a list of departmentIds in your webhook subscription. This is useful if you have separate teams managing different channels and want each team's endpoint to receive only the relevant session events.
Q: I do not have permission to create webhooks.
A: Webhook creation is profile-specific. Only users with the Webhook permission enabled in their profile can create them. Ask your Zoho Desk administrator to go to Setup > Users and Control > Permissions > Profiles and enable the permission for your profile.
Q: How do I test my webhook before going live?
A: Use a service like webhook.site or ngrok to expose a local endpoint during development. Create the webhook pointing to your test URL, then simulate session changes in Zoho Desk (for example, start a test chat, place it on hold, end it) and verify the payloads arrive as expected before switching to your production URL.