MessageBird (now Bird)

2.2.0 verified Tue May 12 auth: no python install: verified quickstart: stale deprecated

MessageBird rebranded as Bird in February 2024. The old messagebird PyPI package (last version 2.2.0, released 2022) is no longer maintained and targets the legacy API. The new Python SDK is bird-python on PyPI, targeting the Bird API at docs.bird.com. LLMs almost universally generate the old package name.

pip install messagebird

Common errors

error ModuleNotFoundError: No module named 'messagebird' ↓

cause The `messagebird` package is not installed in your Python environment, or there's a typo in the import statement, or the environment where the code is run does not have access to the installed package.

fix

Install the correct package. If you intend to use the legacy MessageBird API, install the old package: pip install messagebird. If you intend to use the current Bird API, install the new SDK: pip install bird-python and update your import statements (e.g., from bird import Client).

error messagebird.client.ErrorException: {'code': 2, 'description': 'Request not allowed (incorrect access_key)', 'parameter': 'access_key'} ↓

cause This error indicates that the API key provided is invalid, expired, or does not have the necessary permissions for the requested operation. It's often caused by typos, using a test key for live operations, or an API key for a different MessageBird product.

fix

Verify that your API access key is correct, active, and has the appropriate permissions. Ensure you are using a live API key for sending actual messages and not a test key, which only validates API requests. Check your MessageBird (now Bird) dashboard under 'Developers' -> 'API access' for the correct keys.

error AttributeError: 'str' object has no attribute 'items' ↓

cause This error typically occurs when the `messagebird` client library expects a dictionary or an object with an `items()` method for recipient data, but receives a string instead, often due to an incompatibility between the client library version and the API response or incorrect data formatting.

fix

Ensure that the data structure passed for recipients (or other parameters expecting an iterable or dictionary) is correct according to the messagebird SDK's expectations (e.g., a list of Recipient objects or a dictionary structure with an 'items' key). Review the specific API method's documentation for the expected input format. If using an old SDK, consider updating to bird-python and adapting your code to the new API specifications.

error messagebird messages are not being delivered ↓

cause This is a common observation, not a Python traceback, where the code executes without error but SMS or voice messages are not actually received. A frequent cause is using a 'test API key' which only validates the request format without sending actual messages, or issues with recipient number formatting/validity.

fix

Switch from a 'test API key' to a 'live API key' in your MessageBird (Bird) account credentials. Ensure the recipient phone number is correctly formatted (E.164 format) and is a valid, reachable number capable of receiving the message type (SMS/voice). Check your MessageBird dashboard's API logs for specific delivery failure codes if the issue persists.

error ModuleNotFoundError: No module named 'bird' ↓

cause You have installed the legacy 'messagebird' package, but the current Bird API SDK (installed as 'bird-python') imports under the module name 'bird'.

fix

Uninstall the legacy 'messagebird' package with 'pip uninstall messagebird' and install the correct SDK with 'pip install bird-python'.

Warnings

breaking MessageBird rebranded as Bird in February 2024. The messagebird PyPI package (2.2.0) is unmaintained and targets the legacy API. New features (workspaces, channels, WhatsApp via Bird API) are only available in the bird-python package. ↓

fix pip uninstall messagebird && pip install bird-python. Update API documentation reference from developers.messagebird.com to docs.bird.com.

breaking The new Bird API has a completely different message-sending model. Instead of client.message_create(src, dst, text), it uses workspace + channel selection followed by client.send_message(channels_id, body). All old code patterns break. ↓

fix Set workspace: client.workspaces = client.workspace_list()['results'][0]['id']. Get channel ID: client.channel_list(). Then send with the new body format.

gotcha Both the old messagebird package and the new bird-python package use import messagebird as the import statement. This makes it impossible to tell from the import line alone which API version the code targets. ↓

fix Check which PyPI package is installed (pip show messagebird vs pip show bird-python). The new Bird API requires workspace/channel setup before sending.

gotcha Access keys from the old MessageBird dashboard may not work with the new Bird API. The Bird platform uses a new authentication system via manage.bird.com. ↓

fix Generate new API keys at manage.bird.com. Old keys from manage.messagebird.com may be valid during transition but should be rotated.

Install

pip install bird-python

Install compatibility verified last tested: 2026-05-12

python os / libc variant status wheel install import disk

3.10 alpine (musl) bird-python - - - 70.0M

3.10 alpine (musl) messagebird - - - 22.9M

3.10 slim (glibc) bird-python - - - 141M

3.10 slim (glibc) messagebird - - - 23M

3.11 alpine (musl) bird-python - - - 76.7M

3.11 alpine (musl) messagebird - - - 24.9M

3.11 slim (glibc) bird-python - - - 148M

3.11 slim (glibc) messagebird - - - 25M

3.12 alpine (musl) bird-python - - - 67.2M

3.12 alpine (musl) messagebird - - - 16.6M

3.12 slim (glibc) bird-python - - - 138M

3.12 slim (glibc) messagebird - - - 17M

3.13 alpine (musl) bird-python - - - 63.7M

3.13 alpine (musl) messagebird - - - 16.3M

3.13 slim (glibc) bird-python - - - 137M

3.13 slim (glibc) messagebird - - - 17M

3.9 alpine (musl) bird-python - - - 69.0M

3.9 alpine (musl) messagebird - - - 22.2M

3.9 slim (glibc) bird-python - - - 141M

3.9 slim (glibc) messagebird - - - 23M

Imports

messagebird.Client

wrong

# pip install messagebird pulls the unmaintained 2.2.0 package
# targeting the old API — new Bird features (workspaces, channels, WhatsApp)
# are not available

correct

# New Bird SDK (post-rebrand 2024):
import messagebird  # import name still messagebird inside bird-python
client = messagebird.Client('YOUR_ACCESS_KEY')

# Legacy API (still works against old rest.messagebird.com):
import messagebird
client = messagebird.Client('YOUR_ACCESS_KEY')
msg = client.message_create('+31612345678', ['+14155551234'], 'Hello!')

The import name messagebird is used in BOTH the old and new SDKs. The difference is which PyPI package you install: messagebird (old, dead) vs bird-python (new, active). The new Bird API has a completely different structure with workspaces and channels.

Quickstart stale last tested: 2026-04-23

New Bird SDK pattern. Requires workspace and channel selection before sending.

# Install: pip install bird-python
import messagebird  # import name unchanged in bird-python

client = messagebird.Client('YOUR_ACCESS_KEY')

try:
    # New Bird API — workspace + channel based
    client.workspaces = client.workspace_list()['results'][0]['id']
    channel_id = client.channel_list()['results'][0]['id']

    response = client.send_message(
        channels_id=channel_id,
        body={
            'receiver': {
                'contacts': [{'identifierValue': '+14155551234'}]
            },
            'body': {
                'type': 'text',
                'text': {'text': 'Hello from Bird!'}
            }
        }
    )
except messagebird.client.ErrorException as e:
    for error in e.errors:
        print(error.description)