Setting up Bitrix24 integration with Miro

Setting up Bitrix24 Integration with Miro

The team runs brainstorms and retrospectives in Miro, but manages tasks in Bitrix24. After each session, someone needs to manually transfer stickers from the board to B24 tasks. Usually the most responsible person does it — or nobody does. After two days, brainstorm results are lost among dozens of boards, and B24 has zero new tasks. The bridge between visual planning and task tracking needs to be automatic.

Integration Architecture

The integration uses Miro REST API v2 and B24 REST API. Miro provides API for working with boards, stickers, frames, and connectors. B24 provides webhooks for task and CRM events. Middleware handles data exchange between systems.

Miro (webhook) → Middleware → B24 REST API → Tasks/Comments
B24 (event) → Webhook → Middleware → Miro REST API → Stickers/Cards

Miro supports webhooks — subscribing to board events via POST /v2/boards/{board_id}/webhooks. The middleware receives notifications when elements are created, modified, or deleted.

Embedding Miro Boards in B24

Miro boards are embedded in Bitrix24 in two ways:

• Iframe in task. An embed link of the format https://miro.com/app/live-embed/{board_id}/ is added to the task description or a custom field. Users see an interactive board right in the task card.
• App in B24 marketplace. A local app (type — placement) embeds a Miro widget in a task or deal card via REST placement TASK_VIEW_TAB. Users open the "Board" tab and see the linked Miro board.

For authorization in an embedded board, Miro uses the user's own session. Middleware passes access_token via OAuth 2.0 flow on first login.

Creating Tasks from Stickers

The key scenario is converting Miro stickers into B24 tasks. The middleware tracks stickers with a specific marker (color, tag, or text prefix):

Technical implementation:

1. Miro webhook sends item_created or item_updated event.
2. Middleware receives sticker data via GET /v2/boards/{board_id}/items/{item_id}.
3. Sticker text is parsed: first line — task name, rest — description.
4. Task is created via tasks.task.add linked to the project (determined by the frame containing the sticker).
5. The created task ID is written back to the sticker as a tag — for bidirectional linking.

Status Synchronization

When a sticker moves between frames on the board (for example, from "To Do" to "In Progress"), the middleware updates the task status in B24. Frames are mapped to statuses:

• Middleware requests the sticker position via API and determines which frame it is in.
• The frame name is matched with the task status via configuration.
• tasks.task.update is called with the new status.

Reverse direction: when a task's status changes in B24, the middleware moves the sticker to the corresponding frame via PATCH /v2/boards/{board_id}/items/{item_id} with new coordinates.

Project Collaboration

For project work, set up automatic creation of a Miro board when a project is created in B24:

1. Event ONSOCNETGROUPADD (project/group creation) → middleware calls POST /v2/boards with a board template.
2. The board link is saved in B24 project description.
3. Project participants get board access via POST /v2/boards/{board_id}/members — email from B24 profiles.

Authentication

• Miro: OAuth 2.0. App is registered on https://miro.com/app/settings/user-profile/apps/. Scope: boards:read, boards:write, identity:read.
• B24: OAuth 2.0 with scope task,sonet_group,user.
• Tokens are stored encrypted on middleware. Refresh happens automatically.

What We Implement

• Middleware for bidirectional Miro board and B24 task integration
• Automatic task creation from Miro stickers with color-based marking
• Embedding Miro boards in Bitrix24 interface
• Status synchronization via frame-to-stage mapping
• Automatic board creation when projects launch
• Member access management between systems