Complete guide on how to configure new HTTPS API in UCM63XX (and generate MD5 hash token)

UCM63XX only supports the new HTTPS API Setting, and no longer supports the old HTTPS API Setting. Although UCM API configuration does show how to configure UCM API, some steps are skipped. I’m sure those users who do not know to code will have a hard time getting the token or cookies.

There are 2 steps in configuring CDR API in UCM63XX:

1.     Configure CDR API and HTTP Server in UCM

2.     Establish Connection and User Authentication

a.     Send a request to the UCM to get a challenge string

b.     Send a request to the UCM for Login

c.     Run your command to obtain your desired data

1.     Configure CDR API and HTTP Server in UCM

a.     Enable CDR API

Go to UCM web UI > Value-added Features > API Configuration > HTTPS API Settings (New) and check ‘Enable’. Key in the Username as ‘cdrapi’ and password. In my example here I will be using the password ‘cdrapi123’.

b.    Whitelist your IP address in HTTP Server

Go to UCM web UI > System Settings > HTTP Server, and key in the IP address and subnet mask of the client device which you will be using to run HTTP request later under Permitted IP (s). Note that my HTTP server port here is 8089.

2.     Establish Connection and User Authentication

a.     Send a request to the UCM to get a Challenge string

To proceed with this step, you will need an API platform. I have been using Postman for quite a while (as you can see in all of my previous API guides), and it is working well for me. If you would like to download, here is a link to download.

You need to understand that HTTP authentication is based on request/response protocol. In this case, we will run a Challenge request on POSTMAN, which will parse this request to the UCM server. If the request succeeds, UCM will respond with a Challenge string with the status ‘0’.

Do a POST request in Postman, with the url format as “https://<ucm_ip_address>:<port_number>/api

E.g. https://192.168.0.174:8089/api

You do not need to key in any Params manually. Just go to Body, select raw (JSON), and paste the following request –

{

 "request":{

 "action":"challenge",

 "user":"cdrapi",

 "version":"1.2"

 }

}

It should look like this. Click on Send.

You will get a response with a challenge string back, similar to the image below. This challenge string is crucial for the next step.

b.    Send a request to the UCM for Login

To send a request to the UCM for login, you will need a token computed from the MD5 hash which consists of the challenge string and the user password. This is where things get tricky. The manual guide DOES NOT teach you how to get the token, assuming that you have a certain level of knowledge in coding.

In order to get the token, I have written a simple script for Python 3.9 which will generate the token.

import hashlib

challenge = '0000000891268968'

salt = "cdrapi123"

db_password = challenge+salt

h = hashlib.md5(db_password.encode())

print(h.hexdigest())

Replace the challenge string above with your challenge string generated from step 2(a), and run them in Python. You will get an MD5 hash string.

With this MD5 hash string, you can now run the following POST request in the POSTMAN. Make sure that you have replaced the token string with theMD5 string which you get from running the Python script above, and replace the URL to “https://<ucm_ip_address>:<port_number>”

{

 "request":{

 "action":"login",

 "token":"f6cbb7818d08cbcd09549a382a3f14f9",

 "url":"https://192.168.0.174:8089",

 "user":"cdrapi"

 }

}

UCM should respond with the cookie string. This cookie is required for all of the API requests you will run in step 2(c). Note that the cookie times out in 10 minutes.

c.     Run your command to obtain your desired data

Here, I will be sending a request to get all the CDR records from the CDR database. Run the following request in POSTMAN, and make sure the cookie field contains the cookie string from 2(b).

{"request":{

 "action":"cdrapi",

 "cookie":"sid343158721-1620280910",

 "format":"json"

 }

}

The output should be the CDR records in JSON format. For more parameters, you may refer back to UCM API Guide.