MessageBird's REST API for Python

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

Build Status



The easiest way to install the messagebird package is either via pip:

$ pip install messagebird

or manually by downloading the source and run the script:

$ python install


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 messagebird

Then, create an instance of messagebird.Client:

client = messagebird.Client('test_gshuPaZoeEG6ovbc8M79w0QyM')

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:

  # Fetch the Balance object.
  balance = client.balance()

  # Print the object information.
  print('Your balance:\n')
  print('  amount  : %d' % balance.amount)
  print('  type    : %s' % balance.type)
  print('  payment : %s\n' % balance.payment)

except messagebird.client.ErrorException as e:

  for error in e.errors:
    print('  code        : %d' % error.code)
    print('  description : %s' % error.description)
    print('  parameter   : %s\n' % error.parameter)

This will give you something like:

$ python
Your balance:

  amount  : 9 
  type    : credits
  payment : prepaid

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

To run examples with arguments, try:

$ python ./examples/ --accessKey accessKeyWhichNotExist --url --title HELLO_WEBHOOK --token HELLO_TOKEN

Conversations WhatsApp Sandbox

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

  client = messagebird.Client('1ekjMs368KTRlP0z6zfG9P70z', features=[messagebird.Feature.ENABLE_CONVERSATIONS_API_WHATSAPP_SANDBOX])


Complete documentation, instructions, and examples are available at:


The MessageBird REST Client for Python is licensed under The BSD 2-Clause License. Copyright (c) 2014, MessageBird