GoTo
API Status
GoTo

Migration Guide for the Realtime API Subscription Line Types

The Realtime Api is changing from the line subscription entity type to line.v2.

The line entity type is deprecated and is scheduled for end of life on December 15th, 2020. The core change is that the line subscription type behavior is centered around call events, and the line.v2 subscription type exposes events related to specific devices.

The differences this entails will be summarized and explained in three key points.

1. Change in subscription

Whenever your code is subscribing to line events, you must specify the new line.v2 subscription type in the request payload.

For example in the following call for https://realtime.jive.com/v2/session/<sid>/subscriptions

{
  "id":"elisha",
  "type":"dialog",
  "entity": {
    "id":"4b1bb3e3-a7fb-4375-9ea4-2889c6d82783",
    "type":"line.v2",
    "account":"88b57813-109d-4a0b-8ebe-e2807b7436d0"
  }
}

Note: entity.type is line.v2

2. Changes in the data structure websocket frames

Your application should expect the following structure changes in the data object.

  • display field was removed. This information is now in the data.caller.name and data.caller.number fields.
  • remote field was removed, and the participant field (which represents the SIP username), should be used instead.
  • id field is replaced with data.legId.
  • An originatorId field has been introduced and represents the unique id of the entity which triggered the event. This field can be used to group events related to the same line from multiple devices.
  • An ani field has been introduced which represents the phone number the call was made to. If you are operating with call queues, this is used to identify the original dialed number.
  • The state enumeration has changed it value set.
line line.v2
trying CREATED
BRIDGED
early RINGING
confirmed ANSWERED
UNBRIDGED
HANGUP

3. Expect duplicate events if you have multiple devices listening on a line

If you are subscribing to a line which is assigned to multiple devices, you will receive events for each device assigned that line, when a call comes in on it.

Example Scenario

Both a soft-phone (eg. my.jive.com, or any SIP client) and a hard-phone (for example, a physical phone on a desk), are assigned the same line. When a call comes in on that shared line, your application would receive:

  • Two CREATED events; one for each device. You can expect the value of originatorId to be the same for both events.
  • Two RINGING events; one for each device, and at the same time since both devices are ringing.
  • One ANSWERED event; one for the device which answered the call.
  • One BRIDGED event; follows the ANSWERED event related to the answering device.
  • The first HANGUP event; follows the ANSWERED event, but is related to the device which did not answer the call.
  • One UNBRIDGED event; following the termination of the call.
  • The second HANGUP event; from the device which answered the call, after the termination of the call. Following are concrete examples of the events to expect for the above scenario. Take note of the state, originatingId, and the order of the events.
{
  "type": "announce",
  "subId": "sub_line.v2",
  "entityId": "3174",
  "data": {
    "id": "e20fe748-d38f-494e-a5bb-e620a4d5b037-1580469816.132",
    "created": 1580469816381,
    "participant": "5Plu12gc8KF1cLPGMSqj79wTRwbkFB",
    "callee": {
      "name": "John Doe",
      "number": "1001"
    },
    "caller": {
      "name": "example.com",
      "number": "3855553888"
    },
    "direction": "recipient",
    "state": "CREATED",
    "ani": "Mtn Moto <+13855553970>",
    "recordings": [],
    "isClickToCall": false,
    "originatingId": "0bee5456-6a4c-4fa6-9a3c-8140dc0352ec-1580469804.130"
  }
}
{
  "type": "announce",
  "subId": "sub_line.v2",
  "entityId": "3175",
  "data": {
    "id": "51ff0128-9597-4c17-af04-620a40476b94-1580469816.133",
    "created": 1580469816382,
    "participant": "9W0xSyBYuTlEJ0cNLYlS9yRpkuHkwT",
    "callee": {
      "name": "John Doe",
      "number": "1001"
    },
    "caller": {
      "name": "example.com",
      "number": "3855553888"
    },
    "direction": "recipient",
    "state": "CREATED",
    "ani": "Mtn Moto <+13855553970>",
    "recordings": [],
    "isClickToCall": false,
    "originatingId": "0bee5456-6a4c-4fa6-9a3c-8140dc0352ec-1580469804.130"
  }
}
{
  "type": "replace",
  "subId": "sub_line.v2",
  "oldId": "3175",
  "newId": "3176",
  "data": {
    "id": "51ff0128-9597-4c17-af04-620a40476b94-1580469816.133",
    "created": 1580469816382,
    "participant": "9W0xSyBYuTlEJ0cNLYlS9yRpkuHkwT",
    "callee": {
      "name": "John Doe",
      "number": "1001"
    },
    "caller": {
      "name": "example.com",
      "number": "3855553888"
    },
    "direction": "recipient",
    "state": "RINGING",
    "ani": "Mtn Moto <+13855553970>",
    "recordings": [],
    "isClickToCall": false,
    "originatingId": "0bee5456-6a4c-4fa6-9a3c-8140dc0352ec-1580469804.130"
  }
}
{
  "type": "replace",
  "subId": "sub_line.v2",
  "oldId": "3174",
  "newId": "3177",
  "data": {
    "id": "e20fe748-d38f-494e-a5bb-e620a4d5b037-1580469816.132",
    "created": 1580469816381,
    "participant": "5Plu12gc8KF1cLPGMSqj79wTRwbkFB",
    "callee": {
      "name": "John Doe",
      "number": "1001"
    },
    "caller": {
      "name": "example.com",
      "number": "3855553888"
    },
    "direction": "recipient",
    "state": "RINGING",
    "ani": "Mtn Moto <+13855553970>",
    "recordings": [],
    "isClickToCall": false,
    "originatingId": "0bee5456-6a4c-4fa6-9a3c-8140dc0352ec-1580469804.130"
  }
}
{
  "type": "replace",
  "subId": "sub_line.v2",
  "oldId": "3177",
  "newId": "3178",
  "data": {
    "id": "e20fe748-d38f-494e-a5bb-e620a4d5b037-1580469816.132",
    "created": 1580469816381,
    "participant": "5Plu12gc8KF1cLPGMSqj79wTRwbkFB",
    "callee": {
      "name": "John Doe",
      "number": "1001"
    },
    "caller": {
      "name": "example.com",
      "number": "3855553888"
    },
    "direction": "recipient",
    "state": "ANSWERED",
    "ani": "Mtn Moto <+13855553970>",
    "recordings": [],
    "isClickToCall": false,
    "originatingId": "0bee5456-6a4c-4fa6-9a3c-8140dc0352ec-1580469804.130"
  }
}
{
  "type": "withdraw",
  "subId": "sub_line.v2",
  "entityId": "3176",
  "data": {
    "id": "51ff0128-9597-4c17-af04-620a40476b94-1580469816.133",
    "created": 1580469816382,
    "participant": "9W0xSyBYuTlEJ0cNLYlS9yRpkuHkwT",
    "callee": {
      "name": "John Doe",
      "number": "1001"
    },
    "caller": {
      "name": "example.com",
      "number": "3855553888"
    },
    "direction": "recipient",
    "state": "HUNGUP",
    "ani": "Mtn Moto <+13855553970>",
    "recordings": [],
    "isClickToCall": false,
    "originatingId": "0bee5456-6a4c-4fa6-9a3c-8140dc0352ec-1580469804.130"
  }
}
{
  "type": "replace",
  "subId": "sub_line.v2",
  "oldId": "3178",
  "newId": "3180",
  "data": {
    "id": "e20fe748-d38f-494e-a5bb-e620a4d5b037-1580469816.132",
    "created": 1580469816381,
    "participant": "5Plu12gc8KF1cLPGMSqj79wTRwbkFB",
    "callee": {
      "name": "John Doe",
      "number": "1001"
    },
    "caller": {
      "name": "example.com",
      "number": "3855553888"
    },
    "direction": "recipient",
    "state": "BRIDGED",
    "ani": "Mtn Moto <+13855553970>",
    "recordings": [],
    "isClickToCall": false,
    "originatingId": "0bee5456-6a4c-4fa6-9a3c-8140dc0352ec-1580469804.130"
  }
}
{
  "type": "replace",
  "subId": "sub_line.v2",
  "oldId": "3180",
  "newId": "3181",
  "data": {
    "id": "e20fe748-d38f-494e-a5bb-e620a4d5b037-1580469816.132",
    "created": 1580469816381,
    "participant": "5Plu12gc8KF1cLPGMSqj79wTRwbkFB",
    "callee": {
      "name": "John Doe",
      "number": "1001"
    },
    "caller": {
      "name": "example.com",
      "number": "3855553888"
    },
    "direction": "recipient",
    "state": "UNBRIDGED",
    "ani": "Mtn Moto <+13855553970>",
    "recordings": [],
    "isClickToCall": false,
    "originatingId": "0bee5456-6a4c-4fa6-9a3c-8140dc0352ec-1580469804.130"
  }
}
{
  "type": "withdraw",
  "subId": "sub_line.v2",
  "entityId": "3181",
  "data": {
    "id": "e20fe748-d38f-494e-a5bb-e620a4d5b037-1580469816.132",
    "created": 1580469816381,
    "participant": "5Plu12gc8KF1cLPGMSqj79wTRwbkFB",
    "callee": {
      "name": "John Doe",
      "number": "1001"
    },
    "caller": {
      "name": "example.com",
      "number": "3855553888"
    },
    "direction": "recipient",
    "state": "HUNGUP",
    "ani": "Mtn Moto <+13855553970>",
    "recordings": [],
    "isClickToCall": false,
    "originatingId": "0bee5456-6a4c-4fa6-9a3c-8140dc0352ec-1580469804.130"
  }
}