Live call events
Keep a call interface current with Socket.io notifications, then reload authoritative call state.
Connect an authenticated agent
Use the /agent Socket.io namespace with the existing agent-session token. Connection access is workspace-scoped and subject to session revocation. Do not publish an agent token in a website widget.
Event notifications can be duplicated or missed during reconnects. Treat them as refresh signals, match conversationId, and load the current call record after reconnecting. Do not infer a live call solely from an old event or elapsed timer.
import { io } from 'socket.io-client';
const socket = io('https://app.message.com/agent', { auth: { token: agentToken } });
const events = ['call:ringing', 'call:answered', 'call:on_hold', 'call:resumed',
'call:ended', 'call:ai_phase', 'call:voicemail_started', 'call:voicemail_ready',
'call:transcript_ready', 'call:recording_ready'];
for (const event of events) {
socket.on(event, payload => {
if (payload.conversationId === selectedConversationId) refreshCall();
});
}
socket.on('connect', refreshCall);Ringing, answering and ending
call:ringing identifies conversationId, fromE164, toE164 and phoneNumberId, with routing information and version. There is no separate callId required for HTTP call controls.
call:answered identifies the conversation and agent; it can include agentName, version and an event record. call:on_hold and call:resumed announce hold changes. call:ended announces completion of the phone session. Payloads vary by the provider and hangup path; reload detail rather than assuming every notification includes a duration or artifact.
AI conversation and agent handoff
call:ai_phase carries conversationId and speaking. While speaking is true, display “Speaking with AI” and disable Take Call. Re-enable it when the phase ends and the current call remains available. The server enforces the same restriction.
The configured assistant finishes its greeting and context collection before an agent takes the call. AI behavior is configured per supported phone assignment; hold does not imply a universal five-minute AI takeover. Read aiCallerContext and liveCaptions from call detail for available context.
Voicemail, recordings and transcripts
call:voicemail_started indicates that voicemail recording began. call:voicemail_ready, call:voicemail_updated, call:transcript_ready and call:recording_ready signal new or changed artifacts. Reload the authorized detail endpoint to get their identifiers and current availability.
A recording and a transcript are separate artifacts. Either may still be processing or unavailable under the workspace’s recording settings. Never display “available” just because a call ended.
Use HTTP for call actions
Answer, hold, resume and hangup use the protected HTTP call controllers. Transfer uses the assignment endpoint and acceptance workflow. Do not send legacy socket mutation commands: they return use_rest_call_control instead of changing call state.
HTTP control keeps department access, subscription access, atomic claims and actual audio cleanup on one path. See the Calls API for request bodies and error handling.