Call control

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

Authorization

bearerAuth

AuthorizationBearer <token>

In: header

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

brokerId*string

Match^[A-Za-z0-9][A-Za-z0-9._-]{0,127}$

to*string

Destination, E.164.

Match^\+[1-9]\d{1,14}$

from?string

Caller ID. Must be a number this organization owns; defaults to the org's first outbound-capable number.

Match^\+[1-9]\d{1,14}$

metadata?

Response Body

`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 body",
  "code": "VALIDATION_ERROR"
}

{
  "error": "Unauthorized",
  "code": "UNAUTHORIZED"
}

{
  "error": "human calling is not enabled for this organization",
  "code": "HUMAN_CALLING_DISABLED"
}

Authorization

bearerAuth

AuthorizationBearer <token>

In: header

Query Parameters

status?string

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`

{
  "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 body",
  "code": "VALIDATION_ERROR"
}

{
  "error": "Unauthorized",
  "code": "UNAUTHORIZED"
}

{
  "error": "human calling is not enabled for this organization",
  "code": "HUMAN_CALLING_DISABLED"
}

Authorization

bearerAuth

AuthorizationBearer <token>

In: header

Path Parameters

callId*string

Call id.

Response Body

`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"
}

Authorization

bearerAuth

AuthorizationBearer <token>

In: header

Path Parameters

callId*string

Call id.

Response Body

`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"
}

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.

brokerId*string

Match^[A-Za-z0-9][A-Za-z0-9._-]{0,127}$

Response Body

`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"
}

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

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

reason?string

hangup only. Recorded as the leg's endReason.

Lengthlength <= 120

digits?string

dtmf only. 0-9, *, #, ,, and w for a pause; max 64.

Match^[0-9*#w,]{1,64}$

bridgeTo?string

bridge only. controlId of the leg to bridge this one to.

to?string

transfer only. An E.164 number, or the controlId of another broker's leg.

mode?string

transfer only. blind hands off and drops the leg; warm opens a consultation room you complete with bridge.

Value in"blind" | "warm"

Response Body

`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"
}

201application/json

400application/json

401application/json

503application/json

200application/json

400application/json

401application/json

503application/json

200application/json

401application/json

404application/json

503application/json

200application/json

401application/json

404application/json

503application/json

200application/json

401application/json

404application/json

503application/json

200application/json

400application/json

401application/json

404application/json

409application/json

503application/json

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`