Instant messaging moves fast. Whether a customer sends a WhatsApp message at midnight or your agent replies mid-conversation, the IM Message Add webhook captures it all in real time, across every channel.
What is the IM Message Add Event?
The IM Message Add Event is triggered whenever an incoming or outgoing instant message is received. It gives you message-level visibility, not just session-level, making it ideal for tracking individual message activity within a chat session across channels such as WhatsApp, Instagram, Facebook Messenger, and live chat.
Note
Event Type: IM_Message_Add
Sample Payload
Every time an incoming or outgoing IM message is received, you will get a payload like this at your webhook endpoint:
[{
"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"
}]
Payload Fields Reference
| Field |
Type |
Description |
| actor.contactId |
string |
Zoho Desk contact ID of the message sender |
| actor.name |
string |
Display name of the sender |
| actor.externalId |
string |
External identifier, such as a phone number for WhatsApp |
| actor.type |
string |
ENDUSER (customer) or AGENT |
| messageType |
string |
Format of the message: TEXT, IMAGE, DOCUMENT, etc. |
| direction |
string |
IN for incoming from customer; OUT for outgoing from agent or bot |
| integration |
string |
The channel the message came through, such as WHATSAPP, INSTAGRAM, FACEBOOK |
| text |
string |
The message content. Only present when messageType is TEXT |
| status |
string |
Current state of the message, such as SAVED |
| sessionId |
string |
ID of the parent chat session this message belongs to |
| channelId |
string |
ID of the IM channel configured in your portal |
| meta.DESK_TICKET_ID |
string |
The Zoho Desk ticket linked to this conversation |
| meta.DESK_TICKET_NUMBER |
string |
Human-readable ticket number |
| createdTime |
timestamp |
Unix epoch (milliseconds) of when the message was created in Zoho Desk |
| eventTime |
timestamp |
Unix epoch (milliseconds) of when the webhook event fired |
How to Set It Up
Follow these steps to configure the IM Message Add webhook in your portal:
Setup
1. Navigate to Setup > Automation > Webhooks.
2. Click Create Webhook.
3. Select the IM Message Add event.
4. Enter your Webhook URL: this is where payloads will be delivered.
5. Optionally, specify department IDs to filter notifications to specific departments only.
6. Click Save and test.
Note
You can filter by department. Pass a list of departmentIds in the API subscription to receive events only from selected departments. If no filter is set, events fire for all departments.
See also:
Practical Use Cases
1. Automated first-response acknowledgment
When direction is IN and no agent has replied yet, trigger an automated acknowledgment to the customer. Use sessionId to check whether any prior OUT message exists in the session. If not, fire the acknowledgment.
2. Keyword-triggered escalation
Parse the text field for high-urgency keywords such as "urgent", "broken", "refund", or "cancel". When matched, automatically escalate the linked ticket (meta.DESK_TICKET_ID) to a senior agent or create a high-priority task.
3. Build a full conversation timeline
Combine sessionId, direction, createdTime, and actor.type to reconstruct the exact order of every message in a session. This is useful for quality reviews, dispute resolution, and compliance audits.
4. Cross-channel CRM sync
When a message arrives on WhatsApp (integration: "WHATSAPP"), push the message content and contact details (actor.contactId, actor.name, actor.externalId) to Zoho CRM or a third-party CRM to keep customer records updated in real time.
5. Channel health monitoring
If your WhatsApp access token expires or messaging credits run out, messages may fail silently. Monitor for gaps in IM_Message_Add events during active sessions. If a session has no new events for an unexpected duration, alert your admin before customers are affected.
6. Agent response time tracking
By logging IN and OUT messages with their createdTime and sessionId, you can calculate first-response time and average response cadence per agent, metrics that are otherwise hard to extract from IM sessions.
Troubleshooting and FAQ
Q: My webhook is not receiving any events. What should I check?
A: First confirm the webhook is enabled. Zoho Desk limits active webhooks by edition: Professional allows 5, Enterprise allows 10, and Ultimate allows 20. If you have hit your limit, newly created webhooks remain disabled. Go to Setup > Automation > Webhooks and check the isEnabled status. Also verify that your endpoint responds with 200 OK within 5 seconds. Any other response code or a timeout is treated as a failed delivery, and a 410 Gone response causes Zoho Desk to remove the webhook subscription automatically.
Q: The webhook was created successfully but I am not getting events from a specific department.
A: Check your departmentIds filter. If you passed specific IDs during webhook creation, events only fire for those departments. To receive events from all departments, ensure departmentIds is set to null or left empty.
Q: I am getting events but the text field is empty for some messages.
A: This is expected for non-text message types such as images, documents, and audio. Check the messageType field. If it is not TEXT, the content is a media attachment and the text field will be absent or empty.
Q: I am seeing a large delay between createdTime and eventTime.
A: A gap between these two timestamps is normal. createdTime is when the message was recorded in Zoho Desk, while eventTime is when the webhook payload was dispatched. Under normal load the gap is minimal. A large gap may indicate temporary queue buildup on Zoho's end; retry logic on your side can help.
Q: Can I use the same webhook URL for multiple events?
A: Yes. A single callback URL can receive any number of event types. You can subscribe to IM_Message_Add, IM_Session_Status, and IM_Message_Status at the same URL and differentiate them using the eventType field in each payload.
Q: Who can create webhooks?
A: Only users assigned a profile with the Webhook permission enabled. To check or modify this, go to Setup > Users and Control > Permissions > Profiles.