RealSpeak API Reference

curl https://realspeak.ai/api/v1/agents \
  -H "Authorization: Bearer rs_live_sk_abc123..."

curl https://realspeak.ai/api/v1/agents \
  -H "Authorization: Bearer rs_live_sk_..."

# Response
{
  "agents": [
    {
      "id": "ag_abc123",
      "name": "Support Agent",
      "voiceName": "Ito",
      "llmModel": "claude-sonnet-4-5-20250514",
      "active": true,
      "phoneNumbers": [{ "id": "pn_1", "number": "+14155551234" }],
      "tools": [{ "id": "tl_1", "name": "lookup_order" }],
      "_count": { "callSessions": 47 },
      "createdAt": "2026-04-01T00:00:00Z"
    }
  ]
}

curl -X POST https://realspeak.ai/api/v1/agents \
  -H "Authorization: Bearer rs_live_sk_..." \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Support Agent",
    "systemPrompt": "You are a helpful support agent for Acme Inc...",
    "voiceName": "Kora",
    "firstMessage": "Hi, thanks for calling Acme! How can I help?",
    "webhookUrl": "https://yourapp.com/webhook",
    "tools": [{
      "name": "lookup_order",
      "description": "Look up an order by ID or email",
      "parameters": {
        "type": "object",
        "properties": {
          "orderId": { "type": "string", "description": "Order ID" },
          "email": { "type": "string", "description": "Customer email" }
        },
        "required": ["orderId"]
      }
    }]
  }'

curl -X PATCH https://realspeak.ai/api/v1/agents/ag_abc123 \
  -H "Authorization: Bearer rs_live_sk_..." \
  -H "Content-Type: application/json" \
  -d '{ "active": false, "voiceName": "Sebastian Lockwood" }'

# Response
{
  "calls": [{
    "id": "cs_xyz789",
    "agentId": "ag_abc123",
    "callerNumber": "+14155559876",
    "channel": "phone",
    "status": "completed",
    "startedAt": "2026-04-19T14:30:00Z",
    "endedAt": "2026-04-19T14:35:22Z",
    "durationSeconds": 322,
    "toolsUsed": ["lookup_order", "send_email"],
    "dominantEmotion": "Joy",
    "avgSentiment": 0.72,
    "summary": "Customer called about order status..."
  }],
  "total": 147,
  "limit": 50,
  "offset": 0
}

# Response includes:
{
  "call": {
    "id": "cs_xyz789",
    "transcript": [
      { "role": "agent", "content": "Hi, how can I help?", "timestamp": 0 },
      { "role": "user", "content": "I need to check my order", "timestamp": 3.2 }
    ],
    "prosodyTimeline": [
      {
        "timestamp": 3.2,
        "emotions": {
          "Joy": 0.12, "Anger": 0.02, "Sadness": 0.05,
          "Interest": 0.68, "Confusion": 0.31
        },
        "dominantEmotion": "Interest",
        "sentiment": 0.65
      }
    ],
    "toolsUsed": ["lookup_order"],
    "summary": "Customer inquired about order ORD-456...",
    "agent": { "id": "ag_abc123", "name": "Support Agent" }
  }
}

curl -X POST https://realspeak.ai/api/v1/numbers/purchase \
  -H "Authorization: Bearer rs_live_sk_..." \
  -H "Content-Type: application/json" \
  -d '{ "phone_number": "+14155551234" }'

curl -X PATCH https://realspeak.ai/api/v1/numbers/pn_123 \
  -H "Authorization: Bearer rs_live_sk_..." \
  -H "Content-Type: application/json" \
  -d '{ "agentId": "ag_abc123" }'

import crypto from 'crypto';

function verifyWebhook(body: string, signature: string, secret: string): boolean {
  const expected = crypto
    .createHmac('sha256', secret)
    .update(body)
    .digest('hex');
  return crypto.timingSafeEqual(
    Buffer.from(signature),
    Buffer.from(expected)
  );
}

// Incoming webhook payload
{
  "event": "call.started",
  "callId": "cs_xyz789",
  "agentId": "ag_abc123",
  "callerNumber": "+14155559876",
  "timestamp": "2026-04-19T14:30:00Z"
}

// Your response (all fields optional)
{
  "systemPrompt": "Override prompt for this caller...",
  "firstMessage": "Welcome back, Sarah!",
  "voice": { "provider": "HUME_AI", "name": "Kora" },
  "tools": [{ "name": "vip_lookup", "description": "...", "parameters": {...} }]
}

// Incoming
{
  "event": "tool_call",
  "callId": "cs_xyz789",
  "toolCallId": "tc_001",
  "name": "lookup_order",
  "parameters": { "orderId": "ORD-456" }
}

// Your response — simple result
{ "result": "Order ORD-456: shipped yesterday, tracking 1Z999AA..." }

// Or with action — transfer to human
{
  "result": "Transferring to a specialist now.",
  "action": "transfer",
  "destination": "+14155550000"
}

// Or hangup
{
  "result": "Thank you, goodbye!",
  "action": "hangup"
}

{
  "event": "prosody.update",
  "callId": "cs_xyz789",
  "timestamp": "2026-04-19T14:31:15Z",
  "emotions": {
    "Joy": 0.03, "Anger": 0.67, "Frustration": 0.72,
    "Sadness": 0.15, "Contempt": 0.41, "Disgust": 0.22,
    "Interest": 0.08, "Surprise": 0.05, "Fear": 0.11,
    "...": "48 dimensions total"
  },
  "dominantEmotion": "Frustration",
  "sentiment": 0.18
}

{
  "event": "call.ended",
  "callId": "cs_xyz789",
  "agentId": "ag_abc123",
  "callerNumber": "+14155559876",
  "duration": 322,
  "endedReason": "caller_hangup",
  "transcript": "Agent: Hi, how can I help?\nUser: I need to check...",
  "summary": "Customer called about order status. Issue resolved.",
  "toolsUsed": ["lookup_order", "send_email"],
  "prosody": {
    "avgSentiment": 0.72,
    "dominantEmotion": "Joy",
    "frustrationPeaks": 1,
    "emotionTimeline": [...]
  }
}

{
  "name": "issue_refund",
  "description": "Issue a refund for a customer payment",
  "parameters": {
    "type": "object",
    "properties": {
      "payment_id": {
        "type": "string",
        "description": "The Stripe payment ID"
      },
      "amount_cents": {
        "type": "number",
        "description": "Refund amount in cents. Omit for full refund."
      },
      "reason": {
        "type": "string",
        "enum": ["duplicate", "fraudulent", "requested_by_customer"],
        "description": "Reason for the refund"
      }
    },
    "required": ["payment_id"]
  }
}

curl -X POST https://realspeak.ai/api/v1/templates \
  -H "Authorization: Bearer rs_live_sk_..." \
  -H "Content-Type: application/json" \
  -d '{
    "templateId": "customer-support",
    "agentName": "Acme Support",
    "businessName": "Acme Inc"
  }'

curl -X POST https://realspeak.ai/api/v1/integrations \
  -H "Authorization: Bearer rs_live_sk_..." \
  -H "Content-Type: application/json" \
  -d '{
    "type": "stripe",
    "credentials": { "api_key": "sk_live_..." }
  }'

curl -X DELETE https://realspeak.ai/api/v1/integrations \
  -H "Authorization: Bearer rs_live_sk_..." \
  -H "Content-Type: application/json" \
  -d '{ "type": "stripe" }'

# Response
{
  "plan": "professional",
  "minutesUsed": 342,
  "minutesIncluded": 1000,
  "callsThisMonth": 89,
  "trialEndsAt": null,
  "overage": { "minutes": 0, "cost": "$0.00" }
}

{
  "error": "Agent not found"
}

<!-- Add to your website -->
<script src="https://realspeak.ai/widget.js"
        data-agent-id="ag_abc123">
</script>

<!-- Or initialize programmatically -->
<script>
  RealSpeak.init({
    agentId: "ag_abc123",
    position: "bottom-right",  // bottom-right | bottom-left
    theme: "light",            // light | dark
    primaryColor: "#1a1a2e",
  });
</script>