Create Call
Creates a new outbound phone call.
Request URL
POST
https://voice.bandwidth.com/api/v2/accounts/{accountId}/calls/
Basic Authentication
Bandwidth's Voice API leverages Basic Authentication with your Dashboard API Credentials. Read more about how Bandwidth secures endpoints in the Security & Credentials document.
Supported Parameters
Parameter | Description | Mandatory |
---|---|---|
from | A Bandwidth phone number on your account the call should come from (must be in E.164 format, like +15555551212 ). |
Yes |
to | The destination to call (must be an E.164 formatted number (e.g. +15555551212 ) or a SIP URI (e.g. sip:user@server.com ). |
Yes |
applicationId | The id of the application to associate this call with, for billing purposes. | Yes |
answerUrl | The full URL to send the Answer event to when the called party answers. This endpoint should return the first BXML document to be executed in the call. | Yes |
answerMethod | (optional) The HTTP method to use for the request to answerUrl . GET or POST. Default value is POST. |
No |
disconnectUrl | (optional) The URL to send the Disconnect event to when the call ends. This event does not expect a BXML as response. | No |
disconnectMethod | (optional) The HTTP method to use for the request to disconnectUrl . GET or POST. Default value is POST. |
No |
username | (optional) The username to send in the HTTP request to answerUrl and disconnectUrl . |
No |
password | (optional) The password to send in the HTTP request to answerUrl and disconnectUrl . |
No |
callTimeout | (optional) This is the timeout (in seconds) for the callee to answer the call. Can be any numeric value (including decimals) between 1 and 300. Default: 30 | No |
tag | (optional) A custom string that will be sent with this and all future callbacks unless overwritten by a future tag attribute or <Tag> verb, or cleared.May be cleared by setting tag="" Max length 256 characters. |
No |
answerFallbackUrl | (optional) A fallback url which, if provided, will be used to retry the answer callback delivery in case answerUrl fails to respond |
No |
answerFallbackMethod | (optional) The HTTP method to use to deliver the answer callback to answerFallbackUrl . GET or POST. Default value is POST. |
No |
fallbackUsername | (optional) The username to send in the HTTP request to answerFallbackUrl |
No |
fallbackPassword | (optional) The password to send in the HTTP request to answerFallbackUrl |
No |
callbackTimeout | (optional) This is the timeout (in seconds) to use when delivering callbacks for the call. Can be any numeric value (including decimals) between 1 and 25. Default: 15 | No |
uui | (optional) The value of the User-To-User header to send within the initial INVITE when calling a SIP URI. Must include the encoding parameter as specified in RFC 7433 . Only base64 and jwt encoding are currently allowed. This value, including the encoding specifier, may not exceed 256 characters. |
No |
NOTE: Any error that causes the call to be hung up (for example invalid BXML or rate limiting) will be delivered to the disconnectUrl
via a Disconnect event. This is currently the only way to receive user errors, so while disconnectUrl
is not mandatory, we highly recommend providing it so that user errors can be delivered.
Example 1 of 1: Create an outbound phone call
curl -X POST \
--url 'https://voice.bandwidth.com/api/v2/accounts/{accountId}/calls' \
-u '{username}:{password}' \
-H 'Content-type: application/json' \
--data-raw '
{
"from" : "+15555551212",
"to" : "+15555551313",
"answerUrl" : "http://www.myapp.com/hello",
"applicationId" : "7fc9698a-b04a-468b-9e8f-91238c0d0086"
}'
Responds
HTTP/1.1 201
Content-type: application/json
Location: https://voice.bandwidth.com/api/v2/accounts/55555555/calls/c-95ac8d6e-1a31c52e-b38f-4198-93c1-51633ec68f8d
{
"accountId" : "55555555",
"from" : "+19195551212",
"to" : "+19195551313",
"applicationId" : "7fc9698a-b04a-468b-9e8f-91238c0d0086",
"callId" : "c-95ac8d6e-1a31c52e-b38f-4198-93c1-51633ec68f8d",
"startTime" : "2019-06-20T15:54:22.234Z",
"callUrl" : "https://voice.bandwidth.com/api/v2/accounts/55555555/calls/c-95ac8d6e-1a31c52e-b38f-4198-93c1-51633ec68f8d",
"callTimeout" : 30,
"callbackTimeout" : 15,
"answerUrl" : "http://www.myapp.com/hello",
"answerMethod" : "POST",
"answerFallbackUrl" : null,
"answerFallbackMethod" : "POST",
"disconnectUrl" : null,
"disconnectMethod" : "POST",
"username" : null,
"password" : null,
"fallbackUsername" : null,
"fallbackPassword" : null,
"tag" : null
}
ApiCreateCallRequest createCallRequest = new ApiCreateCallRequest();
createCallRequest.setTo("+19195551313");
createCallRequest.setFrom("+19195551212");
createCallRequest.setAnswerUrl("http://www.myapp.com/hello");
createCallRequest.setApplicationId(VOICE_APPLICATION_ID); //String
try {
ApiResponse<ApiCallResponse> response = voiceClient.createCall(VOICE_ACCOUNT_ID, createCallRequest);
System.out.println(response.getResult().getCallId());
} catch (ApiException | IOException e) {
e.printStackTrace();
}
ApiCreateCallRequest apiCreateCallRequest = new ApiCreateCallRequest();
apiCreateCallRequest.From = "+19195551212";
apiCreateCallRequest.To = "+19195551313";
apiCreateCallRequest.AnswerUrl = "http://www.myapp.com/hello";
apiCreateCallRequest.ApplicationId = VOICE_APPLICATION_ID; //string
var response = voiceClient.CreateCall(VOICE_ACCOUNT_ID, apiCreateCallRequest);
Console.WriteLine(response.Data.CallId);
body = ApiCreateCallRequest.new
body.from = "+19195551212"
body.to = "+19195551313"
body.answer_url = "http://www.myapp.com/hello"
body.application_id = "7fc9698a-b04a-468b-9e8f-91238c0d0086"
begin
result = voice_client.create_call(account_id, :body => body)
puts result.data.call_id
rescue Exception => e
puts e
end
body = ApiCreateCallRequest()
body.mfrom = "+19195551212"
body.to = "+19195551313"
body.answer_url = "http://www.myapp.com/hello"
body.application_id = "7fc9698a-b04a-468b-9e8f-91238c0d0086"
try:
result = voice_client.create_call(account_id, body)
print(result.body.call_id)
except Exception as e:
print(e)
var body = new BandwidthVoice.ApiCreateCallRequest({
"from": "+19999999999",
"to": "+18888888888",
"applicationId": "123",
"answerUrl": "https://test.com",
"answerMethod": "POST",
"callTimeout": 30
});
try {
var response = await voiceController.createCall(accountId, body);
console.log(response);
catch (error) {
console.error(error);
}
$body = new BandwidthLib\Voice\Models\ApiCreateCallRequest();
$body->from = "+15554443333";
$body->to = "+15554442222";
$body->answerUrl = "https://test.com";
$body->applicationId = "3-6-4-b-4";
try {
$response = $voiceClient->createCall($accountId, $body);
print_r($response->getResult()->callId);
} catch (BandwidthLib\APIException $e) {
print_r($e);
}