Reachability Indicator

Each Service instance can have Reachability enabled or disabled. The default is disabled. Reachability state will not be updated if the feature is disabled for a given Service instance. Once enabled, the state will update and synchronize.

You must set the ReachabilityEnabled property using the Services REST resource to configure the Reachability Indicator feature.

To see if the feature is enabled for a Service instance, please refer to the reachability_enabled property of the Service REST resource representation.

1
curl -X POST https://chat.twilio.com/v1/Services/{service sid} \
2
 -d 'ReachabilityEnabled=true' \
3
 -u '{twilio account sid}:{twilio auth token}'

If you choose to enable Reachability Indicators and later wish to return to disabled, set the ReachabilityEnabled back to false.

1
// Download the helper library from https://www.twilio.com/docs/node/install
2
const twilio = require("twilio"); // Or, for ESM: import twilio from "twilio";
3

4
// Find your Account SID and Auth Token at twilio.com/console
5
// and set the environment variables. See http://twil.io/secure
6
const accountSid = process.env.TWILIO_ACCOUNT_SID;
7
const authToken = process.env.TWILIO_AUTH_TOKEN;
8
const client = twilio(accountSid, authToken);
9

10
async function updateService() {
11
  const service = await client.chat.v2
12
    .services("ISXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX")
13
    .update({ reachabilityEnabled: false });
14

15
  console.log(service.sid);
16
}
17

18
updateService();

1
{
2
  "account_sid": "ACaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
3
  "consumption_report_interval": 100,
4
  "date_created": "2015-07-30T20:00:00Z",
5
  "date_updated": "2015-07-30T20:00:00Z",
6
  "default_channel_creator_role_sid": "RLaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
7
  "default_channel_role_sid": "RLaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
8
  "default_service_role_sid": "RLaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
9
  "friendly_name": "friendly_name",
10
  "limits": {
11
    "channel_members": 500,
12
    "user_channels": 600
13
  },
14
  "links": {
15
    "channels": "https://chat.twilio.com/v2/Services/ISaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Channels",
16
    "users": "https://chat.twilio.com/v2/Services/ISaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Users",
17
    "roles": "https://chat.twilio.com/v2/Services/ISaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Roles",
18
    "bindings": "https://chat.twilio.com/v2/Services/ISaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Bindings"
19
  },
20
  "notifications": {
21
    "log_enabled": true,
22
    "added_to_channel": {
23
      "enabled": false,
24
      "template": "notifications.added_to_channel.template"
25
    },
26
    "invited_to_channel": {
27
      "enabled": false,
28
      "template": "notifications.invited_to_channel.template"
29
    },
30
    "new_message": {
31
      "enabled": false,
32
      "template": "notifications.new_message.template",
33
      "badge_count_enabled": true
34
    },
35
    "removed_from_channel": {
36
      "enabled": false,
37
      "template": "notifications.removed_from_channel.template"
38
    }
39
  },
40
  "post_webhook_url": "post_webhook_url",
41
  "pre_webhook_url": "pre_webhook_url",
42
  "pre_webhook_retry_count": 2,
43
  "post_webhook_retry_count": 3,
44
  "reachability_enabled": false,
45
  "read_status_enabled": false,
46
  "sid": "ISXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
47
  "typing_indicator_timeout": 100,
48
  "url": "https://chat.twilio.com/v2/Services/ISaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
49
  "webhook_filters": [
50
    "webhook_filters"
51
  ],
52
  "webhook_method": "webhook_method",
53
  "media": {
54
    "size_limit_mb": 150,
55
    "compatibility_message": "new media compatibility message"
56
  }
57
}

The Reachability indicators are exposed for Users in two places:

• REST API - Users resource
• Client SDKs - User and UserDescriptor objects

The following read-only properties within the Users REST resource provide Reachability information for Users:

• is_online
• is_notifiable

These properties are set by the Chat system if the Reachability Indicator feature is enabled for a User's Service instance.

Note: These properties can be null under the following conditions:

• The Reachability Indicator feature is disabled for the Service instance
• The User has not been online since the Reachability indicator has been enabled
• LIST GET resource representations only have a true or false value for specific GET requests

Please see the REST Users resource documentation for more information.

Within the Chat Client SDKs, the Reachability Indicator properties are exposed in the User and UserDescriptor objects.

Real-time updates to other Users' Reachability Indicator states are communicated via the update event mechanism for subscribed User objects. Reachability on UserDescriptor objects is a snapshot in time. Please see the specific SDK API documentation for details, as each SDK/platform handles this update a little differently.

An indicator of your Service instance's Reachability status (reachability_enabled ) is also exposed at the SDK client level.

The read only client SDK properties exposed are:

• ChatClient.reachabilityEnabled
• User.isOnline and UserDescriptior.isOnline
• User.isNotifiable and UserDescriptor.isNotifiable

Note: The above are representations. The specifics of how these properties are accessed are distinct for each language/SDK.

Note: These user properties are read only and cannot be set. Chat will update these settings and synchronize them as necessary. The Service REST resource manages the Service-level Reachability feature.

Handle an UpdateReason change and process the Reachability Indicators

1
// function called after client init to set up event handlers
2
function registerEventHandlers() {
3
  user = chatClient.user;
4
  // Register User updated event handler
5
  user.on('updated', event => handleUserUpdate(event.user, event.updateReasons));
6
}
7

8
// function to handle User updates
9
function handleUserUpdate(user, updateReasons) {
10
  // loop over each reason and check for reachability change
11
  updateReasons.forEach(reason =>
12
    if (reason == 'online') {
13
      //do something
14
    }
15
  )
16
}
17

Next: Push Notification Configuration