<Response>
  <Dial record="record-from-answer-dual"
        recordingStatusCallback="https://your-middleware.example.com/twilio-recording"
        recordingStatusCallbackEvent="completed">
    +15551234567
  </Dial>
</Response>

curl -X POST https://api.speakai.co/v1/media/upload \
  -H "x-speakai-key: $SPEAK_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Twilio call REc...",
    "url": "https://USER:[email protected]/.../Recordings/REc....mp3",
    "mediaType": "audio",
    "sourceLanguage": "en-US",
    "tags": "twilio,outbound"
  }'

import express from "express";
const app = express();
app.use(express.urlencoded({ extended: false }));

app.post("/twilio-recording", async (req, res) => {
  const { RecordingUrl, RecordingSid, From, To } = req.body;
  if (!RecordingUrl) return res.sendStatus(400);

  const auth = Buffer
    .from(`${process.env.TWILIO_SID}:${process.env.TWILIO_AUTH_TOKEN}`)
    .toString("base64");

  const upload = await fetch("https://api.speakai.co/v1/media/upload", {
    method: "POST",
    headers: {
      "x-speakai-key": process.env.SPEAK_API_KEY,
      "Content-Type": "application/json",
      Authorization: `Basic ${auth}`,
    },
    body: JSON.stringify({
      name: `Twilio call ${From} to ${To} (${RecordingSid})`,
      url: `${RecordingUrl}.mp3`,
      mediaType: "audio",
      sourceLanguage: "en-US",
      tags: `twilio,${From}`,
    }),
  });

  res.sendStatus(upload.ok ? 200 : 502);
});

app.listen(3000);

import os, requests
from flask import Flask, request

app = Flask(__name__)

@app.post("/twilio-recording")
def twilio_recording():
    data = request.form
    recording_url = data.get("RecordingUrl")
    if not recording_url:
        return ("", 400)

    upload = requests.post(
        "https://api.speakai.co/v1/media/upload",
        headers={
            "x-speakai-key": os.environ["SPEAK_API_KEY"],
            "Content-Type": "application/json",
        },
        auth=(os.environ["TWILIO_SID"], os.environ["TWILIO_AUTH_TOKEN"]),
        json={
            "name": f"Twilio call {data.get('From')} to {data.get('To')} ({data.get('RecordingSid')})",
            "url": f"{recording_url}.mp3",
            "mediaType": "audio",
            "sourceLanguage": "en-US",
            "tags": f"twilio,{data.get('From')}",
        },
        timeout=30,
    )
    return ("", 200 if upload.ok else 502)

// Body Speak posts to your callback (verified 2026-05-07)
// URL also gets ?eventType=media.analyzed&mediaId=<id> appended.
{
  "eventType": "media.analyzed",
  "state": "processed",
  "mediaId": "14c8dd9c0a89"
}

// To get transcript + sentiment + speakers, fetch:
// GET https://api.speakai.co/v1/media/insight/<mediaId>
// (response shape excerpt below)
{
  "status": "success",
  "data": {
    "mediaId": "14c8dd9c0a89",
    "name": "Acme Corp - Discovery",
    "mediaType": "video",
    "duration": { "inSecond": 1265, "start": "00:00:01.280", "end": "00:21:00.995" },
    "sourceLanguage": "en-US",
    "state": "processed",
    "tags": ["meeting-assistant"],
    "sentiment": [{
      "document": {
        "Compound": 25.10,
        "Negative": 3.22,
        "Neutral": 41.66,
        "Positive": 55.10
      },
      "sentences": [...]
    }],
    "insight": {
      "transcript": [...],
      "speakers": [...],
      "brands": [...]
    },
    "mediaUrl": "https://...",
    "createdAt": "2026-05-06T17:22:51.269Z"
  }
}

<Response>
  <Say>Thanks for calling. This call may be recorded for quality.</Say>
  <Dial record="record-from-answer-dual"
        recordingStatusCallback="https://your-middleware.example.com/twilio-support">
    <Queue>support-queue</Queue>
  </Dial>
</Response>

# Magic Prompt is async. Step 1 fires the job; step 2 polls until completed.
curl -X POST https://api.speakai.co/v1/prompt/ \
  -H "x-speakai-key: $SPEAK_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "mediaIds": ["86a36b59b38e"],
    "prompt": "Score this support call on (1) issue resolution, (2) agent empathy, (3) first-call resolution. Return JSON with scores 0-10 and 1-sentence justifications.",
    "isStream": false,
    "isIndividualPrompt": true
  }'

# Poll every ~1s (typical completion 2-3s):
curl "https://api.speakai.co/v1/prompt/messages?mediaIds=86a36b59b38e&pageSize=1" \
  -H "x-speakai-key: $SPEAK_API_KEY"
# -> data.history[0].messages[0] = { state: "completed", answer: "..." }

// Magic Prompt is async: POST starts the job, GET polls for the answer.
async function scoreCall(mediaId) {
  const headers = { "x-speakai-key": process.env.SPEAK_API_KEY };

  await fetch("https://api.speakai.co/v1/prompt/", {
    method: "POST",
    headers: { ...headers, "Content-Type": "application/json" },
    body: JSON.stringify({
      mediaIds: [mediaId],
      prompt: "Score this support call on (1) issue resolution, " +
              "(2) agent empathy, (3) first-call resolution. " +
              "Return JSON with scores 0-10 and 1-sentence justifications.",
      isStream: false,
      isIndividualPrompt: true,
    }),
  });

  for (let i = 0; i < 20; i++) {
    await new Promise(r => setTimeout(r, 1000));
    const r = await fetch(
      `https://api.speakai.co/v1/prompt/messages?mediaIds=${mediaId}&pageSize=1`,
      { headers }
    );
    const j = await r.json();
    const msg = j?.data?.history?.[0]?.messages?.[0];
    if (msg && msg.state === "completed") return msg.answer;
  }
  return null;
}

// inside your Flex Plugin React component
async function fetchInsights(recordingSid) {
  const mediaId = await mappingStore.lookup(recordingSid);
  const resp = await fetch(
    `https://api.speakai.co/v1/media/insight/${mediaId}`,
    { headers: { "x-speakai-key": SPEAK_API_KEY } }
  );
  const { topics, sentiment, magicPromptResponse } = await resp.json();
  return { topics, sentiment, magicPromptResponse };
}

# Claude Desktop / Claude Code (auto-detects your installation)
npx @speakai/mcp-server init

# Paste your Speak API key when prompted. Setup takes about 2 minutes.

# Claude.ai (web) and ChatGPT MCP connector
# Settings > Integrations > Add MCP Server
# Remote URL:    https://api.speakai.co/v1/mcp
# Auth header:   x-speakai-key: YOUR_SPEAK_API_KEY

# Verify the connection responds (optional sanity check):
curl -s https://api.speakai.co/v1/mcp \
  -H "x-speakai-key: $SPEAK_API_KEY" \
  -H "Accept: application/json"