Calls API
Read call history and control assigned calls through authenticated Message.com requests.
Access and audio
These dashboard endpoints require an authenticated agent session, phone-product access and the appropriate department scope. They do not accept a Verify or iMessage integration key. Keep agent credentials private. The Inbox provides the supported browser audio client; an HTTP answer request alone does not attach a microphone.
Call control uses HTTP. Socket.io delivers state-change notifications. The legacy call:answer, call:hold and call:hangup socket commands do not perform writes.
List calls
GET /api/v1/calls returns { calls, nextCursor }. Supported query parameters are status, limit (1–100; default 50) and cursor. Status accepts open, pending, closed, solved or spam. Pass nextCursor unchanged to continue. Department access is applied automatically; arbitrary assignee or phone-number filters are not supported by this endpoint.
Closed means the phone call has ended. Solved means the associated request has been completed. Do not render a closed call as an active ringing call.
curl 'https://app.message.com/api/v1/calls?status=closed&limit=50' \
-H "Authorization: Bearer $MESSAGE_AGENT_TOKEN"Read a call and its transcript
GET /api/v1/calls/:conversationId returns call, events, recordingId, transcriptId, agentName, aiCallerContext, liveCaptions and handling. The call object contains id, status, assignedAgentId, metadata, externalRef, closedAt and version. Events are a separate array, capped at 500.
recordingId and transcriptId are null when no artifact exists. liveCaptions can contain partial text before a saved transcript is ready. Fetch authorized artifacts using the recording and transcript APIs; do not assume a permanent public recording URL exists.
Take a call
POST /api/v1/calls/:conversationId/answer accepts { "answerOn": "browser" } or { "answerOn": "desk" }. With no choice, an active assigned desk phone is preferred; otherwise the browser is used. The response includes call, event, livekit and the effective answerOn.
An atomic claim prevents two agents taking the same call. A call cannot be taken while the AI is speaking. A 409 response can indicate an existing claim, ended call, busy agent, stale state or voicemail already started. Read the error and refresh the call; do not loop answer requests.
const response = await fetch(`https://app.message.com/api/v1/calls/${conversationId}/answer`, {
method: 'POST',
headers: { Authorization: `Bearer ${agentToken}`, 'Content-Type': 'application/json' },
body: JSON.stringify({ answerOn: 'desk' })
});
const result = await response.json();
if (!response.ok) throw new Error(result.message || result.reason || result.error);Hold and resume
POST /api/v1/calls/:conversationId/hold accepts { "hold": true } to hold and { "hold": false } to resume. There is no separate /resume endpoint. The assigned agent or a workspace administrator can control hold.
A 503 hold_unavailable response means the audio change failed. Keep the current visible state and allow a deliberate retry. Placing a call on hold does not automatically authorize an AI assistant to take over.
End the call
POST /api/v1/calls/:conversationId/hangup ends the media session and changes the conversation to closed, recording closedAt. The response contains call and event. A configured post-call survey may finish before the remaining media is removed.
Ending the call and completing the customer request are separate actions. The Inbox can retain follow-up reminders while showing the ended call in Archive.
Transfer to another agent
POST /api/v1/conversations/:conversationId/assign-to-agent uses agentId and expectedVersion; note and force are optional. The target must be eligible for the channel and department. A normal transfer uses the acceptance workflow; it is not complete merely because the request was sent.
Use the current version from the call record. On a stale-version response, reload the call before deciding whether the transfer is still appropriate. A caller asking for a department does not grant permission to assign an unauthorized agent.