Calls Live

Calls are conversations with channel = "call". Each call carries an event timeline (ringing, answered, ended, voicemail_left) plus the standard conversation fields. AI features (Smart Hold, AI Receptionist) layer on top.

List calls

Cursor-paginated list. Filters: status, assigneeId, departmentId, phoneNumberId, visitorId.

Code samples

curl 'https://app.message.com/api/v1/calls?status=open' \
  -H 'Authorization: Bearer YOUR_WORKSPACE_JWT'

const res = await fetch('https://app.message.com/api/v1/calls?status=open', {
  headers: { Authorization: 'Bearer ' + token }
});
const { calls } = await res.json();

import requests
r = requests.get(
    "https://app.message.com/api/v1/calls",
    headers={"Authorization": f"Bearer {token}"},
    params={"status": "open"},
)
calls = r.json()["calls"]

require "net/http"
require "json"
uri = URI("https://app.message.com/api/v1/calls?status=open")
res = Net::HTTP.start(uri.host, uri.port, use_ssl: true) do |http|
  req = Net::HTTP::Get.new(uri)
  req["Authorization"] = "Bearer #{token}"
  http.request(req)
end
calls = JSON.parse(res.body)["calls"]

<?php
$ctx = stream_context_create([
  "http" => ["method" => "GET", "header" => "Authorization: Bearer $token"]
]);
$calls = json_decode(file_get_contents("https://app.message.com/api/v1/calls?status=open", false, $ctx), true)["calls"];

Get one call

Returns the call record plus the full event timeline.

{
  "id": "uuid",
  "version": 4,
  "channel": "call",
  "status": "open",
  "fromE164": "+14155550100",
  "toE164": "+14155550199",
  "assignedAgentId": "uuid",
  "phoneNumberId": "uuid",
  "voicemailId": null,
  "events": [
    { "eventType": "ringing", "createdAt": "2026-05-13T15:00:00Z", "fromE164": "+14155550100" },
    { "eventType": "answered", "agentId": "uuid", "createdAt": "2026-05-13T15:00:08Z" },
    { "eventType": "ended", "createdAt": "2026-05-13T15:01:32Z", "duration_ms": 84000, "recordingUrl": "https://..." }
  ],
  "createdAt": "2026-05-13T15:00:00Z"
}

Event types

Answer a call

Marks the call as answered by the calling agent. The carrier-side answer happens over WebRTC in the dashboard; this endpoint records the metadata. Returns 200.

Hang up

Ends the call cleanly. The conversation status moves to solved. ended event is appended.

Hold and resume

Toggle hold. Holding triggers the configured hold music or, above the Smart Hold threshold, the AI hold experience.

Transfer

Move the call to another agent or department. Same handshake semantics as conversation transfer.

{
  "agentId": "uuid",
  "expectedVersion": 4
}

Recording

Mid-call recording control. Whether recording starts automatically is a per-phone-number setting. Recordings are stored in DigitalOcean Spaces; the URL appears on the ended event.

Errors

Common pitfalls

• Polling for incoming calls. Subscribe to call:ringing on the agent namespace. The REST list endpoint is for backfill only.
• Assuming recording is always on. Recording is per-phone-number. Check the recordingPolicy field on the phone-number record before relying on a recording URL.
• Confusing call status with event type. Status is the conversation state (open, solved). Event type is a specific transition in the call timeline.