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 posts an inbound SMS or a delivery-status update to the configured webhook URL.

Connect a MessageBird account

1. Open your workspace in TaskJuice and navigate to Connections.
2. Choose MessageBird and click Connect.
3. 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).
4. 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.
5. Copy the key value, paste it into TaskJuice, and save the connection.

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 (sent, delivered, buffered, expired, delivery_failed). The activation payload carries the message id, recipient, status, reason, error code, and price.

Each trigger publishes an inbound URL. Paste it into MessageBird under Developers, Webhooks (or attach it to the number under Numbers, Edit, Default flow), and set a custom header named X-TaskJuice-Inbound-Secret to a shared secret you also paste into the TaskJuice trigger. MessageBird sends that exact value on every POST and TaskJuice verifies it before activating.

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 offset and limit, with optional filters on originator, recipient, status, type, and date range.
• 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 offset and limit.
• 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 honors the recommended backoff.
• 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 a long-lived shared secret on a custom header (X-TaskJuice-Inbound-Secret). MessageBird's native MessageBird-Signature and MessageBird-Signature-JWT signing schemes are not used by this integration; rotate the shared secret alongside the API key.
• Alphanumeric originators are not supported in every country (notably the United States and Canada). MessageBird returns a 422 from send-sms when the recipient's country forbids the chosen originator; the action surfaces it as a validation error.
• Voice messaging requires a number on your MessageBird account that is provisioned for outbound voice. Numbers provisioned only for SMS will be rejected as a validation error.
• MessageBird is in the middle of a migration from rest.messagebird.com to the newer api.bird.com surface. This integration targets the stable legacy host for broader compatibility; the newer Conversations and Channels APIs will land in a follow-up bundle.