Search Communication With
This request returns a list of communications with a specific addressable.
The results are ordered in (reverse) chronological order, and is paged.
The communication is retreived in periods of 28 days.
This emplies that the results size of a communication-with request will be limitted by one of the following:
-
the results size: the defined maximum number of objects is returned.
-
the time period: less then the maximum number of objects (not enough objects in the specified period are found).
The following algrorithm pages this query with the default page size (15). The page size can be changed the option limit.
Resource
GET /communications?with=<OID>[?parameters]
Parameters
| Name | Type | Description |
|---|---|---|
|
[id] |
Paging: return results before the specified cursor ID. Can also be used to set a start date of this query when order is ascending. |
|
[id] |
Paging: return results after the specified cursor ID. Can also be used to set a start date of this query when order is descending (default). |
|
[participant-id] |
Return communication with this participant, is required for this call. |
|
String |
See communication search parameters → the participants are always included when communication with is queried. |
Paging
Paging of the communication with API calls is very tricky. This is because the ordering is descending and there is also a date part to consider.
How to handle paging is different when you are ascending or descending (communication is ordered descending by default).
Descending
If the communication is given in a descending order, the following call is made:
https://xelion.nl/api/v1/master/communications?with=1650938&limit=4&order=descending
This will return the following:
{
"data": [
{
"object": {
"subject": "",
"date": "2021-06-25 15:28:32",
"commonName": "Wesley -> Arno, 2021-06-25",
"oid": "2006154",
"objectType": "CallLog"
},
"links": [
{
"rel": "self",
"href": "https://xelion.nl/api/v1/master/communications/2006154",
"method": "GET"
}
]
},
{
"object": {
"subject": "",
"date": "2021-06-25 15:09:13",
"commonName": "Wesley -> Arno, 2021-06-25",
"oid": "2006142",
"objectType": "CallLog"
},
"links": [
{
"rel": "self",
"href": "https://xelion.nl/api/v1/master/communications/2006142",
"method": "GET"
}
]
},
{
"object": {
"subject": "hello there",
"date": "2021-06-25 15:08:21",
"commonName": "hello there",
"oid": "2006131",
"objectType": "XCCUserChat"
},
"links": [
{
"rel": "self",
"href": "https://xelion.nl/api/v1/master/communications/2006131",
"method": "GET"
}
]
},
{
"object": {
"subject": "hello there",
"date": "2021-06-25 15:07:51",
"commonName": "hello there",
"oid": "2006116",
"objectType": "XCCUserChat"
},
"links": [
{
"rel": "self",
"href": "https://xelion.nl/api/v1/master/communications/2006116",
"method": "GET"
}
]
}
],
"meta": {
"links": [
{
"rel": "refresh",
"href": "https://xelion.nl/api/v1/master/communications",
"method": "GET"
},
{
"rel": "next",
"href": "https://xelion.nl/api/v1/master/communications?after=1624633671_2006116",
"method": "GET"
},
{
"rel": "previous",
"href": "https://xelion.nl/api/v1/master/communications?before=1624634912_2006154",
"method": "GET"
}
],
"paging": {
"previousId": "1624634912_2006154",
"nextId": "1624633671_2006116"
}
}
}The 4 newest communications are given in a descending order (2021-06-25 15:28:32 until 2021-06-25 15:07:51).
For the next 4 communication objects you need the 4 communication objects that are after the communication with the date 2021-06-25 15:07:51, as you can see, the oid of this communication is 2006116.
You can find the next id (1624633671_2006116) in the meta info of the response. In this meta info there is a object paging with the field nextId, use this field to fetch the correct id for the next page.
When the id is found, add this to the URL parameter after and do the following API call for the next 4 communication items:
https://xelion.nl/api/v1/master/communications?with=1650938&limit=4&order=descending&after=1624633671_2006116
This will return the following:
{
"data": [
{
"object": {
"subject": "",
"date": "2021-06-25 14:06:57",
"commonName": "Wesley -> Arno, 2021-06-25",
"oid": "2006057",
"objectType": "CallLog"
},
"links": [
{
"rel": "self",
"href": "https://xelion.nl/api/v1/master/communications/2006057",
"method": "GET"
}
]
},
{
"object": {
"subject": "",
"date": "2021-06-25 13:58:18",
"commonName": "Wesley -> Arno, 2021-06-25",
"oid": "2006049",
"objectType": "CallLog"
},
"links": [
{
"rel": "self",
"href": "https://xelion.nl/api/v1/master/communications/2006049",
"method": "GET"
}
]
},
{
"object": {
"subject": "",
"date": "2021-06-25 13:57:18",
"commonName": "Wesley -> Arno, 2021-06-25",
"oid": "2006042",
"objectType": "CallLog"
},
"links": [
{
"rel": "self",
"href": "https://xelion.nl/api/v1/master/communications/2006042",
"method": "GET"
}
]
},
{
"object": {
"subject": "",
"date": "2021-06-25 13:26:59",
"commonName": "Wesley -> Arno, 2021-06-25",
"oid": "2005960",
"objectType": "CallLog"
},
"links": [
{
"rel": "self",
"href": "https://xelion.nl/api/v1/master/communications/2005960",
"method": "GET"
}
]
}
],
"meta": {
"links": [
{
"rel": "refresh",
"href": "https://xelion.nl/api/v1/master/communications",
"method": "GET"
},
{
"rel": "next",
"href": https://xelion.nl/api/v1/master/communications?after=1624627619_2005960",
"method": "GET"
},
{
"rel": "previous",
"href": https://xelion.nl/api/v1/master/communications?before=1624630017_2006057",
"method": "GET"
}
],
"paging": {
"previousId": "1624630017_2006057",
"nextId": "1624627619_2005960"
}
}
}Now the next 4 (older) communication items are returned (2021-06-25 14:06:25 until 2021-06-25 13:26:59).
The paging nextId now has the value 1624627619_2005960 and as you can see this is also filled in the meta paging value nextId.
So for the next 4 communication items the same can be done.
Sometimes it is needed to go back a page. Then do the exact opposite of the above description.
Checkout the previousId in the meta paging values
and use this to get the previous page with the following URL:
https://xelion.nl/api/v1/master/communications?with=1650938&limit=4&order=descending&before=1624630017_2006057
This will return the exact same results as the initial call.
Check out that now the parameter before is used instead of after.
Ascending
If the communication is given in a ascending order, the following call is made:
https://xelion.nl/api/v1/master/communications?with=1650938&limit=4&order=ascending
This will return the following:
{
"data": [
{
"object": {
"subject": "",
"date": "2021-06-16 13:07:36",
"commonName": "Wesley -> Arno, 2021-06-16",
"oid": "2004697",
"objectType": "CallLog"
},
"links": [
{
"rel": "self",
"href": "https://xelion.nl/api/v1/master/communications/2004697",
"method": "GET"
}
]
},
{
"object": {
"subject": "",
"date": "2021-06-16 13:08:44",
"commonName": "Wesley -> Arno, 2021-06-16",
"oid": "2004714",
"objectType": "CallLog"
},
"links": [
{
"rel": "self",
"href": "https://xelion.nl/api/v1/master/communications/2004714",
"method": "GET"
}
]
},
{
"object": {
"subject": "",
"date": "2021-06-16 13:10:03",
"commonName": "Wesley -> Arno, 2021-06-16",
"oid": "2004731",
"objectType": "CallLog"
},
"links": [
{
"rel": "self",
"href": "https://xelion.nl/api/v1/master/communications/2004731",
"method": "GET"
}
]
},
{
"object": {
"subject": "",
"date": "2021-06-16 13:13:38",
"commonName": "Wesley -> Arno, 2021-06-16",
"oid": "2004742",
"objectType": "CallLog"
},
"links": [
{
"rel": "self",
"href": "https://xelion.nl/api/v1/master/communications/2004742",
"method": "GET"
}
]
}
],
"meta": {
"links": [
{
"rel": "refresh",
"href": "https://xelion.nl/api/v1/master/communications",
"method": "GET"
},
{
"rel": "next",
"href": "https://xelion.nl/api/v1/master/communications?after=1623849218_2004742",
"method": "GET"
},
{
"rel": "previous",
"href": "https://xelion.nl/api/v1/master/communications?before=1623848856_2004697",
"method": "GET"
}
],
"paging": {
"previousId": "1623848856_2004697",
"nextId": "1623849218_2004742"
}
}
}The 4 oldest communications are given in a ascending order (2021-06-16 13:07:36 until 2021-06-16 13:13:38).
For the next 4 communication objects you need the 4 communication objects that are after the communication with the date 2021-06-16 13:13:38, as you can see, the oid of this communication is 2004742.
You can find the next id (1623849218_2004742) in the meta info of the response. In this meta info there is a object paging with the field nextId, use this field to fetch the correct id for the next page.
When the id is found, add this to the URL parameter after and do the following API call for the next 4 communication items:
https://xelion.nl/api/v1/master/communications?with=1650938&limit=4&order=ascending&after=1623849218_2004742
This will return the following:
{
"data": [
{
"object": {
"subject": "",
"date": "2021-06-16 13:20:52",
"commonName": "Wesley -> Arno, 2021-06-16",
"oid": "2004751",
"objectType": "CallLog"
},
"links": [
{
"rel": "self",
"href": "https://xelion.nl/api/v1/master/communications/2004751",
"method": "GET"
}
]
},
{
"object": {
"subject": "",
"date": "2021-06-16 13:21:36",
"commonName": "Wesley -> Arno, 2021-06-16",
"oid": "2004759",
"objectType": "CallLog"
},
"links": [
{
"rel": "self",
"href": "https://xelion.nl/api/v1/master/communications/2004759",
"method": "GET"
}
]
},
{
"object": {
"subject": "",
"date": "2021-06-16 13:31:20",
"commonName": "Wesley -> Arno, 2021-06-16",
"oid": "2004771",
"objectType": "CallLog"
},
"links": [
{
"rel": "self",
"href": "https://xelion.nl/api/v1/master/communications/2004771",
"method": "GET"
}
]
},
{
"object": {
"subject": "",
"date": "2021-06-16 13:31:36",
"commonName": "Wesley -> Arno, 2021-06-16",
"oid": "2004779",
"objectType": "CallLog"
},
"links": [
{
"rel": "self",
"href": "https://xelion.nl/api/v1/master/communications/2004779",
"method": "GET"
}
]
}
],
"meta": {
"links": [
{
"rel": "refresh",
"href": "https://xelion.nl/api/v1/master/communications",
"method": "GET"
},
{
"rel": "next",
"href": "https://xelion.nl/api/v1/master/communications?after=1623850296_2004779",
"method": "GET"
},
{
"rel": "previous",
"href": "https://xelion.nl/api/v1/master/communications?before=1623849652_2004751",
"method": "GET"
}
],
"paging": {
"previousId": "1623849652_2004751",
"nextId": "1623850296_2004779"
}
}
}Now the next 4 (newer) communication items are returned (2021-06-16 13:20:52 until 2021-06-16 13:31:36).
The paging nextId now has the value 1623850296_2004779 and as you can see this is also filled in the meta paging value nextId.
So for the next 4 communication items the same can be done.
Sometimes it is needed to go back a page. Then do the exact opposite of the above description.
Checkout the previousId in the meta paging values and use this to get the previous page with the following URL:
https://xelion.nl/api/v1/master/communications?with=1650938&limit=4&order=ascending&before=1623849652_2004751
This will return the exact same results as the initial call.
Check out that now the parameter before is used instead of after.
Payload
None
Response
Context
| Authorization |
User |
Errors
Example 1: get communication with
GET https://xelion.nl/api/v1/master/communications?with=14920803
{
"data": [
{
"object": {
"subject": "",
"date": "2019-01-30 16:32:52",
"durationSec": 0,
"status": "Unavailable",
"incoming": false,
"retrieved": false,
"displayed": false,
"flagged": false,
"hasAttachment": false,
"hasInlineAttachment": false,
"contentSummary": "",
"contentSummaryIsComplete": true,
"participants": [
{
"commonName": "Wesley",
"role": "rtFrom",
"address": "413",
"addressable": {
"commonName": "Wesley",
"oid": "1650975",
"objectType": "Person"
},
"oid": "1832044",
"objectType": "Addressee"
},
{
"commonName": "Arno",
"role": "rtTo",
"address": "411",
"addressable": {
"commonName": "Arno",
"oid": "1650938",
"objectType": "Person"
},
"oid": "1832053",
"objectType": "Addressee"
}
],
"voicemail": false,
"callId": "",
"callFlowId": "",
"commonName": "Wesley -> Arno, 2019-01-30",
"oid": "1832043",
"objectType": "CallLog"
},
"links": [
{
"rel": "self",
"href": "http://sip.xelion.nl/api/v1/master/communications/1832043",
"method": "GET"
}
]
},
{
"object": {
"subject": "",
"date": "2019-01-30 16:32:52",
"durationSec": 0,
"status": "Unavailable",
"incoming": true,
"retrieved": false,
"displayed": false,
"flagged": false,
"hasAttachment": false,
"hasInlineAttachment": false,
"contentSummary": "",
"contentSummaryIsComplete": true,
"participants": [
{
"commonName": "Arno",
"role": "rtTo",
"address": "411",
"addressable": {
"commonName": "Arno",
"oid": "1650938",
"objectType": "Person"
},
"oid": "1832032",
"objectType": "Addressee"
},
{
"commonName": "Wesley",
"role": "rtFrom",
"address": "413",
"addressable": {
"commonName": "Wesley",
"oid": "1650975",
"objectType": "Person"
},
"oid": "1832041",
"objectType": "Addressee"
}
],
"voicemail": false,
"callId": "",
"callFlowId": "2019-01-30-17:32:53-00000009",
"commonName": "Arno <- Wesley, 2019-01-30",
"oid": "1832031",
"objectType": "CallLog"
},
"links": [
{
"rel": "self",
"href": "http://sip.xelion.nl/api/v1/master/communications/1832031",
"method": "GET"
}
]
}
],
"meta": {
"links": [
{
"rel": "refresh",
"href": "http://sip.xelion.nl/api/v1/master/communications",
"method": "GET"
},
{
"rel": "next",
"href": "http://sip.xelion.nl/api/v1/master/communications?after=1548865972_1832031",
"method": "GET"
},
{
"rel": "previous",
"href": "http://sip.xelion.nl/api/v1/master/communications?before=1548865972_1832043",
"method": "GET"
}
],
"paging": {
"previousId": "1548865972_1832043",
"nextId": "1548865972_1832031"
}
}
}