<!-- BusyBot node reference — https://busybot.net/tools/messagebird/ -->

> Node: MessageBird (`messagebird`) · Action · v1
> Category: Communication · Credentials: MessageBird API (`messageBirdApi`)
> Updated: 2026-08-16

# MessageBird

> Send SMS messages and check account balance via the MessageBird API.

## Overview

MessageBird is a cloud communications platform that provides SMS, voice, and chat APIs. This tool supports sending SMS messages to one or more recipients and retrieving the current account balance. Authentication uses an API access key sent in the Authorization header. The SMS send operation supports scheduling, datacoding, flash messages, gateway selection, group targeting, delivery reporting, and validity windows.

**Category:** Communication  
**Tool Name:** `messagebird`  
**Version:** 1

**Appearance:** Icon: `lucide-MessageSquare` | Color: `#2481D7`

## Node Type

**Action** — processes input items and produces output

## Input / Output

| Direction | Port(s) |
|-----------|--------|
| Input | `Input` |
| Output | `Output`, `Error` |

## Credentials

This tool requires **MessageBird API** credentials.
See the [Credentials Guide](https://busybot.net/credentials/message-bird-api/) for setup instructions.

### Resources

| Resource | Value |
|----------|-------|
| SMS | `sms` |
| Balance | `balance` |

### Operations

| Operation | Value | Description |
|-----------|-------|-------------|
| Send | `send` | Send a text message (SMS) |
| Get | `get` | Get the current balance |

`Send` is the only operation on the SMS resource; `Get` is the only operation on the Balance resource.

### Parameters

`Balance: Get` takes no parameters of its own — see All Operations.

#### SMS: Send

| Parameter | Type | Required | Default | Description |
|-----------|------|----------|---------|-------------|
| From | `string` | Yes | — | The sender phone number or alphanumeric name (max 11 characters). E.g. 14155238886 or MyCompany. Supports expressions. |
| To | `string` | Yes | — | Recipient phone numbers separated by commas. E.g. 14155238886,14155238887. Leading + signs are accepted. Supports expressions like {{ $json.phone }}. |
| Message | `string` | Yes | — | The text content of the SMS message to send. Supports expressions like {{ $json.body }}. |
| Additional Fields | `collection` | No | `{}` | Optional extras applied to the outgoing message. |
| — Created Date-Time | `string` | No | — | The date and time of the creation of the message in RFC3339 format (Y-m-dTH:i:sP). Supports expressions. |
| — Datacoding | `options` | No | — | Character encoding for the message. Using unicode limits the maximum number of characters to 70 instead of 160. |
| | | | | Options: `auto`, `plain`, `unicode` |
| — Gateway | `number` | No | — | The SMS route/gateway ID used to send the message. |
| — Group IDs | `string` | No | — | Group IDs separated by commas. If provided, recipients can be omitted. Supports expressions. |
| — Message Type | `options` | No | `1` | The message class. 0 = normal message, 1 = flash message (displayed immediately on the phone screen). |
| | | | | Options: `0` (Normal), `1` (Flash) |
| — Reference | `string` | No | — | A client reference string for tracking purposes. Supports expressions. |
| — Report URL | `string` | No | — | A URL to receive delivery status report webhooks. The "reference" field must also be set for reports to be sent. Supports expressions. |
| — Scheduled Date-Time | `string` | No | — | The scheduled date and time to send the message in RFC3339 format (Y-m-dTH:i:sP). Supports expressions. |
| — Type | `options` | No | — | The type of message. Values can be: sms, binary, or flash. |
| | | | | Options: `sms`, `binary`, `flash` |
| — Type Details | `string` | No | — | A hash with extra information. Only used when a binary message is sent. Supports expressions. |
| — Validity | `number` | No | `1` | The number of seconds that the message is valid. After this period, delivery will no longer be attempted. |

#### All Operations

| Parameter | Type | Required | Default | Description |
|-----------|------|----------|---------|-------------|
| Max Concurrency | `number` | No | `10` | Maximum number of items to process concurrently. |

## Output Data

One output item per input item — neither operation fans out, and a single send addressed to several recipients still produces one item. The MessageBird API response is merged into the item JSON at the top level, so the fields the item already carried pass through unchanged and binary data is forwarded.

| Operation | Merged onto the item |
|-----------|----------------------|
| SMS: Send | The created message object exactly as MessageBird returns it |
| Balance: Get | The account balance object exactly as MessageBird returns it |

Because the response is merged at the top level rather than nested under a property of its own, reference its fields directly with `{{ $json.… }}`. Run the node once and inspect the output to see the exact field names MessageBird returned.

## Usage Examples

- Send an SMS notification to a customer when their order ships
- Send a scheduled SMS reminder about an upcoming appointment
- Check the current MessageBird account balance before sending bulk SMS
- Send bulk SMS messages to a list of phone numbers from a spreadsheet
- Send a flash message that displays immediately on the recipient phone

## Example Configuration

Send an SMS to two recipients:

```json
{
  "type": "messagebird",
  "parameters": {
    "resource": "sms",
    "operation": "send",
    "originator": "MyCompany",
    "recipients": "14155238886,14155238887",
    "message": "Hello from MessageBird!"
  }
}
```

Send an SMS with additional fields — scheduled, with a delivery report:

```json
{
  "type": "messagebird",
  "parameters": {
    "resource": "sms",
    "operation": "send",
    "originator": "14155238888",
    "recipients": "14155238886",
    "message": "Scheduled message with delivery report",
    "additionalFields": {
      "reference": "order-12345",
      "reportUrl": "https://myapp.com/webhook/sms-status",
      "scheduledDatetime": "2024-01-15T10:30:00Z",
      "datacoding": "auto",
      "mclass": 1,
      "validity": 1440
    }
  }
}
```

Get the account balance:

```json
{
  "type": "messagebird",
  "parameters": {
    "resource": "balance",
    "operation": "get"
  }
}
```

Advanced SMS configuration — unicode body over a specific gateway:

```json
{
  "type": "messagebird",
  "parameters": {
    "resource": "sms",
    "operation": "send",
    "originator": "+1234567890",
    "recipients": "+14155238886,+14155238887,+14155238888",
    "message": "Important notification with custom settings",
    "maxConcurrency": 5,
    "additionalFields": {
      "reference": "campaign-winter-2024",
      "reportUrl": "https://analytics.mycompany.com/sms-delivery",
      "type": "sms",
      "datacoding": "unicode",
      "gateway": 10,
      "validity": 2880
    }
  }
}
```

Marketing campaign:

```json
{
  "type": "messagebird",
  "parameters": {
    "resource": "sms",
    "operation": "send",
    "originator": "SALES",
    "recipients": "14155238886,14155238887,14155238888",
    "message": "Flash Sale! 50% off everything. Use code FLASH50. Valid until midnight!",
    "additionalFields": {
      "reference": "flash-sale-nov-2024",
      "type": "sms",
      "datacoding": "auto"
    }
  }
}
```

Transaction notification driven by the incoming item:

```json
{
  "type": "messagebird",
  "parameters": {
    "resource": "sms",
    "operation": "send",
    "originator": "BANK",
    "recipients": "{{ $json.phone }}",
    "message": "Your account has been debited {{ $json.amount }}. Ref: {{ $json.txnId }}",
    "additionalFields": {
      "reference": "txn-notification-{{ $json.txnId }}",
      "mclass": 1,
      "validity": 60
    }
  }
}
```

Scheduled reminder:

```json
{
  "type": "messagebird",
  "parameters": {
    "resource": "sms",
    "operation": "send",
    "originator": "CLINIC",
    "recipients": "14155238886",
    "message": "Reminder: You have an appointment tomorrow at 2:00 PM. Reply CONFIRM to confirm.",
    "additionalFields": {
      "scheduledDatetime": "2024-01-14T09:00:00Z",
      "reference": "appointment-reminder-789",
      "reportUrl": "https://clinic.com/sms-status"
    }
  }
}
```

Balance check with concurrency pinned to one:

```json
{
  "type": "messagebird",
  "parameters": {
    "resource": "balance",
    "operation": "get",
    "maxConcurrency": 1
  }
}
```

### Error Handling

| Mode | Behavior |
|------|----------|
| **stop** | Halts workflow on first error |
| **continue** | Skips failed items, passes successful ones through |
| **errorPort** | Routes failed items to Error output port |

## Tips

MessageBird sends SMS messages to one or more recipients and retrieves account balance via the MessageBird REST API. Use it for notifications, alerts, and communication workflows.

### Key Notes

- **Message Type defaults to flash (`1`).** A flash message pops up on the recipient's screen instead of landing in their inbox — set it to `0` if you want an ordinary SMS.
- **Validity defaults to 1 second** once you add the field to Additional Fields, which effectively cancels undelivered messages immediately. Give it a realistic window (for example `1440` for a day) or leave the field out entirely.
- **Delivery reports need both fields.** Report URL only produces callbacks when Reference is set as well.
- **Group IDs can replace recipients.** With Group IDs filled in, the To field may be left empty.