Skip to content
This repository contains the open source Java client for MessageBird's REST API.
Branch: master
Clone or download
Latest commit 2134881 Nov 1, 2019
Type Name Latest commit message Commit time
Failed to load latest commit information.
api updated Nov 1, 2019
.gitignore Added verify api to java client Dec 10, 2015
.travis.yml Add support for updating Conversations webhooks Jul 4, 2019
LICENSE CI timed out again Sep 6, 2019

MessageBird's REST API for Java

This repository contains the open source Java client for MessageBird's REST API. Documentation can be found at:

Build Status Maven metadata URI


  • Sign up for a free MessageBird account
  • Create a new access key in the developers sections
  • An application written in Java
  • Installed version of maven


The easiest way to install the MessageBird package is either via github:

git clone
cd java-rest-api/api
mvn install

If you are using maven, please refer to the mvn repository and choose your desired package version.


We have put some self-explanatory examples in the examples directory, but here is a quick example on how to get started. Assuming the installation was successful, you can import the messagebird package like this:

import com.messagebird.MessageBirdClient;
import com.messagebird.MessageBirdService;
import com.messagebird.MessageBirdServiceImpl;
import com.messagebird.objects.MessageResponse;
import com.messagebird.exceptions.GeneralException;
import com.messagebird.exceptions.UnauthorizedException;

import java.math.BigInteger;
import java.util.ArrayList;
import java.util.List;

Then, create an instance of MessageBirdClient:

// Create a MessageBirdService
final MessageBirdService messageBirdService = new MessageBirdServiceImpl("test_gshuPaZoeEG6ovbc8M79w0QyM");
// Add the service to the client
final MessageBirdClient messageBirdClient = new MessageBirdClient(messageBirdService);

Now you can query the API for information or send a request. For example, if we want to request our balance information you'd do something like this:

    try {
        // Get Balance
        System.out.println("Retrieving your balance:");
        final Balance balance = messageBirdClient.getBalance();

        // Display balance

    } catch (UnauthorizedException unauthorized) {
        if (unauthorized.getErrors() != null) {
    } catch (GeneralException generalException) {
        if (generalException.getErrors() != null) {

This will give you something like:

Retrieving your balance:
Balance{payment='prepaid', type='credits', amount=97}

To try out the command line examples follow the above build instructions. When everything did build successful you can try out the API like this:

cd examples/target
java -cp examples-1.2.0-jar-with-dependencies.jar ExampleSendMessage test_gshuPaZoeEG6ovbc8M79w0QyM 31612345678 "This is a test message"

Please see the other examples for a complete overview of all the available API calls.

Running with unit tests

Running unit tests requires you to create a developer key. You can create one for free at, or when you have one already you can skip registration and go to to create or get your test access key. Once you have such key you can run the unit tests like this:

mvn test -Ptest -DmessageBirdAccessKey=[your access key] -DmessageBirdMSISDN=[your phone]

This will run all unit tests and verifies if everything is running as expected.

Note: If you use by accident use your live key it will send messages and will remove it from your account, please ensure you use your test key to run your unit tests to avoid loosing your credits.

Proxy support

If you server doesn't have a direct connection to the internet you can setup a proxy to for the MessageBird service to use.

    final Proxy proxy = new Proxy(Proxy.Type.HTTP, new InetSocketAddress("", 8080));
    final MessageBirdService messageBirdService = new MessageBirdServiceImpl("test_gshuPaZoeEG6ovbc8M79w0QyM");
Conversations WhatsApp Sandbox

To use the whatsapp sandbox you need to add MessageBirdClient.ENABLE_CONVERSATION_API_WHATSAPP_SANDBOX to the list of features you want enabled. Don't forget to replace YOUR_ACCESS_KEY with your actual access key.

    // Create a MessageBirdService
    final MessageBirdService messageBirdService = new MessageBirdServiceImpl("YOUR_ACCESS_KEY");
    // Add the service to the client
    final MessageBirdClient messageBirdClient = new MessageBirdClient(messageBirdService, List.of(MessageBirdClient.Feature.ENABLE_CONVERSATION_API_WHATSAPP_SANDBOX));


Complete documentation, instructions, and examples are available at:


The MessageBird REST Client for Java is licensed under The BSD 2-Clause License. Copyright (c) 2015-2019, MessageBird

You can’t perform that action at this time.