Speko Docs
API Reference

Call control

Programmable human calling: dial, read, and command browser + PSTN call legs by controlId.

POST
/v1/voice/calls

Authorization

bearerAuth
AuthorizationBearer <token>

In: header

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

Response Body

application/json

application/json

application/json

application/json

application/json

{
  "call": {
    "id": "string",
    "direction": "inbound",
    "status": "initiating",
    "answeredAt": "2019-08-24T14:15:22Z",
    "endedAt": "2019-08-24T14:15:22Z",
    "endReason": "string",
    "legs": [
      {
        "id": "string",
        "controlId": "string",
        "callId": "string",
        "kind": "browser",
        "direction": "inbound",
        "status": "initiating",
        "brokerId": "string",
        "phoneNumber": "string",
        "muted": true,
        "onHold": true,
        "answeredAt": "2019-08-24T14:15:22Z",
        "endedAt": "2019-08-24T14:15:22Z",
        "endReason": "string",
        "createdAt": "2019-08-24T14:15:22Z"
      }
    ],
    "createdAt": "2019-08-24T14:15:22Z"
  },
  "join": {
    "token": "string",
    "url": "string",
    "identity": "string",
    "roomName": "string",
    "expiresAt": "2019-08-24T14:15:22Z"
  }
}
{
  "error": "Invalid request",
  "code": "VALIDATION_ERROR",
  "issues": [
    {
      "path": "to",
      "message": "Required"
    }
  ],
  "retryable": false,
  "docs_url": "https://docs.speko.dev/errors/validation_error"
}
{
  "error": "Unauthorized",
  "code": "UNAUTHORIZED"
}
{
  "error": "This workspace started 60 outbound calls in the last minute, the most it may start per minute. No call was placed. Retry in 12 seconds, or contact support to raise the limit.",
  "code": "OUTBOUND_RATE_LIMITED",
  "scope": "per_minute",
  "limit": 60,
  "retryAfterSeconds": 12
}
{
  "error": "human calling is not enabled for this organization",
  "code": "HUMAN_CALLING_DISABLED"
}
GET
/v1/voice/calls

Authorization

bearerAuth
AuthorizationBearer <token>

In: header

Query Parameters

status?string
Value in"initiating" | "ringing" | "active" | "ended" | "declined" | "missed" | "cancelled" | "failed"
direction?string
Value in"inbound" | "outbound" | "internal"
brokerId?string

Calls with a browser leg owned by this broker.

limit?integer
Range1 <= value <= 200

Response Body

application/json

application/json

application/json

application/json

{
  "calls": [
    {
      "id": "string",
      "direction": "inbound",
      "status": "initiating",
      "answeredAt": "2019-08-24T14:15:22Z",
      "endedAt": "2019-08-24T14:15:22Z",
      "endReason": "string",
      "legs": [
        {
          "id": "string",
          "controlId": "string",
          "callId": "string",
          "kind": "browser",
          "direction": "inbound",
          "status": "initiating",
          "brokerId": "string",
          "phoneNumber": "string",
          "muted": true,
          "onHold": true,
          "answeredAt": "2019-08-24T14:15:22Z",
          "endedAt": "2019-08-24T14:15:22Z",
          "endReason": "string",
          "createdAt": "2019-08-24T14:15:22Z"
        }
      ],
      "createdAt": "2019-08-24T14:15:22Z"
    }
  ]
}
{
  "error": "Invalid request",
  "code": "VALIDATION_ERROR",
  "issues": [
    {
      "path": "to",
      "message": "Required"
    }
  ],
  "retryable": false,
  "docs_url": "https://docs.speko.dev/errors/validation_error"
}
{
  "error": "Unauthorized",
  "code": "UNAUTHORIZED"
}
{
  "error": "human calling is not enabled for this organization",
  "code": "HUMAN_CALLING_DISABLED"
}
GET
/v1/voice/calls/{callId}

Authorization

bearerAuth
AuthorizationBearer <token>

In: header

Path Parameters

callId*string

Call id.

Response Body

application/json

application/json

application/json

application/json

{
  "id": "string",
  "direction": "inbound",
  "status": "initiating",
  "answeredAt": "2019-08-24T14:15:22Z",
  "endedAt": "2019-08-24T14:15:22Z",
  "endReason": "string",
  "legs": [
    {
      "id": "string",
      "controlId": "string",
      "callId": "string",
      "kind": "browser",
      "direction": "inbound",
      "status": "initiating",
      "brokerId": "string",
      "phoneNumber": "string",
      "muted": true,
      "onHold": true,
      "answeredAt": "2019-08-24T14:15:22Z",
      "endedAt": "2019-08-24T14:15:22Z",
      "endReason": "string",
      "createdAt": "2019-08-24T14:15:22Z"
    }
  ],
  "createdAt": "2019-08-24T14:15:22Z"
}
{
  "error": "Unauthorized",
  "code": "UNAUTHORIZED"
}
{
  "error": "not found",
  "code": "NOT_FOUND"
}
{
  "error": "human calling is not enabled for this organization",
  "code": "HUMAN_CALLING_DISABLED"
}
GET
/v1/voice/calls/{callId}/events

Authorization

bearerAuth
AuthorizationBearer <token>

In: header

Path Parameters

callId*string

Call id.

Response Body

application/json

application/json

application/json

application/json

{
  "events": [
    {
      "id": "string",
      "type": "call.initiated",
      "callId": "string",
      "controlId": "string",
      "payload": {},
      "occurredAt": "2019-08-24T14:15:22Z"
    }
  ]
}
{
  "error": "Unauthorized",
  "code": "UNAUTHORIZED"
}
{
  "error": "not found",
  "code": "NOT_FOUND"
}
{
  "error": "human calling is not enabled for this organization",
  "code": "HUMAN_CALLING_DISABLED"
}
POST
/v1/voice/legs/{controlId}/join

Authorization

bearerAuth
AuthorizationBearer <token>

In: header

Path Parameters

controlId*string

Leg control id — the opaque command handle returned on every leg (the Telnyx call_control_id equivalent).

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

Response Body

application/json

application/json

application/json

application/json

{
  "token": "string",
  "url": "string",
  "identity": "string",
  "roomName": "string",
  "expiresAt": "2019-08-24T14:15:22Z"
}
{
  "error": "Unauthorized",
  "code": "UNAUTHORIZED"
}
{
  "error": "not found",
  "code": "NOT_FOUND"
}
{
  "error": "human calling is not enabled for this organization",
  "code": "HUMAN_CALLING_DISABLED"
}
POST
/v1/voice/legs/{controlId}/actions/{command}

Authorization

bearerAuth
AuthorizationBearer <token>

In: header

Path Parameters

controlId*string

Leg control id — the opaque command handle returned on every leg (the Telnyx call_control_id equivalent).

command*string
Value in"answer" | "hangup" | "bridge" | "hold" | "unhold" | "mute" | "unmute" | "dtmf" | "transfer"

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

Response Body

application/json

application/json

application/json

application/json

application/json

application/json

{
  "leg": {
    "id": "string",
    "controlId": "string",
    "callId": "string",
    "kind": "browser",
    "direction": "inbound",
    "status": "initiating",
    "brokerId": "string",
    "phoneNumber": "string",
    "muted": true,
    "onHold": true,
    "answeredAt": "2019-08-24T14:15:22Z",
    "endedAt": "2019-08-24T14:15:22Z",
    "endReason": "string",
    "createdAt": "2019-08-24T14:15:22Z"
  },
  "noop": true
}
{
  "error": "DTMF is only meaningful towards a PSTN leg",
  "code": "UNSUPPORTED_COMMAND"
}
{
  "error": "Unauthorized",
  "code": "UNAUTHORIZED"
}
{
  "error": "not found",
  "code": "NOT_FOUND"
}
{
  "error": "leg is not live",
  "code": "LEG_NOT_LIVE"
}
{
  "error": "human calling is not enabled for this organization",
  "code": "HUMAN_CALLING_DISABLED"
}