com.innovaphone.search (Client API)

This API provides an interface for cross-app searches.

API model

Service info

The API doesn't define any service info.

Provider model

{
    "relevance": number
}

relevance (optional): A number from 0 to 9999 specifying the relevance for the search results of that provider. Low numbers mean higher relevance.; Consumers can use that value to order search results by relevance.

API messages

All messages are JSON objects that have a mandatory attribute "mt" that specifies the message type. Providers must echo the "src" attribute from requests in the corresponding responses.

{
    "mt": string,
    "src": string
}

Requests

Search - A search request

Responses

SearchInfo - An individual search result
SearchResult - Sent after the last SearchInfo to tell that a Search request has been completed.

Search

This message is sent by the API consumer to start a search request. API providers must respond with 0..n SearchInfo messages followed by a SearchResult message.

{
    "mt": "Search",
    "src": string,
    "search": string,
    "type": string
}

search: The search string entered by the user.
type: The type of desired search results.; Currently the following types are implemented by innovaphone apps: "contact", "app", "message", "device".; Optional. Omit to get results of all types.

Examples:

{
    "mt": "Search",
    "search": "John Doe",
    "type": "contact"
}

{
    "mt": "Search",
    "search": "Devices",
    "type": "app"
}

{
    "mt": "Search",
    "search": "Sales Meeting",
    "type": "message"
}

{
    "mt": "Search",
    "search": "Marketing"
}

SearchInfo

This message is sent by the API provider and contains a single search result result.

General structure

{
    "mt": "SearchInfo",
    "src": string,
    "dn": string,
    "type": string,
    <type>: object,
    "link": string,
    "dontAttach": boolean,
    "relevance": number,
    "photourl": string,
    "avatar": string
}

dn: Display name of the item
type: The type of the item.; innovaphone apps currently use the types "contact", "app", "message" and "device".
a detail object: The name is the same as the value of type, e.g. "contact", "app", "message" or "device". The object contains details, that can be used or displayed by API consumers that know the corresponding type.
link: Optional.; An app link that can be used to open the item in the app or origin (e.g. someapp?id=3)
dontAttach: Optional.; If set to true, consumers should not offer to the user to pin or store the link.
relevance: Optional.; A number from 0 to 9999 specifying the relevance for that search result. Low numbers mean higher relevance.; Consumers can use that value to order search results by relevance.
photourl: Optional.; URL to image data. Could be HTTP/HTTPS url or inline data (data:image/png;base64…).
avatar: Optional.; SIP URI; Can be used to get the profile picture using the com.innovaphone.avatar API.; Can be used to do presence or dialog monitoring using the com.innovaphone.client API.

Details for type "contact"

This type is used for contacts. The detail object contains the contact details. Note that some search providers add additional attributes to the top level of the message, if the contact corresponds to a PBX user.

{
    "mt": "SearchInfo",
    "dn": string,
    "type": "contact",
    "contact": {
        "sn": string,
        "givenname": string,
        "displayname": string,
        "title": string,
        "position": string,
        "department": string,
        "company": string,
        "telephonenumber": [ string ],
        "mobile": [ string ],
        "homephone": [ string ],
        "extension": [ string ],
        "facsimiletelephonenumber": [ string ],
        "sip": [ string ],
        "email": [ string ],
        "url": string,
        "description": string,
        "info": string,
        "roomnumber": string,
        "city": string,
        "street": string,
        "postalcode": string,
        "state": string,
        "country": string,
        "privatecity": string,
        "privatestreet": string,
        "privatepostalcode": string,
        "privatestate": string,
        "privatecountry": string
    },
    "guid": string,
    "pbx": string,
    "node": string,
    "template": string,
    "adjust": bool
}

guid: Optional.; GUID of the related user object in the PBX
pbx: Optional.; Location of the related user object in the PBX
node: Optional.; Node of the related user object in the PBX
template: Optional.; Config template of the related user object in the PBX
adjust: Optional.; Indicates that provided phone numbers might not contain the external line prefix and might need to be adjusted by the phone/softphone app before dialing.

Details for type "app"

This type is used for apps or pages inside apps. The corresponding detail object has no defined attributes at the moment, so it is empty.

Examples:

{
    "mt": "SearchInfo",
    "dn": "UsersAdmin",
    "type": "app",
    "app": {},
    "link": "usersadmin",
    "relevance": 2000,
    "photourl": "http://localhost:10008/appproxy/ext/aps.example.com/example.com/usersapp/innovaphone-usersadmin.png"
}

{
    "mt": "SearchInfo",
    "dn": "Call diversions",
    "type": "app",
    "app": {},
    "link": "profile?page=call-diversions#d=Call%20diversions",
    "relevance": 1000
}

Details for type "message"

This type is used for messages. The detail object contains the message details.

{
    "mt": "SearchInfo",
    "dn": string,
    "type": "message",
    "link": "messages?discussion=2054900&message=2756759",
    "message": {
        "author": string,
        "dn": string,
        "text": string,
        "timestamp": number
    }
}

author: The SIP URI of the author.
dn: The display name of the author.
text: The text of the message. Can be plain text or HTML.
timestamp: The UTC timestamp of the message.

Examples:

{
  "mt": "SearchInfo",
  "dn": "Connect ",
  "link": "connect?discussion=4&message=5",
  "dontAttach": true,
  "relevance": 500,
  "type": "message",
  "message": {
    "author": "alice",
    "dn": "Alice",
    "text": "@bob can you please call me back?",
    "timestamp": 1719411290879
  }
}

Details for type "device"

This type is used for devices. The detail object contains the device details.

{
    "mt": "SearchInfo",
    "dn": string,
    "type": "device",
    "link": "devices?header=devices&listItem=009033410fcb&contentId=adminUi",
    "device": {
      "hwId": string,
      "product": string,
      "ethIfs": [{
        "if": string,
        "ipv4": string,
        "ipv6": string
      }],
      "online": bool,
      "version": string
    }
}

hwId: The MAC address of the device.
product: The product name of the device.
ethIfs: Network interfaces of the device.
if: The name of the network interface.
ipv4: The IPv4 address of the network interface. Optional
ipv6: The IPv6 address of the network interface. Optional
online: True, if the device is online.
version: The software version of the device.

Examples:

{
  "mt": "SearchInfo",
  "dn": "PBX Berlin ",
  "link": "devices?header=devices&listItem=009033410fcb&contentId=adminUi",
  "relevance": 500,
  "type": "device",
  "device": {
      "hwId": "009033410fcb",
      "product": "IP811",
      "ethIfs": [{
        "if": "ETH0",
        "ipv4": "192.168.0.210",
        "ipv6": "fec0:9033:0:230:290:33ff:fe41:ca"
      }],
      "online": true,
      "version": "14r2 beta3 [1420276/1420276/600]"
   }
}

SearchResult

This message is sent by the API provider when the search has been completed and no further SearchInfo messages will be sent.

{
    "mt": "SearchResult",
    "src": string
}