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

commandstringrequired

Possible values: [dial]

params

object

required

anyOf

Create a call with a URL

urlstringrequired

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.

Example: https://example.com/swml

fromstringrequired

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

Example: sip:from-sip@example-112233445566.sip.signalwire.com

tostringrequired

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

Example: sip:from-sip@example-112233445567.sip.signalwire.com

caller_idstring

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

Example: +1234567890

fallback_urlstring

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.

Example: https://example.com/fallback

Create a call with SWML

swmlstringrequired

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

Example: {'version': '1.0.0', 'sections': { 'main': [{ 'answer': { 'max_duration': 60 }},{ 'play': { 'urls': ['silence:2', 'say:Hello from SignalWire!']}}]}}

fromstringrequired

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

Example: sip:from-sip@example-112233445566.sip.signalwire.com

tostringrequired

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

Example: sip:from-sip@example-112233445567.sip.signalwire.com

caller_idstring

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

Example: +1234567890

fallback_urlstring

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.

Example: https://example.com/fallback

Responses

201

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

application/json

Schema

Schema

idstringrequired
The unique identifier of the call on SignalWire. This can be used to update the call programmatically.
Example: 3fa85f64-5717-4562-b3fc-2c963f66afa6
fromstringrequired
The origin number or address.
Example: sip:from-sip@example-112233445566.sip.signalwire.com
tostringrequired
The destination number or address.
Example: sip:from-sip@example-112233445567.sip.signalwire.com
directionstringrequired
The direction of the call.
Possible values: [outbound-api]
Example: outbound-api
statusstringrequired
The status of the call.
Possible values: [answered, queued, initiated, ringing, ending, ended]
Example: queued
durationintegerrequired
The duration of the call in seconds.
Example: 60
duration_msintegerrequired
The duration of the call in milliseconds.
Example: 60000
billable_durationintegerrequired
The billable duration of the call in seconds.
Example: 60
sourcestringrequired
Source of this call.
Possible values: [realtime_api]
Example: realtime_api
typestringrequired
Type of this call.
Possible values: [relay_pstn_call, relay_sip_call, relay_webrtc_call]
Example: relay_sip_call

charge

object[]

required

Details on charges associated with this call.

Array [

descriptionstringrequired

Description for this charge.

amountintegerrequired

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 [

typestringrequired

Error type.

codestringrequired

Error code.

messagestringrequired

Error details.

attributestringrequired

Request parameter associated with this error.

urlstringrequired

Link to developer resource for this error.

]

Example (from schema)

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