Reachability Indicator

The Reachability Indicator feature of Programmable Chat provides visibility into whether a User is online or offline within the Chat Service instance context. This feature also provides the User's reachability by Push Notification within the Chat Service instance.

Reachability state is automatically updated and synchronized by the Chat service, provided the feature is enabled. The feature is enabled on a "per Service instance" basis.

Note: It is important to note that Users exist within the scope of a Chat Service instance. Thus, the Reachability indicators are also within the same scope.

Enable the 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.

Loading Code Samples...
Language
curl -X POST https://chat.twilio.com/v1/Services/{service sid} \ 
 -d 'ReachabilityEnabled=true' \
 -u '{twilio account sid}:{twilio auth token}'
Enable the Reachability Indicator

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

Loading Code Samples...
Language
SDK Version:
  • 5.x
SDK Version:
  • 7.x
SDK Version:
  • 3.x
SDK Version:
  • 5.x
SDK Version:
  • 6.x
SDK Version:
  • 5.x
Format:
  • JSON
const accountSid = 'ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX';
const authToken = 'your_auth_token';
const Twilio = require('twilio').Twilio;

const client = new Twilio(accountSid, authToken);

client.chat
  .services('ISXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX')
  .update({
    reachabilityEnabled: 'false',
  })
  .then(response => {
    console.log(response);
  })
  .catch(error => {
    console.log(error);
  });
// Download the twilio-csharp library from twilio.com/docs/libraries/csharp
using System;
using Twilio;
using Twilio.Rest.Chat.V2;

class Example
{
    static void Main(string[] args)
    {
        // Find your Account SID and Auth Token at twilio.com/console
        const string accountSid = "ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX";
        const string authToken = "your_auth_token";
        const string serviceSid = "ISXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX";

        TwilioClient.Init(accountSid, authToken);

        var service = ServiceResource.Update(serviceSid,
                                             reachabilityEnabled: false);

        Console.WriteLine(service.ReachabilityEnabled);
    }
}
<?php

// This line loads the library
require '/path/to/vendor/autoload.php';

use Twilio\Rest\Client;

// Find your Account Sid and Token at twilio.com/console
$sid = "ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX";
$token = "your_auth_token";

// Initialize the client
$client = new Client($sid, $token);

// Update the service
$service = $client->chat
    ->services("ISXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX")
    ->update(
        array("reachabilityEnabled" => false)
    );

echo $service->reachabilityEnabled;
require 'twilio-ruby'

# Get your Account SID and Auth Token from twilio.com/console
account_sid = 'ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX'
auth_token = 'your_auth_token'
service_sid = 'ISXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX'
@client = Twilio::REST::Client.new(account_sid, auth_token)

service = @client.chat.v2.services(service_sid)
response = service.update(reachability_enabled: false)
puts "Reachibility enabled: #{response.reachability_enabled}"
# Download the Python helper library from twilio.com/docs/python/install
from twilio.rest import Client

# Your Account Sid and Auth Token from twilio.com/console
account = "ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX"
token = "your_auth_token"
client = Client(account, token)

service = client.chat.services("ISXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX").update(
    reachability_enabled=False
)

print(service.reachability_enabled)
// Install the Java helper library from twilio.com/docs/java/install
import com.twilio.Twilio;
import com.twilio.rest.chat.v2.Service;

public class Example {
  // Find your Account Sid and Token at twilio.com/console
  public static final String ACCOUNT_SID = "ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX";
  public static final String AUTH_TOKEN = "your_auth_token";

  public static final String SERVICE_SID = "ISXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX";

  public static void main(String[] args) {
    // Initialize the client
    Twilio.init(ACCOUNT_SID, AUTH_TOKEN);

    // Update the service
    Service service = Service.updater(SERVICE_SID).setReachabilityEnabled(false)
        .update();

    System.out.println(service.getReachabilityEnabled());
  }
}
curl -X POST https://chat.twilio.com/v1/Services/{service sid} \ 
 -d 'ReachabilityEnabled=false' \
 -u '{twilio account sid}:{twilio auth token}'
{
  "pre_webhook_url": null,
  "read_status_enabled": true,
  "typing_indicator_timeout": 5,
  "limits": {
    "channel_members": 100,
    "user_channels": 250
  },
  "default_service_role_sid": "RLXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
  "date_updated": "2016-08-30T13:13:10Z",
  "post_webhook_url": null,
  "reachability_enabled": false,
  "friendly_name": "Test service",
  "account_sid": "ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
  "consumption_report_interval": 10,
  "notifications": {
    "new_message": {
      "enabled": false
    },
    "invited_to_channel": {
      "enabled": false
    },
    "removed_from_channel": {
      "enabled": false
    },
    "added_to_channel": {
      "enabled": false
    }
  },
  "webhook_method": null,
  "default_channel_creator_role_sid": "RLXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
  "url": "https://chat.twilio.com/v2/Services/ISXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
  "sid": "ISXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
  "webhook_filters": null,
  "date_created": "2016-08-30T13:13:05Z",
  "default_channel_role_sid": "RLXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
  "links": {
    "channels": "https://chat.twilio.com/v2/Services/ISXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/Channels",
    "users": "https://chat.twilio.com/v2/Services/ISXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/Users",
    "roles": "https://chat.twilio.com/v2/Services/ISXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/Roles"
  }
}
Disable the Reachability Indicator

User Reachability Properties

The Reachability indicators are exposed for Users in two places:

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

REST API

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.

Client SDKs

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.isReachabilityEnabled
  • 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.

Loading Code Samples...
Language
//function called after client init to set up event handlers
function registerEventHandlers() {
    //Register UserInfo specific event handler
    ipMessagingClient.on('userInfoUpdated', handleUserUpdate(user));
}

//function to handle any UserInfo updates
function handleUserUpdate(user) {
    //handle reachability indicator
    if (ipMessagingClient.reachabilityEnabled) {
        //call a function which will update the relevant UI elements to show the Reachability state for the User 
        renderUserReachability(user.online, user.notifiable);
    }
}
Process a UserInfo Update and process the Reachability Indicators
Process a UserInfo Update

Process a UserInfo Update and process the Reachability Indicators

Need some help?

We all do sometimes; code is hard. Get help now from our support team, or lean on the wisdom of the crowd browsing the Twilio tag on Stack Overflow.

1 / 1
Loading Code Samples...
curl -X POST https://chat.twilio.com/v1/Services/{service sid} \ 
 -d 'ReachabilityEnabled=true' \
 -u '{twilio account sid}:{twilio auth token}'
SDK Version:
  • 5.x
SDK Version:
  • 7.x
SDK Version:
  • 3.x
SDK Version:
  • 5.x
SDK Version:
  • 6.x
SDK Version:
  • 5.x
Format:
  • JSON
const accountSid = 'ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX';
const authToken = 'your_auth_token';
const Twilio = require('twilio').Twilio;

const client = new Twilio(accountSid, authToken);

client.chat
  .services('ISXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX')
  .update({
    reachabilityEnabled: 'false',
  })
  .then(response => {
    console.log(response);
  })
  .catch(error => {
    console.log(error);
  });
// Download the twilio-csharp library from twilio.com/docs/libraries/csharp
using System;
using Twilio;
using Twilio.Rest.Chat.V2;

class Example
{
    static void Main(string[] args)
    {
        // Find your Account SID and Auth Token at twilio.com/console
        const string accountSid = "ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX";
        const string authToken = "your_auth_token";
        const string serviceSid = "ISXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX";

        TwilioClient.Init(accountSid, authToken);

        var service = ServiceResource.Update(serviceSid,
                                             reachabilityEnabled: false);

        Console.WriteLine(service.ReachabilityEnabled);
    }
}
<?php

// This line loads the library
require '/path/to/vendor/autoload.php';

use Twilio\Rest\Client;

// Find your Account Sid and Token at twilio.com/console
$sid = "ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX";
$token = "your_auth_token";

// Initialize the client
$client = new Client($sid, $token);

// Update the service
$service = $client->chat
    ->services("ISXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX")
    ->update(
        array("reachabilityEnabled" => false)
    );

echo $service->reachabilityEnabled;
require 'twilio-ruby'

# Get your Account SID and Auth Token from twilio.com/console
account_sid = 'ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX'
auth_token = 'your_auth_token'
service_sid = 'ISXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX'
@client = Twilio::REST::Client.new(account_sid, auth_token)

service = @client.chat.v2.services(service_sid)
response = service.update(reachability_enabled: false)
puts "Reachibility enabled: #{response.reachability_enabled}"
# Download the Python helper library from twilio.com/docs/python/install
from twilio.rest import Client

# Your Account Sid and Auth Token from twilio.com/console
account = "ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX"
token = "your_auth_token"
client = Client(account, token)

service = client.chat.services("ISXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX").update(
    reachability_enabled=False
)

print(service.reachability_enabled)
// Install the Java helper library from twilio.com/docs/java/install
import com.twilio.Twilio;
import com.twilio.rest.chat.v2.Service;

public class Example {
  // Find your Account Sid and Token at twilio.com/console
  public static final String ACCOUNT_SID = "ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX";
  public static final String AUTH_TOKEN = "your_auth_token";

  public static final String SERVICE_SID = "ISXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX";

  public static void main(String[] args) {
    // Initialize the client
    Twilio.init(ACCOUNT_SID, AUTH_TOKEN);

    // Update the service
    Service service = Service.updater(SERVICE_SID).setReachabilityEnabled(false)
        .update();

    System.out.println(service.getReachabilityEnabled());
  }
}
curl -X POST https://chat.twilio.com/v1/Services/{service sid} \ 
 -d 'ReachabilityEnabled=false' \
 -u '{twilio account sid}:{twilio auth token}'
{
  "pre_webhook_url": null,
  "read_status_enabled": true,
  "typing_indicator_timeout": 5,
  "limits": {
    "channel_members": 100,
    "user_channels": 250
  },
  "default_service_role_sid": "RLXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
  "date_updated": "2016-08-30T13:13:10Z",
  "post_webhook_url": null,
  "reachability_enabled": false,
  "friendly_name": "Test service",
  "account_sid": "ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
  "consumption_report_interval": 10,
  "notifications": {
    "new_message": {
      "enabled": false
    },
    "invited_to_channel": {
      "enabled": false
    },
    "removed_from_channel": {
      "enabled": false
    },
    "added_to_channel": {
      "enabled": false
    }
  },
  "webhook_method": null,
  "default_channel_creator_role_sid": "RLXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
  "url": "https://chat.twilio.com/v2/Services/ISXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
  "sid": "ISXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
  "webhook_filters": null,
  "date_created": "2016-08-30T13:13:05Z",
  "default_channel_role_sid": "RLXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
  "links": {
    "channels": "https://chat.twilio.com/v2/Services/ISXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/Channels",
    "users": "https://chat.twilio.com/v2/Services/ISXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/Users",
    "roles": "https://chat.twilio.com/v2/Services/ISXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/Roles"
  }
}
//function called after client init to set up event handlers
function registerEventHandlers() {
    //Register UserInfo specific event handler
    ipMessagingClient.on('userInfoUpdated', handleUserUpdate(user));
}

//function to handle any UserInfo updates
function handleUserUpdate(user) {
    //handle reachability indicator
    if (ipMessagingClient.reachabilityEnabled) {
        //call a function which will update the relevant UI elements to show the Reachability state for the User 
        renderUserReachability(user.online, user.notifiable);
    }
}