MessageBird integration

What it does

The MessageBird (Bird) integration lets your agency drive a client's SMS and voice messaging program from inside a workflow. Connect a client's MessageBird API key once and your workflows can send single or bulk SMS, place text-to-speech voice calls, validate phone numbers with the Lookup API, list and inspect prior sends, watch the prepaid balance, and react in real time when MessageBird sends an inbound SMS or a delivery-status update to the configured webhook URL.

Connect a MessageBird account

1. Open Connections

   Open your workspace in TaskJuice, navigate to Connections, choose MessageBird and click Connect.

2. Create an access key in the Bird Dashboard

   In a new tab, sign in to the Bird Dashboard as the client (or as your agency, if the client has delegated key creation to you). Open Developers, then API access (REST). Click Add access key, name it for the workspace, and choose a live (not test) key for production workflows.

3. Copy your signing key too, if you will use triggers

   Still in a MessageBird tab, sign in at dashboard.messagebird.com and open Developers → Settings to copy your signing key. This is the legacy Connectivity Platform console — the newer Bird console at dashboard.bird.com, where you created the access key, does not surface a signing key. The field is optional: sending works without it, but MessageBird signs every webhook it delivers with this key, so the inbound SMS and delivery-report triggers stay silent until it is on file.

4. Paste the keys and save

   Copy the key values, paste them into TaskJuice — the access key into API Key, the signing key into Webhook signing key — and save the connection. Setting the signing key is an account admin action: it verifies deliveries for the whole account, so connect (or reconnect) as an account admin when you supply it.

To rotate or revoke the key, return to the API access page, revoke the existing key, create a new one, and update the TaskJuice connection.

Triggers

• messagebird/incoming-sms fires when an inbound SMS arrives on a MessageBird number you have routed to the workflow. One POST equals one inbound message, and the activation payload carries the message id, originator, recipient, body, and timestamp.
• messagebird/message-status fires when MessageBird reports a delivery-status change for an outbound SMS (scheduled, sent, buffered, delivered, expired, delivery_failed). MessageBird delivers status reports as HTTP GET requests with the report in the query string, and only for messages you sent with both a reference and a report URL — a send with neither produces no report at all, and the trigger stays silent.

MessageBird signs every webhook it sends with a MessageBird-Signature-JWT header — a JSON Web Token signed with HMAC-SHA256 using your account's signing key, whose claims carry a hash of the request URL and body. TaskJuice verifies all of it, so a delivery is refused until the signing key is on file — supply it on the MessageBird connection (the Webhook signing key field in the Connect dialog above).

Set up MessageBird deliveries

Do these in order. Steps 1 and 2 apply to both triggers; step 3 is for inbound SMS and step 4 is for delivery reports.

1. Copy the Event delivery URL

   Open either MessageBird trigger in the workflow builder and copy the Event delivery URL. There is one URL for the whole app, not one per trigger: both messagebird/incoming-sms and messagebird/message-status are delivered to it, and TaskJuice decides which trigger fires from what arrives.

2. Confirm the signing key is on the connection

   If the MessageBird connection was saved without the optional Webhook signing key, add it now: open the connection, paste the signing key from Developers → Settings at dashboard.messagebird.com, and save. Setting it is an account admin action — ask one to do it if that is not you, and the rest of the setup is yours.

3. For inbound SMS: forward the number to the URL

   In Flow Builder, attach the delivery URL to your number's flow with a Forward to URL step and set the method to POST. POST is a recommendation rather than a requirement: a GET-configured number puts the message text in the query string, where a + typed by a sender and a space are indistinguishable once the URL is decoded.

4. For delivery reports: set BOTH reportUrl and reference

   On every messagebird/send-sms you want reports for, set Delivery Report URL to the same Event delivery URL (or set an account-level status report URL in the MessageBird dashboard) and set Reference. The run id is the usual choice, and it comes back on the report.

   A send missing either one produces silence

   MessageBird sends a status report only for a message that carried both. With either one missing it sends nothing at all — no request, no error — so there is no run and no failed delivery to look at. Silence is the symptom, which is why it is the first thing to check.

5. If no report ever arrives

   Check in this order, because the first cause is by far the most common. First, confirm the send carried both reference and reportUrl — open the run and look at the send-sms step's input. If both were set and the trigger's activity view still shows nothing, the remaining causes are a delivery URL that does not match the one on the panel and a signing key that is missing or stale on the connection: re-copy the URL from step 1 and re-save the key from step 2. A refused delivery leaves no run of its own, so an empty activity view is consistent with both "MessageBird never called" and "the delivery was refused" — work through steps 1, 2 and 4 rather than reading the empty view as an answer.

Actions

• messagebird/send-sms sends an SMS to one or many recipients through the REST messaging API with optional reference, validity, datacoding, and delivery-report URL.
• messagebird/get-message retrieves a single SMS by its MessageBird message id, including the per-recipient delivery state.
• messagebird/list-messages pages through SMS messages on the account, with optional filters on originator, recipient, status, type, direction, search term, contact, and date range. Paging is automatic — the action requests every page up to its limit, so there is no offset or page-size input.
• messagebird/send-voice-message places an outbound voice call that reads a body of text using MessageBird's text-to-speech voice messaging, with selectable language, voice, repeat, and answering-machine behavior.
• messagebird/list-voice-messages pages through voice messages on the account, with optional filters on originator, recipient, contact, status, and date range. Paging is automatic, so there is no offset or page-size input.
• messagebird/lookup-phone-number validates a phone number and returns carrier metadata, line type, and formatted variants via the Lookup API.
• messagebird/get-balance retrieves the account's current prepaid credit balance.

Known limitations

• The integration uses MessageBird's REST API at rest.messagebird.com. Per-key rate limits, daily send caps, and feature entitlements are governed by the client's MessageBird plan, not by TaskJuice. When MessageBird returns a 429, the action surfaces as a retryable rate-limit error, and waits the interval MessageBird asks for when the response carries one.
• Outbound auth uses MessageBird's custom Authorization: AccessKey <key> scheme rather than Bearer. The key must remain server-side; treat a leaked key the same way you would treat a leaked Bearer token and revoke it from the dashboard.
• Inbound webhook verification uses MessageBird's own MessageBird-Signature-JWT header. Regenerating the signing key in the MessageBird dashboard requires saving the new value on the TaskJuice connection; until you do, deliveries are refused.
• Inbound SMS arrives form-encoded. Configure the Flow Builder Forward to URL step to use POST: a GET-configured number puts the message text in the query string, where a + typed by a sender and a space are indistinguishable once the URL is decoded.
• Originator rules vary by destination country and by what your MessageBird account is provisioned for. When MessageBird rejects an originator for a recipient, send-sms surfaces the refusal as a validation error naming what MessageBird said — check the originator against MessageBird's own country rules before assuming the workflow is at fault.
• send-voice-message depends on your MessageBird account being provisioned for outbound voice; a refusal there surfaces as a validation error carrying MessageBird's own message rather than a TaskJuice error.
• messagebird/incoming-sms covers virtual mobile numbers (VMNs). Short codes are outside this bundle: a short-code delivery still reaches the URL, but it does not carry every field the trigger declares, so downstream steps can see gaps.
• Delivery reports require a reference and a report URL on the send that produced them. messagebird/message-status cannot fire for a send that carried only one of the two, and MessageBird reports no error for the omission.
• This integration targets MessageBird's Connectivity Platform at rest.messagebird.com. The newer api.bird.com surface — Conversations, Channels — is not covered by this bundle.