Create a call

Authentication

• Authorization header (bearer token, required) — Bearer authentication of the form Bearer <token>, where token is your auth token.

Request

Path parameters

• AccountSidstringrequired

Body (application/json)

This endpoint expects an object.

• fromstringrequiredThe calling party number
• toTargetrequiredDestination for call
• application_sidstringoptionalThe application to use to control this call. Either application_sid or call_hook is required.
• answerOnBridgebooleanoptionalIf set to true, the inbound call will ring until the number that was dialed answers the call, and at that point a 200 OK will be sent on the inbound leg. If false, the inbound call will be answered immediately as the outbound call is placed.
• call_hookWebhookoptional
• call_status_hookWebhookoptional
• fromHoststringoptionalThe hostname to put in the SIP From header of the INVITE
• timeoutintegeroptionalThe number of seconds to wait for call to be answered. Defaults to 60.
• timeLimitintegeroptionalThe max length of call in seconds
• codecslist of stringoptionalCodec names, in preference order, to offer on the outbound INVITE. Names are case-insensitive. When omitted the media server offers its default codecs. If any name is not supported the whole list is ignored, an error is logged and an alert is written, and default negotiation is used.
• tagobjectoptionalInitial set of customer-supplied metadata to associate with the call (see Wipple CPaaS 'tag' Function)
• headersobjectoptionalThe customer SIP headers to associate with the call
• sipRequestWithinDialogHookstringoptionalThe sip indialog hook to receive session messages
• speech_synthesis_vendorstringoptionalThe vendor for Text to Speech (required if application_sid is not used)
• speech_synthesis_languagestringoptionalThe language for Text to Speech (required if application_sid is not used)
• speech_synthesis_voicestringoptionalThe voice for Text to Speech (required if application_sid is not used)
• speech_recognizer_vendorstringoptionalThe vendor for Speech to Text (required if application_sid is not used)
• speech_recognizer_languagestringoptionalThe language for Speech to Text (required if application_sid is not used)
• amdamdoptional
• dual_streamsbooleanoptionalIf set to true, Wipple CPaaS generates an outbound INVITE whose SDP offer contains two audio media streams (two m=audio lines) instead of one. This is useful when the far end (for example a carrier or recording system) requires the inbound and outbound audio to be delivered on separate RTP streams. Defaults to false. Supported only when creating a call via the REST API (i.e. not available from the dial Function).

Response

201

call successfully created

• sidstringrequired

Errors

400 Bad Request Error

bad request

• any

Types

Target

• typeenumrequired
• Allowed values: phone, sip, user, teams
• numberstringoptionalA phone number to call (when type is phone)
• sipUristringoptionalA SIP URI to call (when type is sip)
• tenantstringoptionalMicrosoft Teams customer tenant domain name (when type is teams)
• trunkstringoptionalThe name of the Carrier that should be used to deliver this call (when type is phone)
• vmailbooleanoptionalDial directly into user's voicemail to leave a message (MS Teams only)
• overrideTostringoptionalA SIP URI that, if provided, will be used as the To header in the outbound INVITE (not needed in most cases)
• namestringoptionalThe name of a registered Wipple CPaaS user to call (when type is user)
• authTargetAuthoptional
• proxystringoptionalSIP Proxy to use for the outgoing INVITE

Webhook

• urlstringrequired
• webhook_sidstringoptional
• methodenumoptional
• Allowed values: get, post
• usernamestringoptional
• passwordstringoptional

amd

• actionHookstringoptionalWebhook to send AMD events.
• thresholdWordCountdoubleoptionalNumber of spoken words in a greeting that result in an amd_machine_detected result.
• digitCountdoubleoptionalNumber of digits in a greeting to trigger a amd_machine_detected result. 0 is off
• timersAmdTimersoptional

TargetAuth

• usernamestringoptionalThe username to use for SIP authentication, if challenged
• passwordstringoptionalThe password to use for SIP authentication, if challenged

AmdTimers

• decisionTimeoutMsdoubleoptionaldefault: 15000Time in milliseconds to wait before returning amd_decision_timeout.
• greetingCompletionTimeoutMsdoubleoptionaldefault: 2000Silence in milliseconds to wait for during greeting before returning amd_machine_stopped_speaking.
• noSpeechTimeoutMsdoubleoptionaldefault: 5000Time in milliseconds to wait for speech before returning amd_no_speech_detected.
• toneTimeoutMsdoubleoptionaldefault: 20000Time in milliseconds to wait to hear a tone.

Examples

Request

{
  "from": "815099990001",
  "to": {
    "type": "phone",
    "number": "+815099990003"
  }
}

Response

{
  "sid": "2531329f-fb09-4ef7-887e-84e648214436"
}

cURL

curl -X POST "https://{API_ENDPOINT}/v1/Accounts/AccountSid/Calls" \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
  "from": "815099990001",
  "to": {
    "type": "phone",
    "number": "+815099990003"
  }
}'

Python

import requests

url = "https://{API_ENDPOINT}/v1/Accounts/AccountSid/Calls"

payload = {
    "from": "815099990001",
    "to": {
        "type": "phone",
        "number": "+815099990003"
    }
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.json())

JavaScript

const url = 'https://{API_ENDPOINT}/v1/Accounts/AccountSid/Calls';
const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: '{"from":"815099990001","to":{"type":"phone","number":"+815099990003"}}'
};

try {
  const response = await fetch(url, options);
  const data = await response.json();
  console.log(data);
} catch (error) {
  console.error(error);
}