1. Publish/Subcribe Principle

With Stringee, Client Apps can monitor status of each other in real-time, like:

  • Call status.
  • Online status.
  • Any attribute defined by the developer.

Publish/Subscribe

If client A wants to monitor the change of an attribute of Client B, both sides have to define a topic, i.g. topic_1

  • Client A subscribes to topic_1
  • When there is any attribute of Client B changes, Client B will publish the change to topic_1
  • Client A will receive notification from topic_1

2. Decide to use Publish/Subcribe in Access Token

To allow an App to Publish or to Subcribe to a Topic, you can add "subscribe" values and "attributes" array into the Access Token Payload; read more about Access Token here.

To be specific, you add at least 1 of 2 fields below in to the Payload:

  • subscribe: List of Topics the App wants to subcribe to, separated by the comma (,)
  • attributes: Arrays of attributes the App wants to publish if there is any change, and the target Topic.
[{
    "attribute": "ATTRIBUTE_NAME",
    "topic" "TOPIC_NAME"
}]

There are 2 default attributes (you can't define new attributes with same name):

  • onlineStatus: Online status of the Client App
  • call: Status of the Call (Calling/Ringing/Answered/Ended)

*Besides those 2 attributes, you can define new ones freely for the Clients. *

There is 1 default Topic:

  • ALL_CALL_STATUS: When status of a Call changes, Stringee system will publish the change to this topic (Call to any user)

An example of Access Token Payload:

{
    "jti": "...-1554197947",
    "iss": "...",
    "exp": 1555197947,
    "userId": "agent_1",
    "subscribe": "online_status_GRDHG0HI,ALL_CALL_STATUS,agent_manual_status",
    "attributes": [{
        "attribute": "onlineStatus",
        "topic": "online_status_GRDHG0HI"
    },
    {
        "attribute": "call",
        "topic": "call_GRDHG0HI"
    },
    {
        "attribute": "manual_status",
        "topic": "agent_manual_status"
    }
    ]
}

After being authorized with above Access Token, the App will:

Subscribe to Topics:

  1. online_status_GRDHG0HI
  2. ALL_CALL_STATUS
  3. agent_manual_status

Publish:

  1. Online status, to the Topic online_status_GRDHG0HI
  2. Call status, to the Topic call_GRDHG0HI
  3. Attribute manual_status, to the Topic agent_manual_status

3. Get current attributes of an user

GET https://api.stringee.com/v1/users/USER_ID

Response:

{
    "loginTime": 1554204151774,
    "attributes": [
        {
            "attribute": "onlineStatus",
            "value": "online"
        },
        {
            "attribute": "call"
        },
        {
            "attribute": "app_is_foreground",
            "value": true
        }
    ],
    "chatCustomer": false,
    "userId": "USER_ID"
}

Notice: REST API must be authorized, more details at: https://developer.stringee.com/docs/call-rest-api/call-rest-api-authentication

4. Change attributes of an user

a) By REST API

PUT https://api.stringee.com/v1/users/USER_ID/attributes

[
    {
        "attribute": "ATTRIBUTE_NAME",
        "value": "NEW_VALUE"
    }
]

Response:

{
    "loginTime": 1554204151774,
    "attributes": [
        {
            "attribute": "onlineStatus",
            "value": "online"
        },
        {
            "attribute": "call"
        },
        {
            "attribute": "ATTRIBUTE_NAME",
            "value": "NEW_VALUE"
        }
    ],
    "chatCustomer": false,
    "userId": "USER_ID"
}

Notice: REST API must be authorized, more details at: https://developer.stringee.com/docs/call-rest-api/call-rest-api-authentication

b) From Client App

Call function:

stringeeClient.changeAttribute('ATTRIBUTE_NAME', "NEW_VALUE")

5. Client Apps receives notification of changes from subcribed Topics

stringeeClient.on('messagefromtopic', function (data) {
    console.log('++++++++++++++ messagefromtopic++++', data);
});

Format of returned data (response):

{
    "topic": "online_status_GRDHG0HI",
    "message": {
        "newValue": "online",
        "callEnded": true,
        "attribute": "onlineStatus",
        "userId": "user_1",
        "projectId": 25,
        "timestamp": 1554261314286
    }
}