Blueticks

Realtime messages (MQTT)

Receive incoming WhatsApp messages over an outbound MQTT connection, when you have no public URL for a webhook.

Webhooks need a URL that the internet can reach. If you don't have one, you can dial out instead: trade your API key for an MQTT credential, connect to the broker, and subscribe. Nothing on your side has to be exposed.

The stream carries the same incoming-message payload as new_message_received_webhook.

1. Get a credential

Call POST /v1/realtime/token with your API key. The key needs the chats:read scope. A successful call returns 201.

curl -X POST 'https://api.blueticks.co/v1/realtime/token' \  -H 'Authorization: Bearer BLUETICKS_API_KEY'
{  "success": true,  "data": {    "brokerUrl": "string",    "username": "string",    "password": "string",    "expiresAt": "2026-01-01T00:00:00Z",    "expiresInSeconds": 0,    "topics": {      "messages": "string"    }  }}
FieldMeaning
brokerUrlMQTT over WebSocket, for example wss://mqtt.blueticks.co:443/mqtt.
usernameYour user id. Send it exactly as given.
passwordA JWT. Send it as the MQTT password.
expiresAt, expiresInSecondsWhen the credential stops being accepted. It is set far in the future, so fetching it once at start-up is enough.
topics.messagesThe one topic you can subscribe to.

Treat password like a secret. Revoking the API key does not invalidate a credential that was already issued from it, so don't log it or ship it to browsers.

2. Connect and subscribe

Connect with any MQTT client that speaks MQTT over WebSocket, using the three values from the response. This example uses the mqtt package for Node.js:

import mqtt from 'mqtt';

const { data } = await (
  await fetch('https://api.blueticks.co/v1/realtime/token', {
    method: 'POST',
    headers: { Authorization: `Bearer ${process.env.BLUETICKS_API_KEY}` },
  })
).json();

const client = mqtt.connect(data.brokerUrl, {
  username: data.username,
  password: data.password,
});

client.on('connect', () => client.subscribe(data.topics.messages, { qos: 1 }));

client.on('message', (_topic, payload) => {
  const { eventType, data: message, _timestamp } = JSON.parse(payload.toString());
  console.log(eventType, message.waMessageKey?._serialized);
});

3. What arrives

The topic is users/{userId}/downstream/messages. Use the value of topics.messages rather than building it yourself.

Each MQTT message is a JSON object:

FieldTypeNotes
eventTypestringmessages.
dataobjectThe message. Same fields as in new_message_received_webhook.
_timestampnumberWhen Blueticks published it, in milliseconds.

This is not the webhook envelope. There is no id, type, created_at or idempotency_key; the message is under data.

Blueticks publishes with QoS 1, so a message can be delivered more than once. De-duplicate on data.waMessageKey._serialized.

Which messages are on the stream

  • Incoming messages: always.
  • Messages sent from your own account: only when the account's include-my-own-messages preference is on. It is off by default, and there is no switch for it in the dashboard yet. When it is on, these arrive in the shape of new_message_received_from_me_webhook.
  • Nothing else. Delivery status, reactions, group activity and the other events are webhook-only. Use webhooks for those.