mirra-voice

name	mirra-voice
description	Use Mirra to voice call history, transcripts, and call metadata. Covers all Voice SDK operations via REST API.
allowed-tools	Read, Bash(curl:*, jq:*)

Mirra Voice

Voice call history, transcripts, and call metadata

Prerequisites

You need the user's API key. Ask for these if not provided:

• API_KEY: Mirra API key (generated in Mirra app > Settings > API Keys)
• API_URL: Defaults to https://api.fxn.world (only ask if they mention a custom server)

API Call Pattern

All operations use a single POST endpoint with the resource ID and method in the body:

curl -s -X POST "${API_URL}/api/sdk/v2/resources/call" \
  -H "Content-Type: application/json" \
  -H "x-api-key: ${API_KEY}" \
  -d '{
    "resourceId": "voice",
    "method": "{operation}",
    "params": { ...args }
  }' | jq .

Replace {operation} with the operation name from the table below.

Legacy alternative: POST ${API_URL}/api/sdk/v1/voice/{operation} with args as the request body also works but is not recommended for new integrations.

Available Operations

Operation	Description
getCallHistory	List voice calls the user participated in, with filters for scope, status, and date range. Return...
getCallDetails	Get full metadata and participant list for a specific call. Use the call's agoraCallId (from getC...
getCallTranscript	Get transcript segments for a voice call. Each segment contains the speaker, text, timing, and co...
getCallSummary	Get a human-readable formatted transcript summary for a voice call. Returns speaker-attributed te...
searchTranscripts	Full-text search across transcript segments. Searches the text content of all transcripts the use...
getActiveCall	Check if there is an active (in-progress) voice call in a specific chat or group. Returns call de...

Operation Details

getCallHistory

List voice calls the user participated in, with filters for scope, status, and date range. Returns call metadata (no transcript content). Use getCallTranscript or getCallSummary to retrieve transcript text for a specific call.

Arguments:

• scope (string, optional): Filter by call scope: "direct" (1-on-1 with AI), "group", "user" (user-to-user), or "meeting" (public shareable). Omit to return all scopes.
• status (string, optional): Filter by call status: "active", "ended", "cancelled". Defaults to all statuses.
• groupId (string, optional): Filter calls to a specific group by group ID.
• startDate (string, optional): Filter calls created on or after this date (ISO 8601, e.g. "2025-01-15T00:00:00Z").
• endDate (string, optional): Filter calls created on or before this date (ISO 8601).
• limit (number, optional): Maximum number of calls to return (default: 20, max: 100).
• offset (number, optional): Number of results to skip for pagination (default: 0).

Returns:

AdapterOperationResult: Returns { data: { count, offset, limit, calls[] } }. Each call has: id, agoraCallId, scope, status, createdAt, endedAt, durationMs, participantCount, videoEnabled, meetingTitle.

Example:

curl -s -X POST "${API_URL}/api/sdk/v2/resources/call" \
  -H "Content-Type: application/json" \
  -H "x-api-key: ${API_KEY}" \
  -d '{"resourceId":"voice","method":"getCallHistory","params":{"status":"ended","limit":5}}' | jq .

Example response:

{
  "count": 2,
  "offset": 0,
  "limit": 5,
  "calls": [
    {
      "id": "6789abc",
      "agoraCallId": "call_1750459861273_qbhg8we",
      "scope": "group",
      "status": "ended",
      "createdAt": "2025-06-01T10:00:00Z",
      "endedAt": "2025-06-01T10:45:00Z",
      "durationMs": 2700000,
      "participantCount": 3,
      "videoEnabled": false,
      "meetingTitle": ""
    }
  ]
}

getCallDetails

Get full metadata and participant list for a specific call. Use the call's agoraCallId (from getCallHistory) or the MongoDB _id.

Arguments:

• callId (string, required): The agoraCallId or MongoDB _id of the call.

Returns:

AdapterOperationResult: Returns { data: { id, agoraCallId, scope, status, createdAt, endedAt, durationMs, videoEnabled, meetingTitle, participants[] } }. Each participant has: userId, username, isGuest, guestName, joinedAt, leftAt, status.

Example:

curl -s -X POST "${API_URL}/api/sdk/v2/resources/call" \
  -H "Content-Type: application/json" \
  -H "x-api-key: ${API_KEY}" \
  -d '{"resourceId":"voice","method":"getCallDetails","params":{"callId":"call_1750459861273_qbhg8we"}}' | jq .

Example response:

{
  "id": "6789abc",
  "agoraCallId": "call_1750459861273_qbhg8we",
  "scope": "group",
  "status": "ended",
  "createdAt": "2025-06-01T10:00:00Z",
  "endedAt": "2025-06-01T10:45:00Z",
  "durationMs": 2700000,
  "videoEnabled": false,
  "meetingTitle": "",
  "participants": [
    {
      "userId": "user_001",
      "username": "alice",
      "isGuest": false,
      "guestName": "",
      "joinedAt": "2025-06-01T10:00:00Z",
      "leftAt": "2025-06-01T10:45:00Z",
      "status": "LEFT"
    }
  ]
}

getCallTranscript

Get transcript segments for a voice call. Each segment contains the speaker, text, timing, and confidence. Results are sorted by time. For a human-readable summary instead of raw segments, use getCallSummary.

Arguments:

• callId (string, required): The agoraCallId or MongoDB _id of the call.
• mirraTriggeredOnly (boolean, optional): If true, return only segments where a Mirra voice command was detected. Default: false.
• limit (number, optional): Maximum segments to return (default: 50, max: 200).
• offset (number, optional): Number of segments to skip for pagination (default: 0).

Returns:

AdapterOperationResult: Returns { data: { callId, count, offset, limit, totalSegments, segments[] } }. Each segment has: id, speakerUserId, speakerUsername, text, startMs, endMs, confidence, isFinal, mirraTriggered.

Example:

curl -s -X POST "${API_URL}/api/sdk/v2/resources/call" \
  -H "Content-Type: application/json" \
  -H "x-api-key: ${API_KEY}" \
  -d '{"resourceId":"voice","method":"getCallTranscript","params":{"callId":"call_1750459861273_qbhg8we","limit":10}}' | jq .

Example response:

{
  "callId": "call_1750459861273_qbhg8we",
  "count": 2,
  "offset": 0,
  "limit": 10,
  "totalSegments": 42,
  "segments": [
    {
      "id": "seg_001",
      "speakerUserId": "user_001",
      "speakerUsername": "alice",
      "text": "Hey, let's discuss the Q2 roadmap.",
      "startMs": 1200,
      "endMs": 3800,
      "confidence": 0.95,
      "isFinal": true,
      "mirraTriggered": false
    }
  ]
}

getCallSummary

Get a human-readable formatted transcript summary for a voice call. Returns speaker-attributed text in "Speaker: text" format. Useful for AI context, summaries, and recaps. For raw segment data, use getCallTranscript instead.

Arguments:

• callId (string, required): The agoraCallId or MongoDB _id of the call.
• maxLength (number, optional): Maximum character length of the summary (default: 2000). Transcript is truncated with "[Transcript truncated...]" if it exceeds this.
• startMs (number, optional): Only include segments starting at or after this millisecond offset from call start.
• endMs (number, optional): Only include segments ending at or before this millisecond offset from call start.

Returns:

AdapterOperationResult: Returns { data: { callId, summary, characterCount } }. The summary is a formatted string with "Speaker: text" lines.

Example:

curl -s -X POST "${API_URL}/api/sdk/v2/resources/call" \
  -H "Content-Type: application/json" \
  -H "x-api-key: ${API_KEY}" \
  -d '{"resourceId":"voice","method":"getCallSummary","params":{"callId":"call_1750459861273_qbhg8we"}}' | jq .

Example response:

{
  "callId": "call_1750459861273_qbhg8we",
  "summary": "alice: Hey, let's discuss the Q2 roadmap.\nbob: Sure, I think we should prioritize mobile performance.\nalice: Agreed. Let's also look at the onboarding flow.",
  "characterCount": 158
}

searchTranscripts

Full-text search across transcript segments. Searches the text content of all transcripts the user has access to. Results include the call context and matching segments.

Arguments:

• query (string, required): Text to search for in transcript content (case-insensitive substring match).
• groupId (string, optional): Limit search to transcripts from calls in a specific group.
• startDate (string, optional): Only search transcripts from calls created on or after this date (ISO 8601).
• endDate (string, optional): Only search transcripts from calls created on or before this date (ISO 8601).
• limit (number, optional): Maximum number of matching segments to return (default: 20, max: 100).

Returns:

AdapterOperationResult: Returns { data: { query, count, results[] } }. Each result has: segmentId, callId (agoraCallId), speakerUsername, text, startMs, confidence, callCreatedAt.

Example:

curl -s -X POST "${API_URL}/api/sdk/v2/resources/call" \
  -H "Content-Type: application/json" \
  -H "x-api-key: ${API_KEY}" \
  -d '{"resourceId":"voice","method":"searchTranscripts","params":{"query":"roadmap","limit":5}}' | jq .

Example response:

{
  "query": "roadmap",
  "count": 1,
  "results": [
    {
      "segmentId": "seg_001",
      "callId": "call_1750459861273_qbhg8we",
      "speakerUsername": "alice",
      "text": "Hey, let's discuss the Q2 roadmap.",
      "startMs": 1200,
      "confidence": 0.95,
      "callCreatedAt": "2025-06-01T10:00:00Z"
    }
  ]
}

getActiveCall

Check if there is an active (in-progress) voice call in a specific chat or group. Returns call details if active, or an empty result if no call is in progress.

Arguments:

• chatInstanceId (string, optional): Check for an active call in a specific chat instance.
• groupId (string, optional): Check for an active call in a specific group. Provide either chatInstanceId or groupId.

Returns:

AdapterOperationResult: Returns { data: { hasActiveCall, call? } }. If active, call contains: id, agoraCallId, scope, status, createdAt, participantCount, videoEnabled.

Example:

curl -s -X POST "${API_URL}/api/sdk/v2/resources/call" \
  -H "Content-Type: application/json" \
  -H "x-api-key: ${API_KEY}" \
  -d '{"resourceId":"voice","method":"getActiveCall","params":{"groupId":"group_123"}}' | jq .

Example response:

{
  "hasActiveCall": true,
  "call": {
    "id": "6789abc",
    "agoraCallId": "call_1750459861273_qbhg8we",
    "scope": "group",
    "status": "active",
    "createdAt": "2025-06-01T11:30:00Z",
    "participantCount": 2,
    "videoEnabled": false
  }
}

Response Format

All SDK responses return the operation payload wrapped in a standard envelope:

{
  "success": true,
  "data": { ... }
}

The data field contains the operation result. Error responses include:

{
  "success": false,
  "error": {
    "code": "ERROR_CODE",
    "message": "Human-readable error message"
  }
}

Tips

• Use jq . to pretty-print responses, jq .data to extract just the payload
• For list operations, results are in data.results or directly in data (check examples)
• Pass --fail-with-body to curl to see error details on HTTP failures
• Store the API key in a variable: export API_KEY="your-key"