×
PLEASE NOTE THIS VERSION OF API IS DEPRECATED

 

If you are integrating this API now, kindly refer to the updated documentation here 

If you had integrated this API before 9th June 2021, you shall receive an email notification on steps to migrate to the latest version.

Reach out to hello@exotel.com for any queries.

 

To update user's device, you will need to make a HTTP PUT request to

PUT

https://<your_api_key>:<your_api_token><subdomain>/v2/accounts/<your_sid>/users/<user_id>/devices/<device_id>

  • Replace <your_api_key> and <your_api_token> with the API key and token created by you.
  • Replace <your_sid> with your “Account sid”
  • Replace <subdomain> with the region of your account
    1. <subdomain> of Singapore cluster is @ccm-api.exotel.com
    2. <subdomain> of Mumbai cluster is @ccm-api.in.exotel.com
  • Replace <user_id> and <device_id> with the user's unique identifier and device identifier as present in GET user details API.

<your_api_key> , <your_api_token> and <your_sid> are available in the API settings page of your Exotel Dashboard

The following are the PUT parameters supported with Content-Type: application/json set in the header

Parameter Name

Value

available

Boolean (true/false); Indicates if the device is available (ON) to take calls or unavailable (OFF).

Example -
{
"available": true
}

NOTE: If a user has more than one device, then, only 1 device can be turned ON (set to available = true) is allowed. All other devices must be turned OFF (set to available = false) before another device can be turned ON (set to available = true).

 
curl -X PUT \
  https://<your_api_key>:<your_api_token><subdomain>/v2/accounts/<your_sid>/users/<user_id>/devices/<device_id> \
  -H 'content-type: application/json' \
  -d '{ "available": true }'
var request = require('request');
var options = {
    url: 'https://<your_api_key>:<your_api_token><subdomain>/v2/accounts/<your_sid>/users/<user_id>/devices/<device_id>',
    method: 'PUT',
    headers: { 'content-type': 'application/json' },
    body: { available: true },
    json: true
};
function callback(error, response, body) {
    if (!error && response.statusCode == 200) {
        console.log(body);
    }
}
request(options, callback);
    
<?php

$request = new HttpRequest();
$request->setUrl('https://<your_api_key>:<your_api_token><subdomain>/v2/accounts/<your_sid>/users/<user_id>/devices/<device_id>');
$request->setMethod(HTTP_METH_PUT);

$request->setHeaders(array(
  'content-type' => 'application/json',
));

$request->setBody('{    
    "available": true
}
');

try {
  $response = $request->send();
  echo $response->getBody();
} catch (HttpException $ex) {
  echo $ex;
}
import requests

url = "https://<your_api_key>:<your_api_token><subdomain>/v2/accounts/<your_sid>/users/<user_id>/devices/<device_id>"

payload = "{\"available\": true}"
headers = {
    'content-type': "application/json",
    }

response = requests.request("PUT", url, data=payload, headers=headers)

print(response.text)
require 'uri'
require 'net/http'

url = URI("https://<your_api_key>:<your_api_token><subdomain>/v2/accounts/<your_sid>/users/<user_id>/devices/<device_id>")

http = Net::HTTP.new(url.host, url.port)

request = Net::HTTP::Put.new(url)
request["content-type"] = 'application/json'
request.body = "{\"available\": true}"

response = http.request(request)
puts response.read_body

HTTP Response:

  • On success, the HTTP response status code will be 200
  • the HTTP body will contain an JSON similar to the one below:
  • Example Response
{
    "request_id": "6b99d8f854244f1eb8bb91d75f1c565a",
    "method": "PUT",
    "http_code": 200,
    "response": [
        {
            "code": 200,
            "error_data": null,
            "status": "success",
            "data": {
                "id": 100280,
                "name": "Primary Device",
                "contact_uri": "+91917622XXXX",
                "type": "tel",
                "available": true,
                "verified": true,
                "status": "free"
            }
        }
    ]
}
Parameter Name Type & Value
request_id This indicates the unique id of the request. Useful for debugging and tracing purposes.
method This indicates the HTTP method for the request such as GET/POST/PUT etc.
http_code This indicates the HTTP code for the request such as 200, 400, 500 etc.
response

Response is an array of user records matching the request query. Each of the element in the array contains the following

  • code - This indicates the http code for the particular record in the response array like 200, 400 etc.
  • error_data - This block will be null if there is no error else contain error information for the response with following fields
    • code - This would be the error code useful for Exotel's team to debug and can be highlighted in case of unexpected errors.
    • description - This describes the details of the error.
    • message - This is the error message corresponding to the error code useful for Exotel's team to debug and can be highlighted in case of unexpected errors.
  • status - This field would indicate status of the response (success/failure).
  • data - This block will contain the information corresponding to the response array element and will contain the fields for a user record as explained below. 

Description of parameters under 'data' block:

Parameter Name Description
id Unique ID of the device of the user. To be used as <device-id> while performing a PUT operation on the user.
name Friendly name of the device
contact_uri

Phone number of the device in E.164 format like +919999XXXXXX or the SIP URI of the device if it is a soft-phone like sip:arjuns2d853099.
type

Type of device. Possible values

  • sip - The device is a soft-phone with a SIP URI like sip:arjuns2d853099
  • tel - The device is a PSTN phone number like +919999XXXXXX
available

Boolean (true/false);

Indicates if the device is available (ON) to take calls or unavailable (OFF). It will be set to null if device is unverified.
verified Boolean (true/false);

Indicates if the device is verified or not on Exotel. If a user needs to verify their device, these steps can be followed.
status

Indicates the current device status. Possible values-

  • busy - The device is currently busy on a call and no more calls can be dialled or received using this device.
  • free - The device is currently free and calls can be made or received on this device.

Possible error scenarios in case of this PUT API - 

HTTP Codes

Descriptions

404

User not found

404

Tenant not found

404

Device not found

403

Device is unverified

403
Another device is ON. Only one device can be ON at a time

401

Authentication Failed

400

Request format is invalid

429

Too many requests

500

Internal Server Error

Example - How to turn a user device ON / OFF ?

Step 1 : Fetch the user id and device id of the corresponding user where the contact_uri (phone number) is +9199512131xx by querying the GET API like below

GET

https://<your_api_key>:<your_api_token><subdomain>/v2/accounts/<account_sid>/users?fields=devices&devices.contact_uri=%2B9199512131xx 

Step 2: Use the user id and device id returned in the API response to toggle the value of available by setting it to true for ON and false for OFF like below

PUT

https://<your_api_key>:<your_api_token><subdomain>/v2/accounts/<your_sid>/users/<user_id>/devices/<device_id>