1 of 1

REST API & Webhooks

Documentation for BlueBubbles REST API & Webhooks

The REST API is currently only compatible with https Ngrok, Cloudflare, or Dynamic DNS connections with valid SSL certificates (when used in a Browser). We hope to add support for LocalTunnel in the near future. If you plan to use the REST API in a non-browser environment, it should work as expected.

The REST API requires server version 0.2.0 or greater, though we recommend you use the latest server as some methods in the documentation may not exist on older versions. Webhooks require server version 1.0.0 or greater.

API Wrappers

https://git.elliotnash.org/elliotnash/blueify (Java)

Who's Using It?

If you've built something using the API or webhooks that you'd like to share, let us know on our Discord!

API Documentation

Authentication

Most requests require authentication. Simply add the query parameter guid (aliases include password & token) to the end of the request URL, with the server password as the value.

For example: https://some-url.ngrok.io/api/v1/ping?guid=password

Response Format

All requests are returned with the basic format as below:

{
    status: (int) Status Code,
    message: (String) Status Message,
    data: (Variable)
}

Or in the case of an error:

{
    status: (int) Status Code,
    message: (String) Status Message,
    error: {
        type: (String) Error Type,
        error: (String) Error Message
    },
    data?: (any)
}

Webhooks

We support listening to the following events:

New Messages
Message Updates (delivered, read, etc)
Message Errors
Group Name Changes
Participant Added / Removed / Left
Chat Read Status Changes
Typing Indicators
BB Server Update
BB Server URL Change
Hello World (for testing)

You can also subscribe to an event that listens to all of the above at once.

Simply provide a URL and the server will POST to it whenever your desired event occurs.

REST API & Webhooks

Documentation for BlueBubbles REST API & Webhooks

API Wrappers

https://git.elliotnash.org/elliotnash/blueify (Java)

Who's Using It?

If you've built something using the API or webhooks that you'd like to share, let us know on our Discord!

API Documentation

Authentication

Most requests require authentication. Simply add the query parameter guid (aliases include password & token) to the end of the request URL, with the server password as the value.

For example: https://some-url.ngrok.io/api/v1/ping?guid=password

Response Format

All requests are returned with the basic format as below:

{
    status: (int) Status Code,
    message: (String) Status Message,
    data: (Variable)
}

Or in the case of an error:

{
    status: (int) Status Code,
    message: (String) Status Message,
    error: {
        type: (String) Error Type,
        error: (String) Error Message
    },
    data?: (any)
}

Webhooks

We support listening to the following events:

New Messages
Message Updates (delivered, read, etc)
Message Errors
Group Name Changes
Participant Added / Removed / Left
Chat Read Status Changes
Typing Indicators
BB Server Update
BB Server URL Change
Hello World (for testing)

You can also subscribe to an event that listens to all of the above at once.

Simply provide a URL and the server will POST to it whenever your desired event occurs.