.png)
Bird Integration Guide
Connect Bird’s SMS, WhatsApp, email, and other communication channels with enterprise applications through REST APIs, selected webhook events, and Martini workflows.
Bird integration options at a glance
Bird primarily integrates with enterprise systems through REST APIs for Contacts, Conversations, Messages, Channels, and related resources. Bird also supports webhook-style notifications for selected events, including inbound messages, status changes, conversation updates, and supported resource changes. Channel-specific payloads can include text, templates, media, recipients, senders, and metadata. Martini can consume these APIs, receive Bird callbacks through REST endpoints and workflows, map channel-specific data, and orchestrate downstream updates. API access keys authenticate server-to-server requests, while secrets and webhook verification requirements should be managed securely. High-volume processing can use controlled iteration, scheduling, queues, retries, and rate-limit backoff.
| Integration point | Supported by Bird? | Common use cases | How Martini supports it |
|---|---|---|---|
| REST APIs | Yes | Bird’s primary programmatic mechanism for creating and updating Contacts, retrieving Conversations, sending Messages, reading delivery status, and querying Channels and related configuration. | Martini can consume Bird REST endpoints from workflows, map request and response data, orchestrate calls with other applications, and expose normalized REST APIs for internal consumers. |
| Webhooks and outbound callbacks | Limited | Bird supports notifications for selected events such as inbound Messages, status changes, Conversation updates, and supported resource changes. Coverage is not universal. | Martini can expose a REST endpoint or use a webhook-consuming workflow to receive callbacks, validate them, apply business rules, and route events downstream. |
| File and attachment APIs | Limited | Media and attachments are available for selected channels and message types, subject to channel-specific restrictions and endpoint behavior. | Martini can map attachment metadata, transfer content through supported HTTP operations, and route or archive files when the Bird endpoint supports the required operation. |
| Bulk, asynchronous, and batch APIs | Not confirmed | A universal bulk API for all Bird resources was not confirmed. Resource- or channel-specific operations must be verified before implementation. | Martini can implement controlled iteration, scheduling, queues, throttling, retries, and backoff around applicable REST endpoints without assuming a universal bulk API. |
| Authentication | Yes | Bird documents server-to-server API access keys using the documented Authorization header format, with permissions determined by the key and workspace configuration. | Martini stores the access key in environment secrets and applies it to outbound REST requests; webhook security requirements should be implemented for the relevant Bird product and version. |
| Database and analytics access | Not confirmed | No direct Bird customer-database or JDBC access was confirmed. Operational data should be extracted through APIs and event notifications. | Martini can copy API and webhook data into a customer-managed database or analytics store using workflows and database capabilities. |
How Bird exposes data and business events
Bird REST APIs
Bird’s REST API is the primary integration mechanism for Contacts, Conversations, Messages, Channels, delivery status, and related resources. Endpoint paths, versions, pagination, schemas, and permissions vary by API area.
Martini implementation pattern
Martini implementation pattern: a workflow or API receives an enterprise request, calls the applicable Bird REST endpoint with an access key from environment secrets, transforms the response, and writes results to downstream systems. Reusable Martini APIs can normalize Bird-specific models for internal applications.
Implementation sequence
Bird Webhooks
Bird supports webhook-style notifications for selected resources and events, including inbound Messages, status changes, Conversation updates, and other supported changes. Event coverage and payload behavior must be checked for the relevant Bird product and workspace.
Martini implementation pattern
Martini implementation pattern: expose a REST endpoint or webhook-consuming workflow, validate the request according to Bird’s current webhook security requirements, deduplicate the event, map the payload, and route it to a CRM, service desk, database, or response workflow.
Implementation sequence
Bird Channel Messaging
Bird Message payloads depend on the enabled channel. Text, templates, media, recipients, senders, and metadata may differ across SMS, WhatsApp, email, and other channels.
Martini implementation pattern
Martini implementation pattern: select the channel from business rules and customer preferences, validate channel-specific content and sender requirements, construct the Bird Message request, and process the resulting identifier and delivery status.
Implementation sequence
Scheduled Bird Synchronization
Scheduled retrieval is useful for reconciliation and for resources where webhook coverage is unavailable or incomplete. Contacts, Conversations, Messages, and status information may require pagination and version-specific API behavior.
Martini implementation pattern
Martini implementation pattern: a scheduler starts a workflow that retrieves changed or paginated resources, maps them into a customer-managed store or application, and compares results with previously recorded identifiers to repair missed events.
Implementation sequence
Common Bird integration patterns
Pattern 1: Send CRM-triggered customer messages
When to use this pattern
Use this pattern when a customer interaction, preference change, or service process in a CRM should trigger an outbound Bird Message. It supports channel selection, consent validation, correlation, and later delivery processing.
Integration direction
Example Mapping
| Bird Field | Canonical Field | Target Field |
|---|---|---|
| Contact.id | customer.externalId | Bird Contact.id |
| Contact.phone or email | customer.destination | Message.recipient |
| communicationPreference | messaging.channel | Message.channel |
| case or interaction reference | correlation.reference | Message.metadata |
Martini implementation pattern
Martini receives a CRM event or scheduled change, normalizes the Contact, checks opt-in and channel rules, resolves the Bird Channel and sender, and sends a channel-specific Message. It stores the Bird Message identifier and retries only transient failures, while later status events update the CRM.
Martini capabilities used
- workflows
- API consumption
- data mapping
- business rules
- secrets management
- error handling
Pattern 2: Route inbound Bird messages to a service desk
When to use this pattern
Use this pattern when inbound customer communications should create or update support work in Zendesk or ServiceNow and optionally receive an agent response through Bird.
Integration direction
Example Mapping
| Bird Field | Canonical Field | Target Field |
|---|---|---|
| Contact.id | customer.externalId | Case.customerReference |
| Conversation.id | conversation.externalId | Case.externalConversationId |
| Message.text or media | interaction.content | Case.description or attachment |
| Message.id | interaction.externalId | Case.correlationId |
Martini implementation pattern
Martini receives a selected Bird webhook, validates its authenticity, deduplicates it, matches the Contact or Conversation, and creates or updates a service case. Routing rules select the queue; agent responses can be transformed into Bird Messages. Failed downstream writes are retried or placed into an operational exception path.
Martini capabilities used
- API exposure
- webhook consumption
- data mapping
- conditional routing
- business rules
- error handling
Pattern 3: Send order and delivery notifications
When to use this pattern
Use this pattern for order confirmations, fulfillment updates, appointment reminders, and similar transactional communications initiated by commerce or ERP events.
Integration direction
Example Mapping
| Bird Field | Canonical Field | Target Field |
|---|---|---|
| order.id | transaction.externalId | Message.metadata.orderId |
| customer.contact | notification.recipient | Message.recipient |
| fulfillment.status | notification.event | Template.variable.status |
| shipping.estimatedDate | notification.value | Template.variable.estimatedDate |
Martini implementation pattern
Martini consumes an order or fulfillment event, checks consent and notification preferences, selects an enabled Bird channel and Template, validates variables, and sends the Message. The workflow records the result and correlates delivery or failure events back to the order system without replacing final statuses with older events.
Martini capabilities used
- workflows
- API consumption
- data transformation
- business rules
- retry handling
- event correlation
Pattern 4: Reconcile centralized communication history
When to use this pattern
Use this pattern when Contacts, Conversations, Messages, and delivery status must be retained in a CRM, customer data store, or analytics platform, including recovery from missed webhook events.
Integration direction
Example Mapping
| Bird Field | Canonical Field | Target Field |
|---|---|---|
| Conversation.id | conversation.externalId | communication_history.conversation_id |
| Message.id | message.externalId | communication_history.message_id |
| Message.status | message.deliveryStatus | communication_history.status |
| Message.createdAt | message.occurredAt | communication_history.occurred_at |
Martini implementation pattern
Martini combines near-real-time Bird webhook processing with scheduled REST reconciliation. It follows pagination, upserts by stable identifiers, preserves status precedence, and records checkpoints and failures so delayed or missed events can be repaired.
Martini capabilities used
- scheduled workflows
- API consumption
- webhook consumption
- pagination control
- data mapping
- database integration
- monitoring
Applications commonly integrated with Bird
Bird can be integrated with customer, commerce, service, and operational applications when organizations need to coordinate communications with business processes. These are architectural integration patterns rather than claims of Bird-native packaged connectors; implementation depends on the relevant application APIs, Bird workspace configuration, and enabled channels.
| Application | Scenario | Direction | Martini Pattern |
|---|---|---|---|
| Salesforce | Synchronize Contacts and communication history, trigger customer notifications, and create service follow-up records from inbound conversations. | Salesforce → Martini → Bird | Martini receives Salesforce events or scheduled changes, maps customer preferences and contact identifiers to Bird Contacts, sends channel-appropriate Messages, and processes Bird delivery or inbound events back into Salesforce. |
| HubSpot | Trigger transactional or customer communications and associate Bird message activity with contact engagement data. | HubSpot → Martini → Bird | A Martini workflow consumes HubSpot changes, validates consent and channel data, calls Bird REST endpoints, and reconciles message status or supported inbound events into HubSpot. |
| Zendesk | Convert inbound Bird messages into support tickets or append communication activity to existing customer cases. | Bird → Martini → Zendesk | Martini receives selected Bird webhook events, matches the Contact or Conversation to a Zendesk user or ticket, routes the message, and sends agent responses through Bird when required. |
| ServiceNow | Create or update customer-service cases and send status notifications through Bird. | ServiceNow → Martini → Bird | Martini consumes ServiceNow events or schedules, applies notification rules, sends Bird Messages, stores identifiers, and routes inbound or delivery events back to ServiceNow. |
| Shopify | Send order confirmations, fulfillment updates, delivery notifications, and customer-service communications. | Shopify → Martini → Bird | Martini receives order or fulfillment events, checks customer preferences, selects a Bird channel and template, sends the Message, and records the result for reconciliation. |
| Microsoft Dynamics 365 | Coordinate customer communication activity with transactional and service notifications. | Microsoft Dynamics 365 → Martini → Bird | Martini maps Dynamics customer and activity data to Bird resources, invokes the REST API, and processes selected Bird events back into Dynamics with duplicate protection. |
| NetSuite | Send order, invoice, fulfillment, or account notifications to customers. | NetSuite → Martini → Bird | A Martini workflow consumes NetSuite business events or scheduled records, applies channel and consent rules, sends Bird Messages, and persists message identifiers and outcomes. |
| Slack | Notify internal teams about delivery failures, inbound escalations, and integration exceptions. | Bird → Martini → Slack | Martini receives Bird status or inbound events, evaluates escalation rules, formats a concise operational message, and posts it to the appropriate Slack channel. |
How to build a Bird integration in Martini
Objective
Establish Bird access using the workspace and API permissions required for the selected resources and channels.
Instructions in Martini
- Confirm the Bird API version, workspace, resources, and enabled channels
- Create or obtain an appropriately restricted Bird API access key
- Store the key in Martini environment secrets
- Configure the Bird Authorization header and webhook security requirements
Objective
Select an event-driven, API-led, or scheduled entry point based on Bird event coverage and the required freshness of the integration.
Instructions in Martini
- Use a Martini REST endpoint or webhook-consuming workflow for supported Bird events
- Use an application event or API request for outbound messaging
- Use a scheduler for reconciliation and resources without suitable webhook coverage
Objective
Collect the relevant Bird Contact, Conversation, Message, Channel, Template, or status data while accounting for incomplete notifications and pagination.
Instructions in Martini
- Validate inbound webhook structure and authenticity
- Retrieve the current resource when a notification contains only a summary
- Follow pagination cursors or page tokens for list operations
- Record stable Bird identifiers and correlation values
Objective
Coordinate Bird calls with CRM, service desk, commerce, ERP, database, or notification systems in a maintainable Martini workflow.
Instructions in Martini
- Separate channel selection, Bird API calls, downstream writes, and reconciliation logic
- Use reusable workflow services or APIs for shared communication behavior
- Route success, validation, permission, rate-limit, and transient failures separately
Objective
Convert Bird’s channel-specific payloads into canonical enterprise models and construct valid outbound Message requests.
Instructions in Martini
- Normalize phone numbers, email addresses, external IDs, and preferences
- Map Contact, Conversation, Message, Channel, and Template fields explicitly
- Branch for SMS, WhatsApp, email, and media-specific requirements
- Preserve Bird identifiers for correlation and idempotency
Objective
Enforce consent, suppression, sender, regional, template, routing, and status-precedence rules before writing or sending data.
Instructions in Martini
- Check opt-in, opt-out, and communication preferences
- Select only an enabled and permitted Bird channel and sender
- Validate required template variables and content limits
- Prevent an older event from overwriting a newer final status
Common Bird data objects used in integrations
| Object | Typical Use | Common target systems | Martini handling |
|---|---|---|---|
| Workspace | The Bird environment containing channels, users, Contacts, Conversations, and configuration. | Configuration stores, integration databases, administration systems | Martini uses workspace context and permissions when configuring API calls and routing data; it does not assume direct database access. |
| Contact | A person or addressable customer profile used in communication workflows. | Salesforce, HubSpot, Microsoft Dynamics 365, Shopify, customer databases | Martini normalizes phone numbers, email addresses, external IDs, consent, and preferences before creating, updating, or matching Contacts. |
| Conversation | A customer interaction that can contain Messages across supported channels. | Zendesk, ServiceNow, Salesforce, CRM databases, analytics stores | Martini retrieves or receives Conversation data, correlates it with customer and case identifiers, and preserves event ordering and status precedence. |
| Message | An inbound or outbound SMS, WhatsApp message, email, or other channel communication. | CRM activity objects, service tickets, order systems, communication archives | Martini applies channel-specific mappings, sends or receives content, stores Bird identifiers, and handles delivery results and retries. |
| Channel | A configured communication channel or channel type used to send and receive Messages. | Configuration services, routing workflows, notification applications | Martini resolves the appropriate channel and sender, validates channel-specific requirements, and avoids treating SMS, WhatsApp, and email payloads as identical. |
| Template | A reusable message template, including templates required or pre-approved for some channels. | Commerce systems, ERP systems, notification workflows, CRM applications | Martini supplies the relevant template reference and variables, validates required fields, and branches where channel rules differ. |
Authentication and security considerations
API authentication
Bird documents API access-key authentication using the Authorization header format applicable to the relevant API version. Workspace, resource, and channel permissions should follow least-privilege principles.
Secrets and webhooks
Store Bird access keys and webhook signing secrets in Martini environment secrets. Validate webhook authenticity, request structure, freshness, and required identifiers according to the current Bird documentation.
Communication compliance
Preserve consent, opt-out, suppression, and communication-preference data. Channel, carrier, regional, WhatsApp, email, and retention requirements may apply independently of Martini and Bird.
Operational considerations for Bird integrations
Throughput and pagination
Account for Bird API limits, channel provider limits, sender throughput, workspace quotas, and regional restrictions. Use controlled execution, queues where appropriate, retries with backoff, and pagination checkpoints.
Idempotency and ordering
Webhook retries and uncertain outbound results can create duplicates. Persist Bird event, Message, Conversation, or external transaction identifiers. Compare timestamps or status precedence so an older event cannot replace a newer final status.
Channel-specific schemas
SMS, WhatsApp, email, and other channels can differ in recipient formats, sender requirements, templates, media, content limits, and delivery states. Use explicit validation and mapping branches.
Versioning and reconciliation
Confirm the current Bird API version and resource model before implementation. Version mappings, tolerate additive fields, monitor rejected requests, and schedule reconciliation to repair missed or delayed events.
Why use Martini instead of scripts or point-to-point integrations?
Reusable orchestration
Martini separates Bird API consumption, webhook intake, channel validation, business rules, downstream writes, and reconciliation into maintainable workflows and reusable APIs.
Controlled transformation
Mappings can normalize Contacts, Conversations, Messages, Templates, identifiers, preferences, and channel-specific content without forcing every consuming application to understand Bird’s resource model.
Reliable operations
Martini provides workflow-based error handling, retries, scheduling, logging, and monitoring patterns for rate limits, transient failures, duplicate events, pagination, and reconciliation.
API-led integration
Instead of maintaining separate point-to-point scripts, teams can expose a controlled internal API façade over Bird, coordinate multiple enterprise systems, and keep credentials and environment configuration outside workflow definitions.
Frequently asked questions
Bird integrates primarily through REST APIs for Contacts, Conversations, Messages, Channels, delivery status, and related resources. It also supports webhook-style notifications for selected inbound messages, status changes, conversation updates, and other supported events. API access keys authenticate server-to-server requests, while channel-specific message schemas and workspace permissions must be considered.
Yes. Martini can consume Bird REST APIs, receive selected Bird webhook events, expose internal APIs that normalize Bird operations, and orchestrate Bird messaging with CRM, service desk, commerce, ERP, database, and other enterprise systems.
No dedicated Bird connector is required. Martini can integrate with Bird using its confirmed native REST APIs, selected webhook notifications, API access-key authentication, and supported channel or attachment endpoints.
Lonti does not charge an additional per-connector or per-vendor fee to integrate Bird with Martini. The integration is subject to the provisioned capacity of the Martini environment. Separate costs may apply from Bird, cloud infrastructure, carriers, messaging providers, or other third parties based on subscriptions, usage, and deployment model.
Use Bird REST APIs as the primary method for resource operations and outbound messaging. Use webhook notifications for supported inbound and status events, and scheduled REST synchronization for reconciliation or resources without suitable event coverage. A universal Bird GraphQL or SOAP API was not confirmed.
Bird supports webhook-style notifications for selected events, including examples such as inbound Messages, status changes, and Conversation updates. Coverage, signing, payloads, retries, and subscriptions must be verified for the relevant Bird API product, version, workspace, and event type.
Martini can combine Bird webhook events with scheduled or on-demand REST retrieval. Workflows map Contacts, Conversations, Messages, Channels, and statuses into target models, follow pagination, preserve stable identifiers, apply channel and consent rules, and use upserts or reconciliation checkpoints to reduce duplicates and repair missed events.
Martini can separate authentication, permission, validation, rate-limit, channel rejection, and transient failures. Transient calls can use controlled retries and backoff, while webhook workflows can persist event or Message identifiers for idempotency. Status precedence and reconciliation workflows help manage out-of-order or repeated events.
Related Martini documentation
API Integration
Workflows
Connect Bird to your enterprise workflows
Use Martini to integrate Bird REST APIs and selected webhook events with the applications, data stores, and business processes that manage customer communications.