Bird integration

What it does

Bird and MessageBird are two separate integrations in TaskJuice, and this is the current one. Use Bird for new work; the MessageBird integration stays in the catalog for connections that already exist, and for the two things Bird has no equivalent for: placing an outbound voice call, and reading an account balance. Bird replaced the MessageBird REST API with a unified platform API on a different host, with different credentials and a different webhook system, which is why the two could not be merged without breaking every existing connection.

The Bird integration lets your agency run a client's messaging program from inside a workflow. Connect a client's Bird workspace once and your workflows can send SMS and WhatsApp messages, verify a phone number or email with a one-time code, look up a number before sending to it, manage the numbers the workspace owns, read voice call records, and keep contacts, audiences, custom properties and consent in step with the rest of your stack. Delivery outcomes arrive back as triggers.

Connect a Bird account

1. Open Connections

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

2. Create an API 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). The Bird API Key field asks for this, and describes it the same way the form does: Your Bird API key, created in the Bird dashboard under Developers then API keys. It begins with bk_ followed by its region. Give it Write on webhooks — that is what lets TaskJuice register your triggers for you — plus Write on the surfaces your workflows touch: sms and sms_management for SMS, whatsapp, verify, lookup, numbers, preferences, and email_marketing, which is where Bird keeps contacts and audiences even though it sits under Email. Workspace only needs Read, and Read is the most Bird allows there. Scopes can be changed on an existing key at any time and apply immediately, so adding a workflow later does not mean issuing a new key.

3. Read the region off the key itself

   The Bird Region field asks for this, and describes it the same way the form does: The region your Bird workspace lives in. Read it off your API key: a key beginning bk_us1_ is us1, a key beginning bk_eu1_ is eu1. Enter the bare region, lowercase. Read it off the key rather than recalling it — the region decides which Bird host every request goes to.

4. Paste the key and save

   Paste the key into the Bird API Key field and save. TaskJuice sends it as Authorization: Bearer {key} on every request.

Triggers

You do not register these yourself. Publishing a workflow with a Bird trigger registers one workspace-wide endpoint at Bird, carrying the union of every event your workflows use. Adding a second trigger widens that one registration rather than creating another.

Turning a workflow off or deleting it stops deliveries reaching it but leaves the registration in place at Bird, dormant, and cleaned up automatically later. Removing the Bird connection is what deletes the endpoint at Bird.

Bird signs every delivery to the Standard Webhooks specification and TaskJuice verifies the signature before the trigger runs. The signing secret is captured automatically when the endpoint is registered — there is nothing to paste. Bird signs with both the old and the new secret for 24 hours after a rotation, and both are accepted.

Actions

SMS

• bird/send-sms — Send an SMS to one phone number, as free text or from a stored template.
• bird/list-sms-messages — List SMS messages in the workspace, newest first, with filters for direction, status, recipient, sender and time window.
• bird/get-sms-message — Read one SMS message by id, including its current status, segment breakdown and final cost.
• bird/list-sms-message-events — Read the status history of one SMS message, one entry per state change.
• bird/list-sms-keyword-rules — List the automatic keyword rules that answer inbound SMS, such as STOP and HELP replies.
• bird/create-sms-keyword-rule — Create a keyword rule that acts on inbound SMS matching a word you choose.
• bird/get-sms-keyword-rule — Read one SMS keyword rule by id.
• bird/update-sms-keyword-rule — Change an existing SMS keyword rule.
• bird/delete-sms-keyword-rule — Delete an SMS keyword rule.
• bird/list-sms-suppressions — List the phone numbers Bird will not send SMS to, with the reason each was suppressed.
• bird/create-sms-suppression — Stop sending SMS to a phone number by adding it to the suppression list.
• bird/get-sms-suppression — Read one SMS suppression entry by id.
• bird/delete-sms-suppression — Remove a phone number from the SMS suppression list so Bird can send to it again.
• bird/list-sms-templates — List the stored SMS templates a send can use, with the parameters each one takes.
• bird/get-sms-template — Read one stored SMS template by reference.
• bird/get-sms-stats-summary — Read SMS volume, delivery and failure rates, and latency over a time window, so a scheduled workflow can act on a threshold.

WhatsApp

• bird/send-whatsapp-message — Send a WhatsApp message to one recipient, as a template or as free text inside an open service window.
• bird/list-whatsapp-messages — List WhatsApp messages in the workspace, newest first, with filters for direction, status, recipient and time window.
• bird/get-whatsapp-message — Read one WhatsApp message by id, including its current status and final cost.
• bird/list-whatsapp-message-events — Read the status history of one WhatsApp message, one entry per state change.

Verify

• bird/create-verification — Start a verification: Bird sends a one-time code to a phone number or email over the channel you choose.
• bird/check-verification — Check a one-time code a recipient entered against an open verification.
• bird/verification-next-channel — Retry an open verification over the next channel in its policy, for example moving from SMS to a voice call.

Lookup

• bird/lookup-phone-number — Look up a phone number to learn its country, line type, carrier and whether it can receive SMS.
• bird/lookup-email — Look up an email address to learn whether it is deliverable, disposable or role-based.

Numbers

• bird/list-workspace-numbers — List the phone numbers this workspace owns, with the channels each one supports.
• bird/get-workspace-number — Read one phone number this workspace owns.
• bird/release-workspace-number — Release a phone number back to Bird.
• bird/list-available-numbers — Search Bird inventory for phone numbers you can buy, by country, type, prefix and capability.
• bird/get-available-number — Read one number from Bird inventory, including its price and capabilities, before ordering it.
• bird/list-numbers-orders — List phone-number orders this workspace has placed, with the status of each.
• bird/create-numbers-order — Order one or more phone numbers from Bird inventory.
• bird/get-numbers-order — Read one phone-number order by id, including which numbers it provisioned.

Voice

• bird/list-voice-calls — List voice call records for the workspace, with filters for direction, status, number and time window.
• bird/get-voice-call — Read one voice call record by id, including its duration, SIP response and cost.

Contacts

• bird/list-contacts — List contacts in the workspace, or find one by email, phone number or your own external id.
• bird/create-contact — Create a contact with its identifiers and custom property values.
• bird/create-contact-batch — Create or update many contacts in one request, matched on the identifier you choose.
• bird/get-contact — Read one contact by id, including its identifiers and property values.
• bird/update-contact — Change a contact identifier or property value.
• bird/delete-contact — Delete a contact.
• bird/list-contact-preferences — Read the consent records on file for one contact, one row per channel, handle and sender scope, so a workflow can check consent before sending.

Audiences

• bird/list-audiences — List the audiences in the workspace.
• bird/create-audience — Create an audience contacts can be assigned to.
• bird/get-audience — Read one audience by id.
• bird/update-audience — Rename an audience or change its description.
• bird/delete-audience — Delete an audience.
• bird/list-audience-contacts — List the contacts assigned to one audience.
• bird/assign-audience-contacts — Add contacts to an audience.
• bird/unassign-audience-contacts — Remove several contacts from an audience in one request.
• bird/unassign-audience-contact — Remove one contact from an audience.

Contact properties

• bird/list-contact-properties — List the custom contact properties defined in this workspace.
• bird/create-contact-property — Define a new custom contact property.
• bird/get-contact-property — Read one custom contact property by id.
• bird/update-contact-property — Set the fallback value on a custom contact property; the key and type cannot be changed after creation.
• bird/archive-contact-property — Archive a custom contact property so its key stops being accepted in contact writes. Values already stored are preserved.
• bird/unarchive-contact-property — Bring an archived custom contact property back into use.

Preferences (consent)

• bird/list-preferences — List consent records in the workspace, filtered by channel or by the handle they apply to.
• bird/create-preference — Record consent: grant or revoke a handle on a channel, optionally narrowed to one sender scope instead of the whole channel.
• bird/get-preference — Read one consent record by id.
• bird/delete-preference — Delete a consent record. A statement the person made themselves, such as an unsubscribe or a STOP keyword, cannot be deleted.

Workspace

• bird/get-workspace — Read the Bird workspace this connection belongs to, including its name, organization and notification email addresses.

Sending is asynchronous — correlate on the outcome event

bird/send-sms and bird/send-whatsapp-message return the message immediately with status accepted. That is Bird accepting it, not the handset receiving it: the delivery outcome arrives later, as a trigger. cost is null on that first response for the same reason — the message is not priced yet.

The pattern is two workflows. The first sends and records the returned id:

bird/send-sms  →  $steps.send_sms.data.id

The second is triggered by the outcome and matches on it:

Trigger: bird/sms-delivered
Filter:  {{$trigger.data.sms_id}} equals the id you stored

bird/sms-failed, bird/sms-undelivered, bird/sms-expired and bird/sms-rejected carry the failure detail in data.error, so one workflow can branch on why a send did not arrive.

Sending exactly once

Every action that changes something at Bird takes an optional Idempotency Key. Reuse the same key and Bird replays the original response instead of acting twice, for three hours. Bird recommends <event-type>/<entity-id>, which in a workflow is usually an expression over the trigger:

order-confirmation/{{$trigger.data.order_id}}

Leave it empty and every run sends independently.

Known limitations

No outbound voice calls. Bird's platform API has no place-a-call endpoint. Its entire voice surface is read-only call records: calls are placed over SIP by your own telephony stack, and this integration observes the result. If you need TaskJuice to place the call, stay on the MessageBird integration, whose send-voice-message action still works — or send an SMS or WhatsApp message instead, which is the right answer for most alerting.

No account balance. Bird's platform API exposes no balance field anywhere, so the "alert me when my balance drops below X" workflow cannot be rebuilt here. Use MessageBird's get-balance for that. bird/get-sms-stats-summary reports volume, delivery and failure rates and latency over a window — useful for a scheduled health check, but it is not a spend figure and not a balance.

No batch send. Bird's batch endpoint takes a bare JSON array of complete send requests, a shape TaskJuice's HTTP action engine cannot express. Send inside a Loop node instead.

Not covered by this integration: Bird Email (use Resend, SendGrid, Postmark or Mailgun), the analytics breakdown endpoints (volume and delivery rates come back from bird/get-sms-stats-summary; the per-carrier, per-country and per-hour slices do not), and Realtime websocket channels. None of them is missing by accident — each is a different product, and this page says so rather than leaving you looking.