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:
- 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
WhatsApp Message Templates User Guide
What is a Message Template? A WhatsApp Message Template is a pre-approved customized message that is used to send notifications to opted-in customers. To start using the Message templates, you must first submit the messages to WhatsApp and get them ...Setting up Webhooks
Webhooks are one way that apps can send automated messages or information to other apps. They facilitate communication with third-party applications by sending instant web notifications every time an event occurs in Zoho Desk. All you need to do is ...Setting Task Status, Due Date, and Priority
Task Status An important aspect of customer support is to keep track of all the tasks that are created on your help desk. Task status accurately reflects the current stage of your tasks, from start to finish. With task status, you can neatly track ...Ticket Status Lifecycle Extension for Zoho Desk
A ticket can go through various statuses once it gets created. For example, upon its creation, ticket status is Open. When an agent replies to the ticket, its status will change to Resolved. Similarly, if the customer responds to the same ticket, ...How to set the welcome message on the ASAP Help Widget
Specifying the Welcome Message A personalized welcome message can serve as a friendly greeting for customers when they first access your ASAP help widget. You can include a brief introduction about your service and explain how it can benefit them, ...
New to Zoho LandingPage?
Zoho LandingPage Resources