Inbox agent events
Use the actual Inbox event names and payloads for queues, conversations and agent presence.
Load the queue
Emit agent:hello after connecting. queue:snapshot contains conversations, truncated and total. Respect truncated instead of treating the snapshot as every conversation in a large workspace. Access depends on the agent’s workspace, product, department and queue permissions.
Take the next chat or ticket
agent:take-next accepts channel chat or ticket and returns one acknowledgement object. A null conversationId means no assignment was made; inspect reason and message. Calls use the protected HTTP call-answer flow, not this event.
socket.emit("agent:take-next", { channel: "ticket" }, result => {
if (!result.conversationId) {
console.info(result.reason, result.message);
return;
}
socket.emit("agent:open-conversation", {
conversationId: result.conversationId
});
});Open and read a conversation
agent:open-conversation joins an authorized conversation and returns conversation:history with conversationId, conversation and messages. agent:close-conversation leaves that subscription. New messages arrive as conversation:message with conversationId and message.
socket.on("conversation:history", ({ conversationId, conversation, messages }) => {
// Replace the thread with the authorized history.
});
socket.on("conversation:message", ({ conversationId, message }) => {
// Upsert by message.id in the matching thread.
});Send an agent reply
agent:message takes conversationId, body and optional attachments. This event does not implement a success acknowledgement callback. Listen for conversation:message and the error event. Channel rules, assignment, product access, opt-outs and delivery limits still apply. A queued external-channel message is not proof of delivery.
socket.on("error", ({ code, reason, conversationId }) => {
// Show a failure for the affected conversation; retain the draft.
});
socket.emit("agent:message", { conversationId, body: "How can I help?" });Presence
Set availability with agent:status using status available, away or offline. Read agent:presence-snapshot and agent:status-change; a network connection alone is not a request to become available. Use the authentication and presence guide for connection failures.