Create a Call

POST 
/calls

To create a new Call, you send a POST request to the Call resource with a payload including a dial command and additional nested params.

Request

application/json

Body

required

command stringrequired

Possible values: [dial]

params

object

required

anyOf

Create a call with a URL

url stringrequired

The URL to handle the call. This parameter allows you to specify a webhook or different route in your code containing SWML instructions for handling the call. Either url or swml must be included for a new call.

from stringrequired

The address that initiated the call. Can be either a E.164 formatted number (+xxxxxxxxxxx), or a SIP endpoint (sip:xxx@yyy.zzz).

to stringrequired

The address that received the call. Can be either a E.164 formatted number (+xxxxxxxxxxx), or a SIP endpoint (sip:xxx@yyy.zzz).

caller_id string

The number, in E.164 format, or identifier of the caller.

fallback_url string

The Fallback URL to handle the call. This parameter allows you to specify a backup webhook or different route in your code containing SWML instructions for handling the call.

Create a call with SWML

swml stringrequired

Inline SWML, passed as a string, containing SWML instructions for handling the call. Either url or swml must be included for a new call.

from stringrequired

The address that initiated the call. Can be either a E.164 formatted number (+xxxxxxxxxxx), or a SIP endpoint (sip:xxx@yyy.zzz).

to stringrequired

The address that received the call. Can be either a E.164 formatted number (+xxxxxxxxxxx), or a SIP endpoint (sip:xxx@yyy.zzz).

caller_id string

The number, in E.164 format, or identifier of the caller.

fallback_url string

The Fallback URL to handle the call. This parameter allows you to specify a backup webhook or different route in your code containing SWML instructions for handling the call.

Responses

201

The request has succeeded and a new resource has been created as a result.

application/json

Schema

Schema

id stringrequired

The unique identifier of the call on SignalWire. This can be used to update the call programmatically.

from stringrequired

The origin number or address.

to stringrequired

The destination number or address.

direction stringrequired

Possible values: [outbound-api]

The direction of the call.

status stringrequired

Possible values: [answered, queued, initiated, ringing, ending, ended]

The status of the call.

duration integerrequired

The duration of the call in seconds.

duration_ms integerrequired

The duration of the call in milliseconds.

billable_duration integerrequired

The billable duration of the call in seconds.

source stringrequired

Possible values: [realtime_api]

Source of this call.

type stringrequired

Possible values: [relay_pstn_call, relay_sip_call, relay_webrtc_call]

Type of this call.

charge

object[]

required

Details on charges associated with this call.

Array [

description stringrequired

Description for this charge.

amount integerrequired

Charged amount.

]

Example (from schema)

{
  "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "from": "sip:from-sip@example-112233445566.sip.signalwire.com",
  "to": "sip:from-sip@example-112233445567.sip.signalwire.com",
  "direction": "outbound-api",
  "status": "queued",
  "duration": 60,
  "duration_ms": 60000,
  "billable_duration": 60,
  "source": "realtime_api",
  "type": "relay_sip_call",
  "charge": [
    {
      "description": "string",
      "amount": 0
    }
  ]
}

401

Access is unauthorized.

application/json

Schema

Schema

string

Possible values: [Unauthorized]

404

The server cannot find the requested resource.

application/json

Schema

Schema

string

Possible values: [Not Found]

422

Client error

application/json

Schema

Schema

errors

object[]

required

Array [

type stringrequired

Error type.

code stringrequired

Error code.

message stringrequired

Error details.

attribute stringrequired

Request parameter associated with this error.

url stringrequired

Link to developer resource for this error.

]

Example (from schema)

{
  "errors": [
    {
      "type": "validation_error",
      "code": "http_url_required",
      "message": "url must be a valid http or https url",
      "attribute": "url",
      "url": "https://developer.signalwire.com/rest/overview/error-codes#http_url_required"
    }
  ]
}

Loading...