Offline history

Metoda dostępna pod adresem: /ch.ashx .

This method allows you to download the history of conversations and messages for a given user. This method contains two parameters: cm and pm. The cm parameter describes the name of the method, while the pm parameter describes the parameters of a given method. The following methods are available within conversation history: setRead, setDownloaded, delRecord, getList.

Authorization

The method requires authorization using basic authentication. Please use your SIP account login and password.

Method description:

Mark the list of records as read

Each record in the history has a field called "new" with values 0 or 1. All new records are set to "new" = 1. To change the status of a given message or group of messages to 0, i.e. read, you need to call the ch.ashx method with the parameters:

Parameter	Description
cm	parameter specifies the name of the method. If the status changes, set the "setRead" value
pm	a JSON object containing an array of identifiers which messages should have their status changed to read. Example {"id":[1000685,1192075]} where 1000685 and 1192075 are the record IDs

Downloading history for the first time:

(remember to send empty If-Modified-Since this parameter will be used in all the next request to ch.ashx)

curl --location --request POST 'https://xxxxxxxxxx/emcd/ch.ashx?cm=getList' \
--header 'User-Agent: vippie;ios;1.2.3' \
--header 'Content-Type: text/plain' \
--header 'Authorization: Basic NDg2MDAzNTUzNjE6cGlvdHJJT1M=' \
--header 'X-VIPPIE-DEVICE-ID: 637' \
--header 'X-VIPPIE-DEVICE-NAME: iPhone8,1' \
--header 'If-Modified-Since;' \
--header 'Range: records=0-10000' \
--header 'X-Check-Threads;' \

Response :

[
    {
        "id": 1405573,
        "new": 1,
        "rs": "1000225",
        "dn": "48130313058",
        "s": "v",
        "sn": "on",
        "sb": "in",
        "dts": "2014-02-21T09:46:14",
        "dte": "",
        "mid": "",
        "mb": "",
        "cd": 0
    },
    {
        "id": 1174223,
        "new": 1,
        "rs": "1317111",
        "dn": "vippie ID",
        "s": "m",
        "sn": "on",
        "sb": "out",
        "dts": "2014-03-05T14:24:34",
        "dte": "2014-03-05T14:24:35",
        "mid": "35635",
        "mb": "Message content",
        "cd": 0
    },
....
]

where:

id - identifier of a given message in the conversation history

new - message status: 1 - unread, 0 - read

rs - resource - in the case of source onnet it is the sip login, in the case of offnet it is the caller ID of the caller.

dn - display name

s - source, available values: c - call, f - call failed, m - message, v - voicemail, s - SIPLINK_COMMAND

sn - source network, available values: on -> on-net or off -> off-net

sb - source box, available values: in or out

sdt - event date - in the case of calls, this is the date the call ended.

mid - message id - message ID sent by dialer in the sip message body

mb - message body -Message content

ms - message status - available values s - sent, d - delivered, r - read, c - deleted

cd - call duration - connection length in seconds.

cid - Call Id

fa - FlagArchive
fs - FlagStarred
fd - FlagDeleted

Retrieving the conversation list by modification date

To download the history, call the ch.ashx method with the cm=getList parameter and additionally set the If-Modified-Since and Range headers.

The If-Modified-Since header instructs the server to send records only if they have been modified since a given date. If the data has not changed, the server should send the response code 304 - HTTP STATUS: 304 Not Modified, otherwise the server will return a list of records in the form of a JSON array.
The Range header specifies what part of the data the dialer expects. This header should be provided in the format records=start_position-end_position. If the dialer does not send the Range header, the server will default to records=0-99, i.e. it will return the first 100 records.

Example - retrieving records without specifying If-Modified-Since and Range:

Request

Request body
cm=getList

Response

Content-Range: records 0-99/5124
Last-Modified: Tue, 21 Nov 2014 12:45:26 GMT
 
Response body
[
    {
        "id": 1405573,
        "new": 1,
        "rs": "1000225",
        "dn": "48130313058",
        "s": "v",
        "sn": "on",
        "sb": "in",
        "dts": "2014-02-21T09:46:14",
        "dte": "",
        "mid": "",
        "mb": "",
        "cd": 0
    },
    {
        "id": 1174223,
        "new": 1,
        "rs": "1317111",
        "dn": "vippie ID",
        "s": "m",
        "sn": "on",
        "sb": "out",
        "dts": "2014-03-05T14:24:34",
        "dte": "2014-03-05T14:24:35",
        "mid": "35635",
        "mb": "tre?? wiadomo?ci",
        "cd": 0
    },
....
]

If-Modified-Since and Range

Everytime when the app is started you have to send the request to ch.ashx to check if nothing has changed in the history and for this use header If-Modified-Since :

You have to remember when the previous request was sent to check is something has changed on the account since the last hitory check.

The previous request was sent by the app 2025-01-28 09:40:46 on the server we see 1 milisecond later time as those are server logs (2025-01-28 09:40:47,342)

Now in the next request take remembered time of last request and put it in If-Modified-Since header in this format:

day of a week, date GMT

Tue, 28 Jan 2025 09:40:46 GMT

curl --location --request POST 'https://xxxxxxx/emcd/ch.ashx?cm=getList' \
--header 'User-Agent: vippie;ios;1.2.3' \
--header 'Content-Type: text/plain' \
--header 'Authorization: Basic NDg2MDAzNTUzNjE6cGlvdHJJT1M=' \
--header 'X-VIPPIE-DEVICE-ID: 637' \
--header 'X-VIPPIE-DEVICE-NAME: iPhone8,1' \
--header 'If-Modified-Since: Tue, 28 Jan 2025 09:40:46 GMT' \
--header 'Range: records=0-10000' \
--header 'X-Check-Threads;' \

logs from EMCD API
2025-01-28 09:56:58,912 46.205.197.141 48666777888 3F96B4B5BB50B603575AAA6B INFO HistoryHandler > [gzip, deflate, br]|POST|/emcd/ch.ashx|cm=getList
2025-01-28 09:56:58,913 46.205.197.141 48666777888 3F96B4B5BB50B603575AAA6B DEBUG HistoryHandler - X-VIPPIE-DEVICE-ID:637, X-VIPPIE-DEVICE-NAME:iPhone9,3
2025-01-28 09:56:58,913 46.205.197.141 48666777888 3F96B4B5BB50B603575AAA6B DEBUG HistoryHandler - If-Modified-Since:Tue, 28 Jan 2025 09:40:46 GMT, Range:records=0-10000, X-Check-Threads:
2025-01-28 09:56:59,052 46.205.197.141 48666777888 3F96B4B5BB50B603575AAA6B DEBUG HistoryHandler - Response header(s):Last-modified:Tue, 28 Jan 2025 09:40:46 GMT
2025-01-28 09:56:59,053 46.205.197.141 48666777888 3F96B4B5BB50B603575AAA6B INFO HistoryHandler < 200|application/json|[]

If nothing has changed on the account you will get an empty response , if something has changed you will get the history

POST /history

Description

Download the conversation list.

Parameters

Name

Located in

Description

Required

Example

Authorization

header

Basic authorization. SIP login and SIP password required

yes

Basic aHR0cHdhdGNoOmY=

User-Agent

header

Dialer identifier in the form custom-name,operating-system,application-version

no

vippie;ios;2.1.9

If-Modified-Since

header

The If-Modified-Since header tells the server to send records only if they have been modified since a given date. If the data has not changed, the server should send a response code of 304 - HTTP STATUS: 304 Not Modified

no

Range

header

The Range header specifies what portion of the data the dialer expects. This header should be in the format records=start_position-end_position. If the dialer does not send the Range header, the server will default to records=0-99, i.e. it will return the first 100 records.

no

X-Check-Threads

header

no

cm

body

method name - getList

yes

pm

body

method parameters - JSON object

{
 "th" : true,
 "rs" : "sip_login",
 "gid": 123,
 "sn" : "on",
 "sdt": "2018-03-02T18:00:20"
}

where:

Name	Type	Description
th	bool	thread - events grouped by threads
rs	string	resource - in the case of source onnet it is the sip login, in the case of offnet it is the caller ID of the caller
sn	string	source network, available values: on -> on-net or off -> off-net
gid	number	group id
sdt	string	event date

no

Thread list

{
 "th":true 
}

event list (for a login)

{
 "rs":"sip_login",
 "sn":"on"
}

event list (for a login) older than 2018-01-20 20:20:11

{
 "rs":"sip_login",
 "sn":"on",
 "sdt":"2018-01-20T20:20:11"
}

Event list (for a group)

{
 "gid":123
}

Getting a list of events in a thread (for a group)

{
 "gid":123,
 "sdt":"2018-01-20T20:20:11"
}

Responses

Code	Content-Type	Description	Schema
200
304
200
200
200

Retrieving information about the message

To retrieve information about a given message, you need to call the /history method with the following parameters:

Parameter	Description
cm	parameter specifies the name of the method. If a message is deleted, set the "getMessageInfo" value
pm	a JSON object containing an array of identifiers of what messages are to be deleted. Example { "mid":"MESSAGE-ID", "rs": "1317111" } where mid is the identifier of the message sent by the dialer and rs - resource - is the sip login

Response

{
 "st": "2014-03-17T18:08:20",
 "cf": "2014-03-17T18:08:20",
 "rd": "2014-03-17T18:08:20"
}

setting up a Label

To set the label, you need to call the /history method with parameters:

Parameter

Description

cm

parameter specifies the name of the method. You must set the "setLabel" value

pm

a JSON object containing information about what labels should be set for individual records. Example:

{
 "lbl": 0,
 "s"  : "",
 "mid": [""],
 "rs" : [""],
 "cid": [""],
 "gid": [1]
}

where:

lbl - label, numerical marking of labels. A description of how to calculate the value is provided below.
s - source -
mid - message ID - can only occur for s = m or s = g
rs - resource - sip login - can appear for any s or without s
cid - call ID - can only occur for s = c or s = f
gid - group ID - can only occur for s = g

Example 1:

To set the archived label for the entire groupchat with ID = 567, you need to create an object

{
 "lbl": 8,
 "s"  : "g",
 "gid": [567]
}

Example 2

To set the archived label for selected groupchat messages with ID = 567, you must create an object

{
 "lbl": 8,
 "s"  : "g",
 "gid": [567]
 "mid": ["123","124","125","126"]
}

How to calculate the value for label.

Each label has a fixed value, which is a power of 2. A value of 0 means no labels.

ID	Desc	Value
1	deleted	2^1 = 2
2	starred	2^2 = 4
3	archived	2^3 = 8

If, for example, we want to set the deleted (id=1) and archived (id=3) labels for selected records, we calculate it as follows:

2^1 + 2^3 = 2 + 8 = 10

In response we will receive:

Response

{
 "nra": 12
}

Delete the message list

To delete the list of messages, you need to call the ch.ashx method with the following parameters:

Parameter	Description
cm	parameter specifies the name of the method. If a message is deleted, set the "delRecord" value
pm	a JSON object containing an array of identifiers of what messages are to be deleted. Example {"id":[1000685,1192075]} where 1000685 and 1192075 are the message IDs

Mark the attachment in the message as downloaded

After successfully downloading the file, set the attachment status to correct. Calling the function removes the file identifier from the message body. Example:

message containing a downloadable attachment

 ~[ATT RID:'1999999' type:'0' ext:'jpg']

message containing a downloaded attachment:

 ~[ATT RID:'' type:'0' ext:'jpg']

To set the attachment status, you need to call the ch.ashx method with the following parameters:

Parameter	Description
cm	parameter specifies the name of the method. If the status changes, set the "setDownloaded" value
pm	a JSON object containing the ID of the message with the attachment. Example {"id":1000685} where 1000685 are the message IDs

Browser not supported