Call Results API

Authentication

All read endpoints require a Bearer API key with the voice:read scope. Webhook configuration (PUT) requires the voice:call scope. Create keys in your voice portal API keys page.

Authorization: Bearer mbn_live_...

Retrieve a single call

Get the full details of a completed call by its ID. The call ID is the callControlId returned when you placed the call, or found in the call log.

GET https://api.talktomyagent.io/v1/voice/calls/{callId}
Authorization: Bearer mbn_live_...

Response

{
  "data": {
    "id": "v3:abc123...",
    "direction": "outbound",
    "status": "completed",
    "endedReason": "callerHangup",
    "callerNumber": "+16473705600",
    "calledNumber": "+16475551234",
    "startedAt": "2026-05-25T14:30:00.000Z",
    "endedAt": "2026-05-25T14:35:12.000Z",
    "durationSeconds": 312,
    "recordingAvailable": true,
    "hasTranscript": true,
    "transcript": "[Agent] Hi, this is Sol... [Caller] Yeah...",
    "task": {
      "goal": "Collect $154.56 from Bobby",
      "script": "debt-collection",
      "facts": { "debtor_name": "Bobby", "amount_due": "$154.56" },
      "escalation": null
    },
    "usage": {
      "turnCount": 8,
      "inputTokens": 4521,
      "outputTokens": 2130
    },
    "quality": {
      "grade": "A",
      "p50ResponseLatencyMs": 340,
      "p95ResponseLatencyMs": 890
    }
  }
}

Call end reasons

The endedReason field tells you exactly why a call ended. Use it to route post-call workflows, flag failed calls, or track agent performance.

List calls

Retrieve your call history with cursor-based pagination. Filter by direction, end reason, or date range.

GET https://api.talktomyagent.io/v1/voice/calls?limit=25
Authorization: Bearer mbn_live_...

Query parameters

Pagination

The response includes a pagination object. When hasMore is true, pass the cursor value to the next request:

GET /v1/voice/calls?limit=25&cursor=eyJtcyI6MTcx...

Download recordings

Get a short-lived signed URL to download the call recording as an MP3 file. The URL expires in 5 minutes.

GET https://api.talktomyagent.io/v1/voice/calls/{callId}/recording
Authorization: Bearer mbn_live_...

Response

{
  "data": {
    "url": "https://storage.googleapis.com/...",
    "expiresAt": "2026-05-25T14:40:00.000Z"
  }
}

Returns 404 if no recording is available. The recordingAvailable field on the call object tells you in advance whether a recording exists.

Webhooks

Instead of polling, configure a webhook URL to receive a POST request automatically every time a call ends. You get the full call data, including the transcript and task results, the moment they are ready.

Configure your webhook

Use your agent's phone number (from) to identify which deployment to configure:

PUT https://api.talktomyagent.io/v1/voice/webhooks
Authorization: Bearer mbn_live_...
Content-Type: application/json

{
  "from": "+16473705600",
  "url": "https://your-server.com/webhooks/ttma",
  "secret": "your-signing-secret-at-least-32-characters-long",
  "enabled": true
}

Webhook payload

When a call ends, we POST the following JSON to your URL:

{
  "event": "call.ended",
  "deliveryId": "a1b2c3d4-...",
  "timestamp": "2026-05-25T14:35:12.000Z",
  "data": {
    "id": "v3:abc123...",
    "direction": "outbound",
    "status": "completed",
    "endedReason": "botHangup",
    "callerNumber": "+16473705600",
    "calledNumber": "+16475551234",
    "startedAt": "2026-05-25T14:30:00.000Z",
    "endedAt": "2026-05-25T14:35:12.000Z",
    "durationSeconds": 312,
    "recordingAvailable": true,
    "hasTranscript": true,
    "transcript": "[Agent] Hi, this is Sol...",
    "task": { "goal": "...", "facts": { ... } },
    "usage": { "turnCount": 8 },
    "quality": { "grade": "A" }
  }
}

The data object is the same shape as the single-call GET response. Headers included with every delivery:

Verify the signature

Every webhook delivery is signed with your secret using HMAC-SHA256. Always verify the signature before processing the payload:

// Node.js verification example
const crypto = require("crypto");

function verifyWebhook(rawBody, signatureHeader, secret) {
  // Parse the header: "t=1716648912,v1=abc123..."
  const parts = {};
  signatureHeader.split(",").forEach(p => {
    const [k, v] = p.split("=");
    parts[k] = v;
  });

  // Reject old deliveries (replay defense)
  const age = Math.abs(Date.now() / 1000 - Number(parts.t));
  if (age > 300) return false; // 5-minute window

  // Compute expected signature
  const expected = crypto
    .createHmac("sha256", secret)
    .update(parts.t + "." + rawBody)
    .digest("hex");

  // Constant-time comparison
  return crypto.timingSafeEqual(
    Buffer.from(expected, "hex"),
    Buffer.from(parts.v1, "hex")
  );
}

Delivery behavior

Webhooks wait for the recording to be ready before delivering (up to 60 seconds). If a recording doesn't arrive in time, the webhook fires anyway with recordingAvailable: false. Failed deliveries are retried up to 5 times. If your endpoint returns 410 Gone, the webhook is automatically disabled.

Using with n8n and automation tools

The webhook is standard JSON over HTTPS, making it easy to connect to any automation platform. For n8n:

1. Create a Webhook node with your URL

2. Configure your TTMA webhook to point at the n8n webhook URL

3. The payload arrives as structured JSON. No regex parsing needed. Access fields directly: {{ $json.data.endedReason }}, {{ $json.data.task.facts.debtor_name }}, etc.

Full API reference

For the complete endpoint specification including all fields, error codes, and rate limits, see the interactive API reference.