Java/Android WebSocket Client

A very lightweight WebSocket client library for Java/Android which aims to implement the WebSocket protocol as defined in RFC 6455.


This library is published into JCenter and Maven Central.


compile 'tech.gusavila92:java-android-websocket-client:1.2.2'



This is an example of how you can start a new connection.

private WebSocketClient webSocketClient;

private void createWebSocketClient() {
    URI uri;
        try {
            uri = new URI("ws://localhost:8080/test");
        catch (URISyntaxException e) {

        webSocketClient = new WebSocketClient(uri) {
            public void onOpen() {
                webSocketClient.send("Hello, World!");

            public void onTextReceived(String message) {

            public void onBinaryReceived(byte[] data) {

            public void onPingReceived(byte[] data) {

            public void onPongReceived(byte[] data) {

            public void onException(Exception e) {

            public void onCloseReceived() {

        webSocketClient.addHeader("Origin", "");

If you don't specify a port into the URI, the default port will be 80 for ws and 443 for wss.

This is the list of the default HTTP Headers that will be included into the WebSocket client handshake

If you wish to include more headers, like Origin, you can add them using addHeader(String key, String value) method.

You can also override the default SSLSocketFactory using setSSLSocketFactory(SSLSocketFactory factory).

When an Exception occurs, the library calls onException(Exception e).

When you are finished using the WebSocket, you can call webSocketClient.close() to close the connection.

Automatic reconnection

Automatic reconnection is supported through enableAutomaticReconnection(long waitTimeBeforeReconnection) method. Every time an IOException occurs, onException(Exception e) method is called and automatically a new connection is created and started. For performance reasons, between every reconnection intent you should specify a wait time before trying to reconnect again, using waitTimeBeforeReconnection parameter.


Connect and read timeouts are supported through setConnectTimeout(int connectTimeout) and setReadTimeout(int readTimeout). If one of those timeouts expires, onException(Exception e) is called. If automatic reconnection is enabled, a new connection could be established automatically.

Connect timeout is used in establishing a TCP connection between this client and the server. Read timeout is used when this WebSocket Client doesn't received data for a long time. A server could send data periodically to ensure that the underlying TCP connection is not closed unexpectedly due to an idle connection, and this read timeout is designed for this purpose.

ws and wss

This library supports secure and insecure WebSockets. You just need to define the scheme as wss or ws (case-sensitive) into the URI.

Ping and Pong frames

When a Ping frame is received, automatically a Pong frame is sent with the same Application Data of the Ping frame. You can also send Ping and Pong frames unsolicited using sendPing(byte[] data) and sendPong(byte[] data). Data can be null if don't want to send Application Data.


You need Gradle to build the project. Any version will do.

gradle build

Then you cand find a .jar file inside the build/libs folder


If you want to open the project in Eclipse, just type

gradle eclipse

and Gradle will automatically generate the source files required to open the project in Eclipse.

IntelliJ IDEA

If you want to open the project in IntelliJ IDEA, just type

gradle idea

and Gradle will automatically generate the source files required to open the project in IntelliJ IDEA.

Minimum requirements

This libary requires at minimum Java 1.6 or Android 1.6 (API 4)


Copyright 2017 Gustavo Avila

Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at

Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.