# 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,
        "count":number
    }

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.
count
  The maximum count of search results per provider (if implemented by the provider).
  Optional. Omit to get the default number of search results implemented by the provider.

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"
    }

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

### 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
    }