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 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:

{
  "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:

{
  "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:

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

Advanced SMS configuration — unicode body over a specific gateway:

{
  "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:

{
  "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:

{
  "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:

{
  "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:

{
  "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.