Contacts
Last updated September 27, 2018 Cloud Endpoint Control API
Directory types
Contacts are fetched by requesting the path /contacts.
There are four different contact directory types:
- global (or directory) – the organization global contact directory.
- personal – the personal contact directory of the current user.
- recent (or history) – the set of recent calls.
- favorite (or favourite)– the favorites of the current user.
The initial members of the favorite directory type are also accessible via the state section favorites, which has the additional ability to push presence updates for those members.
Parameter | Data type | Description |
---|---|---|
type | string | Directory type (see above). |
search | string | Search string. |
sort | string | Sort order (either first,last or last,first). |
start | integer | Index in directory of first contact to fetch. |
count | integer | Number of contacts to fetch (1 to 20). |
The returned object contains the details of the view created (determined by the type, search and sort arguments to the request), along with the actual results of the search within that view (determined by the start and count arguments).
Parameter | Data type | Description |
---|---|---|
total_entries | integer |
The total number of contacts in this view (whole directory or searched subset). |
view_sequence | integer | Sequence number of the current transient view. |
ribbon | array | Ribbon values (global and personal directories only) |
results | array | Array of contact detail objects (see below). |
The contact details available depend on which directory is being fetched.
The global and personal directories contain:
Parameter | Data type | Description |
---|---|---|
index | integer | Index in this directory. The index is 0-indexed. |
id | integer | Contact ID (for fetching detail and to use with the dial action). |
first_name | string | First name. |
last_name | string | Last name. |
numbers | array | Array of number objects. |
The recent calls list entries contain:
Parameter | Data type | Description |
---|---|---|
index | integer | Index in this directory. The index is 0-indexed. |
id | integer | Contact ID (for fetching detail and to use with the dial action). |
display_name | string | Display name. |
count | integer | Number of calls made e (repeated calls to the same contact are combined). |
time | integer | Time of last call (UNIX time). |
outcome | integer | Call outcome (see below). |
duration | integer |
Call duration (seconds). |
number | object |
A single number object. |
The favorite list entries contain:
Parameter | Data type | Description |
---|---|---|
index | integer | Index in this directory. The index is 0-indexed. |
id | integer | Contact ID (for fetching detail and to use with the dial action). |
display_name | string | Display name. |
presence | integer |
Presence state. |
evsip_presence | integer | EVSIP presence state. |
number | object |
A single number object. |
Detailed contacts
To fetch a detailed contact, first search for the normal contact by whatever means. When the normal contact is available, fetch the detailed contact using the id in the short entry for that contact.
The contact id is transient and may change and therefore you must search for the contact id before requesting any details.
Parameter | Data type | Description |
---|---|---|
type | string | Directory type (see above). |
detail | boolean | Set to true to fetch contact detail. |
contactid | integer | The ID of the contact to fetch. |
Examples:
- To fetch a list of up to 20 contacts from the global directory:
request: contacts?type=global&pretty - To see more contacts, pass in the start argument:
request: contacts?type=global&start=20&pretty
This returns a list of up to 20 contacts from the global directory, starting at the 21st contact in the global directory as ordered by the default alphabetic ordering of last name, first name. - To search for a particular contact:
request: contacts?type=global&search=John%20Doe&pretty
Example result:{ "view_sequence" : 3, "total_entries" : 1, "results" : [{ "index" : 0, "id" : 165, "display_name" : "John Doe", "first_name" : "John", "last_name" : "Doe", "numbers" : [ ] } ] }
- An empty search string matches everything, so contacts?type=global&search=&pretty
is equivalent to
contacts?type=global&pretty -
When a search has been made, more information can be viewed on a particular contact by passing in the integer
contactid.
request: contacts?type=global&detail&contactid=165&pretty
Example result:{ "view_sequence" : 3, "total_entries" : 1, "results" : [{ "index" : 0, "id" : 165, "display_name" : "John Doe", "first_name" : "John", "last_name" : "Doe", "numbers" : [{ "type" : 1, "number" : "9001" } ] } ] }
Personal contacts
Contact number types
Contact number types that can be set are as follows:
Contact type | Description | |
---|---|---|
1 | INTERNAL | Organization-internal cloud number. |
2 | CLOUD | Global cloud number. |
3 | MOBILE | Mobile number (PSTN). |
4 | WORK | Work number. |
5 | HOME | Home number. |
Recent calls
Clearing recent calls
The clear_recent action clears the recent calls list. It takes no arguments.