Set Up IM Session Status Webhook
Never miss a conversation update in IM! With the IM Session Status webhook, you’ll know right away when a live chat or instant message session changes status, so you can respond quickly, keep your team informed.
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:
- Is picked up by an agent or a bot
- Goes on hold or ends
- Gets assigned, blocked, or switched between open and active states
This lets you:
- Trigger internal workflows instantly (like reassigning a ticket or updating a dashboard)
- Analyze support team performance in real time
- Monitor customer engagement across channels
Steps to set up your webhook for IM Session Status updates
- Navigate to Setup > Automation > Webhooks.
- Click Create Webhook.
- Select the IM Session Status event.
- Enter your Webhook URL. This is where notifications will be sent.
- 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"
}]
"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 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
- Real-time Agent Routing: Reassign chats when status is "ON_HOLD" too long.
- Performance Tracking: Log all ENDED sessions for service-quality reviews.
- Queue Monitoring: Alert supervisors when sessions stay "OPEN" with no assignee.
- Omnichannel Insights: Tie chat behavior to other channel data with the unique session or channel ID.
Advanced tips and integration examples
Automating escalations
- Connect the webhook to your ticketing or incident management system.
- Trigger auto-escalation for sessions blocked, left open, or ended abruptly.
Live analytics dashboard
- Feed webhook data into a dashboard tool for up-to-the-minute session trends, agent workloads, and engagement stats.
Custom notifications
- Use payload data to build targeted email, SMS, or app notifications for your team.
- Send alerts for "BLOCKED" or "CREDIT_EXHAUSTED" statuses to prevent lost conversations.
Best practices
- Document Your Flows: Keep a record of each status transition for compliance and clarity.
- Regularly Review Status Definitions: Stay up to date with any new values Zoho adds.
- Test Thoroughly: Simulate all session states and statuses in a sandbox before going live.
- Secure Your Endpoint: Use authentication, validation, and logging to protect your webhook URL.
Troubleshooting & FAQ
Why am I not receiving any webook events?
- Double-check the destination URL. Ensure it is accessible, expects POST requests, and can parse JSON.
- Review authentication and firewall settings if you use a secured webhook endpoint.
Why is the data my webhook is receiving not useful?
- Make sure your logic checks for all possible statuses (such as "BLOCKED" or "SESSION_EXPIRED").
- Map sessionStatus and replyStatus values in your app to accurately reflect session lifecycles.
Can I use this webhook for Whatsapp/Facebook/Instagram?
- Yes! The payload includes helpful statuses for social channels. Look for replyStatus like ‘ACCESSTOKEN_EXPIRED’ or ‘PERMISSION_REVOKED’ for Facebook/Instagram integrations.
Access your files securely from anywhere
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 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 Workerly Home
- Forums
- Connect With Us:
- Zoho Recruit Home
- Forums
- Connect With Us:
New to Zoho Writer?
Create. Review. Publish.
New to Zoho CRM Plus?
Deliver unforgettable customer experiences
New to Zoho CRM Plus?
Deliver unforgettable customer experiences
New to Zoho Marketing Plus?
Everything you need to run your marketing
New to Zoho Marketing Plus?
Everything you need to run your marketing
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.
New to Zoho Survey?
Zoho Sheet Resources
Zoho Forms Resources
New to Zoho Sign?
Zoho Sign Resources
Sign, Paperless!
New to Zoho TeamInbox?
Zoho TeamInbox Resources
New to Zoho ZeptoMail?
Design. Discuss. Deliver.
New to Zoho Workerly?
New to Zoho Recruit?
New to Zoho CRM?
New to Zoho Projects?
New to Zoho Sprints?
New to Zoho Assist?
New to Bigin?
Related Articles
Measuring Customer Happiness in Instant Messaging
Getting genuine, useful feedback after a chat support interaction shouldn’t feel forced for you or your customers. With Zoho Desk, you can gather honest feedback without interrupting the conversation flow. This guide covers how Customer Satisfaction ...Introduction to Instant Messaging
Instant messaging (IM) enables you to connect with your customers on the messaging apps they use, such as WhatsApp, Telegram, Facebook Messenger, and more. This feature consolidates customer conversations from various platforms into one unified ...Configure Welcome Messages in Instant Messaging Inbox
Welcome messages are your first opportunity to create a positive and professional impression when customers start a chat. This guide will help you set up and manage welcome messages in your Instant Messaging (IM) channels. What you will achieve with ...WhatsApp Multi-WABA support by Instant Messaging
If you've been using the WhatsApp channel to communicate with your customers, you're likely aware that every WhatsApp Business Account (WABA) needs a verified phone number specifically dedicated to that IM channel for the current WhatsApp Business ...Configure Offline Messages in Instant Messaging Channels
When a customer reaches out for help and no one’s there to respond, this can lead to feelings of frustration. That’s why Offline Messages exist, to let your customers know you’ve received their message and will get back to them soon. This article ...
New to Zoho LandingPage?
Zoho LandingPage Resources