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.
displayfield was removed. This information is now in thedata.caller.nameanddata.caller.numberfields.remotefield was removed, and theparticipantfield (which represents theSIPusername), should be used instead.idfield is replaced withdata.legId.- An
originatorIdfield 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
anifield 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
stateenumeration 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
originatorIdto 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"
}
}
- How much do the LogMeIn APIs cost?
- How do I get started?
- How do I get support for the APIs?
- Can I access more than one product API?
- What are the rate limits for the APIs?
- How to login or create a developer account
- How to create an OAuth client
- How to obtain an access token
- How to obtain and use refresh tokens
- How to use Postman API collections
- GoToWebinar webhooks
- How to use GoToWebinar webhooks
- Date and time conventions
- Paging, Sorting & Filtering Output
- OAuth Migration Guide
- Direct Login Migration
- Migrating from GoToConnect to LogMeIn Authentication API
- Migration Guide for the Realtime API Subscription Line Types
- Introduction
- Java SDK
- .NET SDK
- SDK License Agreement
FAQ
HowTos
References
SDKs