Objective-C / Plivo REST API / Make an outbound call
Back to Collection Items
#import <CkoHttp.h>
#import <CkoJsonObject.h>
#import <CkoHttpResponse.h>
// This example assumes the Chilkat API to have been previously unlocked.
// See Global Unlock Sample for sample code.
CkoHttp *http = [[CkoHttp alloc] init];
BOOL success;
http.BasicAuth = YES;
http.Login = @"{{auth_id}}";
http.Password = @"password";
// Use this online tool to generate code from sample JSON: Generate Code to Create JSON
// The following JSON is sent in the request body.
// {
// "from": "+14152224444",
// "to": "+14152223333",
// "answer_url": "https://s3.amazonaws.com/plivosamplexml/play_url.xml",
// "answer_method": "GET",
// "ring_url": "https://www.foo.com/ring.url",
// "ring_method": "POST",
// "hangup_url": "https://www.foo.com/hangup.url",
// "hangup_method": "POST",
// "fallback_url": "https://www.foo.com/fallback.url",
// "fallback_method": "POST",
// "caller_name": "friendly_name",
// "send_digits": "1w2W3",
// "send_on_preanswer": "true",
// "time_limit": "300"
// }
CkoJsonObject *json = [[CkoJsonObject alloc] init];
[json UpdateString: @"from" value: @"+14152224444"];
[json UpdateString: @"to" value: @"+14152223333"];
[json UpdateString: @"answer_url" value: @"https://s3.amazonaws.com/plivosamplexml/play_url.xml"];
[json UpdateString: @"answer_method" value: @"GET"];
[json UpdateString: @"ring_url" value: @"https://www.foo.com/ring.url"];
[json UpdateString: @"ring_method" value: @"POST"];
[json UpdateString: @"hangup_url" value: @"https://www.foo.com/hangup.url"];
[json UpdateString: @"hangup_method" value: @"POST"];
[json UpdateString: @"fallback_url" value: @"https://www.foo.com/fallback.url"];
[json UpdateString: @"fallback_method" value: @"POST"];
[json UpdateString: @"caller_name" value: @"friendly_name"];
[json UpdateString: @"send_digits" value: @"1w2W3"];
[json UpdateString: @"send_on_preanswer" value: @"true"];
[json UpdateString: @"time_limit" value: @"300"];
CkoHttpResponse *resp = [http PostJson3: @"https://api.plivo.com/v1/Account/<auth_id>/Call/" contentType: @"application/json" json: json];
if (http.LastMethodSuccess == NO) {
NSLog(@"%@",http.LastErrorText);
return;
}
NSLog(@"%d",[resp.StatusCode intValue]);
NSLog(@"%@",resp.BodyStr);
Curl Command
curl -X POST
-u '{{auth_id}}:password'
-d '{
"from":"+14152224444",
"to":"+14152223333",
"answer_url":"https://s3.amazonaws.com/plivosamplexml/play_url.xml",
"answer_method":"GET",
"ring_url":"https://www.foo.com/ring.url",
"ring_method":"POST",
"hangup_url":"https://www.foo.com/hangup.url",
"hangup_method":"POST",
"fallback_url":"https://www.foo.com/fallback.url",
"fallback_method":"POST",
"caller_name":"friendly_name",
"send_digits":"1w2W3",
"send_on_preanswer":"true",
"time_limit":"300"
}'
https://api.plivo.com/v1/Account/<auth_id>/Call/
Postman Collection Item JSON
{
"name": "Make an outbound call",
"request": {
"method": "POST",
"header": [
],
"body": {
"mode": "raw",
"raw": "{\n \"from\":\"+14152224444\",\n \"to\":\"+14152223333\",\n \"answer_url\":\"https://s3.amazonaws.com/plivosamplexml/play_url.xml\",\n \"answer_method\":\"GET\",\n \"ring_url\":\"https://www.foo.com/ring.url\",\n \"ring_method\":\"POST\",\n \"hangup_url\":\"https://www.foo.com/hangup.url\",\n \"hangup_method\":\"POST\",\n \"fallback_url\":\"https://www.foo.com/fallback.url\",\n \"fallback_method\":\"POST\",\n \"caller_name\":\"friendly_name\",\n \"send_digits\":\"1w2W3\",\n \"send_on_preanswer\":\"true\",\n \"time_limit\":\"300\"\n}",
"options": {
"raw": {
"language": "json"
}
}
},
"url": {
"raw": "https://api.plivo.com/v1/Account/{{auth_id}}/Call/",
"protocol": "https",
"host": [
"api",
"plivo",
"com"
],
"path": [
"v1",
"Account",
"{{auth_id}}",
"Call",
""
]
},
"description": "This method allows you to initiate an outbound call. The call can be made to a PSTN number or a SIP endpoint. This method also enables you to make bulk calls (Simultaneous calls).\n\nBelow is the list of arguments that can be passed in this API request, more information can be found [here](https://www.plivo.com/docs/voice/api/call#make-a-call)\n\n| Arguments | Description | Required/Conditional/Optional |\n| :--- | :----: | ---: |\n| from | The phone number that needs to be used as the caller ID for the call. The format should be the country code followed by the number. Example: 15677654321 (for United States)| Required |\n| to | The destination that needs to be called. The destination can either be a regular number or a SIP endpoint. The regular number should be provided with the country code followed by the number to be called. Example: 15677654321. <br /> In case you are calling a SIP endpoint, the to field should be a valid SIP URI. Example: sip:john1234@phone.plivo.com. <br /> Multiple numbers and endpoints can be initiated at once (bulk calls) by using the delimiter <. For example in case you want to call two numbers and one SIP endpoint, the ‘to’ field can be specified as follows: 15677654321<15673464321<sip:john1234@phone.plivo.com. <br />| Required |\n| answer_url | The URL that will be invoked by Plivo once the call is answered. This URL should return an XML with valid Plivo XML to perform the desired actions once the call is answered | Required |\n| answer_method | The HTTP verb that should be used to invoke the answer_url. This defaults to POST | Optional |\n| ring_url | An optional URL to which Plivo will notify once the call starts ringing | Optional |\n| ring_method | The HTTP verb that should be used to invoke the ring_url. This defaults to POST | Optional |\n| hangup_url | An optional URL to which Plivo will notify once the call is hung up | Optional |\n| hangup_method | The HTTP verb that should be used to invoke the hangup_url. This defaults to POST | Optional |\n| fallback_url | This is the URL that will be tried in case the answer_url is not reachable. We retry answer_url thrice to fetch a valid XML file. In case all three attempts fail to return a valid XML or after a timeout of 60 seconds whichever is earlier, fallback_url will be invoked | Optional |\n| fallback_method | The HTTP verb that should be used to invoke the fallback_url. This defaults to POST | Optional |\n| caller_name | If set to a string, caller name will be set to this string value.Allowed values - Any string. Defaults to Caller's caller_name. Character limit - 50 characters. | Optional |\n| send_digits | This flag allows you to send digits once the call is connected. The common use case is to dial to an extension.Plivo will dial the number, and when the automated system picks up, sends the DTMF tones to connect to the extension.<br />You can choose how long to wait before sending the digits. Using character ‘w’ waits for 0.5 seconds and ‘W’ waits for 1 seconds.<br />For example setting this parameter to 1w2W3 sends digit 1, waits for 0.5 seconds, sends digit 2, waits for 1 second and sends digit 3.<br />The duration of the tone when the digit is sent can be configured by appending the duration (in ms) with the @ character.For example setting 123@1000 will send the digits 123 with a tone duration of 1000 milliseconds. | Optional |\n| send_on_preanswer | This takes boolean values ‘true’ and ‘false’ and is applicable only if send_digits is set. In case it is set to ‘true’ the digits would be sent at preanswer stage. The default value is false. | Optional |\n| time_limit | Sets a limit on the maximum duration of a call. The time limit is calculated starting from the time the call is answered. The time_limit is provided in seconds and it needs to be positive integer. Defaults to 14400 seconds(4 hours). | Optional |\n| hangup_on_ring | Sets a limit on the maximum duration of the call similar to time_limit. But instead of calculating the limit from the time call is answered, this parameter calculates the limit from the time call starts ringing. The hangup_on_ring value is also provided in seconds and it needs to be a positive integer. | Optional |\n| machine_detection | This parameter is used to detect whether the call has been answered by a machine.<br />If set to ‘true’, in case machine is detected at the beginning of the call, any URL that is invoked by the call (answer_url, hangup_url etc) will be POSTed with the ‘machine’ parameter set to true.<br />In case you want to hangup the call in case machine is detected, you can set this parameter to ‘hangup’. This will hangup the call and POST to the hangup_url with ‘machine’ parameter set as true. | Optional |\n| machine_detection_time | This defines the time that is allotted to decide whether machine is detected or not. This is specified in milliseconds and takes a value between 2000 and 10000 both inclusive. The default value is 5000ms. | Optional |\n| machine_detection_url | The URL which will be invoked with machine detection parameters. The list of parameters sent with the request are described in asynchronous machine detection section below. These parameters should be used to make machine detection asynchronous. | Optional |\n| machine_detection_method | The HTTP verb that should be used to invoke the machine_detection_url. This defaults to POST. |Optional |\n| sip_headers | List of SIP headers in the form of 'key=value' pairs, separated by commas. E.g. head1=val1,head2=val2,head3=val3,...,headN=valN.<br />The SIP headers specified will be automatically prefixed with “X-PH-” and these headers will be present for all the HTTP requests that are being made.<br />The valid values allowed for SIP header keys and values are integers, uppercase and lowercase alphabets. |Optional |\n| ring_timeout | Defines how long an unanswered call should ring before hanging up. The timeout is provided in seconds and the default value is 120. |Optional |\n| parent_call_uuid | The call_uuid of the first leg in an ongoing conference. This parameter is helpful in minimizing the delay of adding a new member in case of a conference. |Optional |\n| error_if_parent_not_found | Defines the behaviour of how to use parent_call_uuid. If this is set to true, then if parent_call_uuid is not found, the call is not initiated and it returns an error. If it is set to false, then the call will be initiated ignoring any errors with the parent_call_uuid. Default value is false |Optional |"
},
"response": [
{
"name": "Successful call",
"originalRequest": {
"method": "POST",
"header": [
],
"body": {
"mode": "raw",
"raw": "{\n \"from\":\"+14152225555\",\n \"to\":\"+14152223333\",\n \"answer_url\":\"https://answer.url\",\n \"answer_method\":\"POST\",\n \"ring_url\":\"https://ring.url\",\n \"ring_method\":\"POSt\",\n \"hangup_url\":\"https://hangup.url\",\n \"hangup_method\":\"POST\",\n \"fallback_url\":\"https://fallback.url\",\n \"fallback_method\":\"POST\",\n \"caller_name\":\"friendly_name\",\n \"send_digits\":\"1w2W3\",\n \"send_on_preanswer\":\"true\",\n \"time_limit\":\"300\"\n}",
"options": {
"raw": {
"language": "json"
}
}
},
"url": {
"raw": "https://api.plivo.com/v1/Account/{{auth_id}}/Call/",
"protocol": "https",
"host": [
"api",
"plivo",
"com"
],
"path": [
"v1",
"Account",
"{{auth_id}}",
"Call",
""
]
}
},
"code": 201,
"_postman_previewlanguage": "json",
"header": [
],
"cookie": [
],
"body": "{\n \"message\": \"call fired\",\n \"request_uuid\": \"9834029e-58b6-11e1-b8b7-a5bd0e4e126f\",\n \"api_id\": \"97ceeb52-58b6-11e1-86da-77300b68f8bb\"\n}"
},
{
"name": "Successful Queued call",
"originalRequest": {
"method": "POST",
"header": [
],
"body": {
"mode": "raw",
"raw": "{\n \"from\":\"+14152225555\",\n \"to\":\"+14152223333\",\n \"answer_url\":\"https://answer.url\",\n \"answer_method\":\"POST\",\n \"ring_url\":\"https://ring.url\",\n \"ring_method\":\"POSt\",\n \"hangup_url\":\"https://hangup.url\",\n \"hangup_method\":\"POST\",\n \"fallback_url\":\"https://fallback.url\",\n \"fallback_method\":\"POST\",\n \"caller_name\":\"friendly_name\",\n \"send_digits\":\"1w2W3\",\n \"send_on_preanswer\":\"true\",\n \"time_limit\":\"300\"\n}",
"options": {
"raw": {
"language": "json"
}
}
},
"url": {
"raw": "https://api.plivo.com/v1/Account/{{auth_id}}/Call/",
"protocol": "https",
"host": [
"api",
"plivo",
"com"
],
"path": [
"v1",
"Account",
"{{auth_id}}",
"Call",
""
]
}
},
"code": 200,
"_postman_previewlanguage": "json",
"header": [
],
"cookie": [
],
"body": "{\n \"message\": \"call queued\",\n \"request_uuid\": \"9834029e-58b6-11e1-b8b7-a5bd0e4e126f\",\n \"api_id\": \"97ceeb52-58b6-11e1-86da-77300b68f8bb\"\n}"
}
]
}
