Jump to: navigation, search


This operation is part of the IM Session API section of the Web Services API.


Initiates a new IM session. The operation fails if Web Services can't find any suitable devices or if a "devicePath" is not specified when multiple devices are capable of initiating IM sessions.

An agent can't participate in more than one IM session at a time — any attempts to initiate a second IM session returns an "Invalid state" error message in the response.

Request URL /api/v2/me/im-sessions
Required Features api-voice-instant-messaging


Parameter Value
operationName InitiateIMSession
destination The number to reach. This should represent a SIP extension that supports IM. (mandatory)

To enable IM communication, both agents must be logged in on a place with a SIP multimedia DN — that is, a SIP DN configured with the following Annex options in the [TServer] section:

  • multimedia option set to true
  • sip-signalling-chat option set to none
userData The user data to attach to the IM session. (optional)
devicePath The path to a device assigned to the current user that is to be used for the operation. This parameter is not necessary if there is only one device assigned to the agent that is capable of handling an IM session (optional).



POST api/v2/me/im-sessions
  "operationName": "InitiateIMSession",
  "destination": {
    "phoneNumber": "16001"
  "userData": {
    "favColor": "blue"

HTTP Response

  "statusCode": 0

CometD Response

      "state":" Talking",
         "favColor": "blue"
      "uri": "http://hpe-voicevm-64.genesyslab.com:8090/api/v2/im-sessions/00S4UMMDT8AHN1VL807GK2LAES000002", 
      "participants": [
            "digits": "3002",
            "e164Number": "3002",
            "formattedPhoneNumber": "3002",
            "phoneNumber": "3002"
This page was last edited on January 22, 2016, at 19:56.
Comments or questions about this documentation? Contact us for support!