Skip to content

[IA Migration] Phase 4: Channels#12385

Open
bre-fitzgerald wants to merge 108 commits intodevelopfrom
phase4-channels
Open

[IA Migration] Phase 4: Channels#12385
bre-fitzgerald wants to merge 108 commits intodevelopfrom
phase4-channels

Conversation

@bre-fitzgerald
Copy link
Contributor

@bre-fitzgerald bre-fitzgerald commented Feb 28, 2026

Summary

Phase 4 of the User Guide IA migration: moves all content from message_building_by_channel/ into the new channels/ top-level section, and dissolves the messaging/content/ section.

~440 files changed — 160 channel renames, 55 content-section renames, 8 new landing page stubs, 1 deletion, ~140 internal link fixes, ~540 new redirect lines, ~380 existing redirect chain targets collapsed.

Nine channel sections created under channels/

Channel Files Key changes
Banners 5 createcreate_a_banner, analyticsreporting
Content Cards 9 createcreate_a_content_card, page_order updates
Webhooks 6 creating_a_webhookcreate_a_webhook, use case renames
LINE 10 line_users/message_users/, landing page rewrite
In-app messages 26 in-app_messagesin_app_messages (hyphen to underscore), new message_types/ section, customize/ split, DnD + traditional trees preserved
Push 30 New push_setup/, new platform_specific_resources/, creating_a_push_messagecreate_a_push_message
Email 43 New customize/ section, apple_mail/best_practices/, reporting_and_analyticsreporting, FAQ merge (duplicate emails), nav reorder
SMS/MMS/RCS 38 sms_mms_rcssms_mms_and_rcs, new message_setup/, new message_features_and_optimization/
WhatsApp 32 overview/whatsapp_setup/, new phone numbers section, new features section

Additional work

  • Transactional email extracted to own top-level section under channels/
  • Email nav reorder — updated page_order for all 11 email child pages
  • In-app messages nav reorder — new Message types landing page, Creative details converted to redirect, 2 files moved (create page under DnD, iOS rating prompt under Best practices)
  • Email FAQ merge — folded duplicate_emails.md into faq.md
  • Email reporting directory fix — moved reporting_and_analytics/reporting/ to match landing page filename

Sections fully removed

  • message_building_by_channel/ — all 160+ files migrated, directory empty
  • messaging/content/ — dissolved, all 54 files redistributed

Depends on

Made with Cursor

bre-fitzgerald and others added 30 commits February 23, 2026 15:29
Restructures the Administer and Data sections of the user guide as part of the
ongoing IA migration. Key changes include:

- Reorganize Data > Activation: distribute custom_data/ content into
  attributes/ and events/ subsections, update landing pages, add data_types
  article, reorder pages
- Reorganize Data > Distribution: move Currents articles under use_cases/ and
  setting_up_currents/, clean up Export Braze Data nav titles, merge/delete
  duplicate export articles
- Move custom events report to Analytics > Reports
- Update Data landing page with integrated overview content
- Add redirects for all moved/deleted pages
- Update 300+ internal cross-references across the docs

Co-authored-by: Cursor <cursoragent@cursor.com>
Remove site-wide internal link updates from this PR. These will be
handled separately as a final QA pass after all IA restructuring is
complete.

Co-authored-by: Cursor <cursoragent@cursor.com>
Co-authored-by: copilot-swe-agent[bot] <198982749+Copilot@users.noreply.github.com>
Co-authored-by: bre-fitzgerald <82903296+bre-fitzgerald@users.noreply.github.com>
… settings > Managing tags" in the PR. Propose suggestions to improve the quality, clarity, and comprehensiveness of the article. (#12259)

Co-authored-by: copilot-swe-agent[bot] <198982749+Copilot@users.noreply.github.com>
Co-authored-by: bre-fitzgerald <82903296+bre-fitzgerald@users.noreply.github.com>
…les (#12260)

Co-authored-by: copilot-swe-agent[bot] <198982749+Copilot@users.noreply.github.com>
Co-authored-by: bre-fitzgerald <82903296+bre-fitzgerald@users.noreply.github.com>
Co-authored-by: copilot-swe-agent[bot] <198982749+Copilot@users.noreply.github.com>
Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Co-authored-by: bre-fitzgerald <82903296+bre-fitzgerald@users.noreply.github.com>
… nav alert

- Rename manage_braze_users.md to manage_company_users.md
- Remove alert about older navigation (no longer available)
- Update internal links and redirects

Co-authored-by: Cursor <cursoragent@cursor.com>
- Switch Data landing page from dev_guide to standard article layout for auto-TOC
- Add cross-link to Export Braze Data under "Distribute your data"
- Rewrite Attributes description with cross-links to user profiles, SDK,
  API, segmentation, and personalization docs
- Rewrite Events description with bulleted event types, cross-links to
  SDK logging and Custom events report, and corrected examples
- Update meta descriptions to match new content

Co-authored-by: Cursor <cursoragent@cursor.com>
Co-authored-by: Cursor <cursoragent@cursor.com>
- Rewrite Data Activation guide_top_text2 with a cohesive paragraph covering
  attributes, events, recommended events, catalogs, and tags
- Rewrite Events guide_top_text in paragraph form (replacing bulleted list)
- Update SDK link to point to SDK data collection page

Co-authored-by: Cursor <cursoragent@cursor.com>
Co-authored-by: copilot-swe-agent[bot] <198982749+Copilot@users.noreply.github.com>
Co-authored-by: bre-fitzgerald <82903296+bre-fitzgerald@users.noreply.github.com>
Audience (new top-level section):
- Create audience.md, manage_users.md, subscription_preferences.md landing stubs
- Move segments/ from engagement_tools/ to audience/ (15 files + subtree)
- Extract suppression_lists, user_profiles to audience/ root
- Move duplicate_users to audience/manage_users/merge_duplicate_users
- Move import_users + csv child from data/unification/ to audience/manage_users/
- Move delete_users from data/unification/ to audience/manage_users/
- Move preference_center + 2 children from email/ to audience/subscription_preferences/
- Move locations_and_geofences + 2 children from engagement_tools/ to audience/
- Move global_control_group_reporting from analytics/reporting/ to audience/
- Move viewing_and_understanding_segment_data to data/distribution/export_braze_data/segment_data

Analytics (internal reshuffle):
- Rename dashboard/ to dashboards/, rename 4 files (home, api_usage, channel_performance, conversions)
- Move dashboard_builder from reporting/ into dashboards/
- Rename reporting/ to reports/, rename configuring_reporting
- Move query_builder + 3 children into reports/
- Move global_control_group from engagement_tools/testing/ to reports/
- Rename email_tracking to open_pixel_and_click_tracking
- Rename influenced_opens to influence_opens

Redirects: 59 new entries + 81 existing destinations updated to prevent chains.
Frontmatter: Updated nav_title and article_title on all renamed files.
Site-wide cross-reference updates deferred to Phase 3 QA pass.

Co-authored-by: Cursor <cursoragent@cursor.com>
- Fix /user_guide/introduction/ build error (update 5 stale references)
- Reorder top-level User Guide nav sections
- Audience: remove manage_users stub, move children under user_profiles,
  reorder all Audience children
- Audience > Segments: reorder, move segment_data back from Data section
- Audience > Subscription preferences: add channel and API cross-link tiles
- Analytics: reorder to Dashboards > Reports > Tracking > Metrics glossary
- Analytics: move report_metrics up to analytics/metrics_glossary
- Analytics > Dashboards: reorder, nest eCommerce revenue under Dashboard Builder
- Analytics > Reports: alphabetize (Configure reporting first),
  clean up all stale landing page tiles and body cross-references
- Update redirects for all moved files, collapse redirect chains

Co-authored-by: Cursor <cursoragent@cursor.com>
…data

Co-authored-by: Cursor <cursoragent@cursor.com>

# Conflicts:
#	_docs/_user_guide/data/activation/attributes/data_types.md
…alytics

Co-authored-by: Cursor <cursoragent@cursor.com>

# Conflicts:
#	_docs/_user_guide/data/activation/attributes/data_types.md
Creates the messaging/ section by moving content from engagement_tools/
and other source directories.

Messaging fundamentals (17 files):
- Move from engagement_tools/messaging_fundamentals/ with renames
- Pull in frequency_capping from campaigns/building_campaigns/rate-limiting
- Pull in rate_limiting from canvas/create_a_canvas/rate_limiting

Canvas (58 files):
- Move entire subtree as-is from engagement_tools/canvas/
- Extract feature_flags.md from canvas_components/ to messaging/ root

Campaigns (33 files):
- Move subtree with restructuring: flatten campaign_basics from
  getting_started/, rename delivery_types→schedule_your_campaign,
  managing_campaigns→manage_campaigns, testing_and_more→test_campaigns
- Delete orphaned building_campaigns.md and getting_started.md landing pages
- Children move with their renamed parents

Landing pages (7 files):
- Move from engagement_tools/landing_pages/ with 4 file renames

Feature flags (5 files):
- New landing from canvas_components/feature_flags.md
- Children from engagement_tools/feature_flags/ with renames
- Delete old engagement_tools/feature_flags.md landing

A/B testing (7 files):
- New section from engagement_tools/testing/ items
- random_bucket_numbers, conversion_correlation, race_conditions → concepts/
- multivariant_testing children → ab_testing root

Reusable content (2 files):
- content_blocks from email/drag_and_drop/dnd_content_blocks
- product_blocks from data/activation/catalogs/product_blocks

Design and edit (1 file):
- image_specs from templates_and_media/

New landing stubs: messaging.md, ab_testing.md, concepts.md,
reusable_content.md, design_and_edit.md

Redirects: 134 new entries + 66 existing destinations updated.
Frontmatter: Updated nav_title and article_title on all renamed files.
Site-wide cross-reference updates deferred to Phase 3 QA pass.

Deferred to Jira (6 items):
- Priority sorter (new article)
- Campaigns landing page rewrite
- Drag-and-drop editor (new article)
- Email drag-and-drop editor (new article)
- Email HTML editor (new article)
- Traditional composers (new article)

Co-authored-by: Cursor <cursoragent@cursor.com>
Integrate remaining engagement_tools/ content into messaging/ and
delete the now-empty section entirely.

A/B testing:
- Integrate multivariant_testing.md conceptual content (when to use,
  tips, variant distribution) into messaging/ab_testing.md landing page
- Move ab_test_projection.md to messaging/ab_testing/
- Delete testing.md and multivariant_testing.md landing pages

Media library:
- Promote to messaging/ root from templates_and_media/

Templates (renamed from "Templates and media"):
- Move templates_and_media.md → messaging/templates.md
- Move content_blocks → templates/content_block_library.md
- Move canvas_templates, managing_templates, faqs to templates/
- Update canvas_templates redirect target to messaging/canvas/ path
- Rewrite templates.md landing page tiles for new paths

Engagement tools:
- Delete engagement_tools.md landing page
- Section is now fully empty and removed

Redirects: 10 new entries + 62 existing destinations updated to
prevent chains. Only news_feed legacy redirects remain pointing
to engagement_tools/ (deprecated section, not part of migration).

Co-authored-by: Cursor <cursoragent@cursor.com>
- Move webhook templates to Messaging > Content > Templates
- Move Media Library from Content to Design and edit
- Nest Image specifications and FAQ under Media Library
- QA: Fix stale landing page tile links (messaging_fundamentals, feature_flags, connected_content)
- QA: Resolve 11 redirect chains (engagement_tools, personalization_and_dynamic_content)
- QA: Fix ~50 stale internal links across 20+ files
- QA: Remove empty canvas_templates directory
- Merge Content Block library into canonical Content Blocks article
- Fold Personalization & Dynamic Content into Messaging > Content > Personalize
- Create Content parent section with templates, personalize, content blocks, product blocks
- Update all corresponding redirects in broken_redirect_list.js

Co-authored-by: Cursor <cursoragent@cursor.com>
Media library & Design and edit:
- Remove duplicative image specs from media_library.md, link to dedicated article
- Add Content Cards, Video, push/IAM notes to image_specifications.md
- Replace tabs with H3 headings under "Channel guidance"
- Add Image specifications tile to Design and edit landing page

A/B testing:
- Fix broken Intelligent Selection link in guide_top_text
- Rename "Tips" to "Tips for running effective tests"
- Move Variant distribution to dedicated concept article with proper H2 structure
- Add Variant distribution tile to Concepts landing page
- Replace FAQ include with concise answer linking to canonical article

Co-authored-by: Cursor <cursoragent@cursor.com>
…data

Made-with: Cursor

# Conflicts:
#	_docs/_user_guide/administer/global/user_management/internal_groups.md
#	_docs/_user_guide/administer/global/user_management/permissions.md
#	_docs/_user_guide/analytics/dashboard/deliverability_center.md
#	_docs/_user_guide/data/activation/custom_data/managing_custom_data.md
Made-with: Cursor

# Conflicts:
#	_docs/_user_guide/message_building_by_channel/email/drag_and_drop/dnd_content_blocks.md
Copilot AI and others added 27 commits March 3, 2026 16:52
Co-authored-by: copilot-swe-agent[bot] <198982749+Copilot@users.noreply.github.com>
Co-authored-by: rachel-feinberg <135255868+rachel-feinberg@users.noreply.github.com>
Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>
Co-authored-by: Lydia Xie <87040416+lydia-xie@users.noreply.github.com>
Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>
Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>
Address common support questions about:
- Product-level data visibility in dashboard
- Segmenting by specific product using Segment Extensions
- Differences between legacy purchase events and eCommerce events
- Custom properties limitations in eCommerce events
- Identity handling (SDK vs API) for event logging
- Nested property limitations with AI Recommendations
- Troubleshooting missing eCommerce events

Cases: 500VP00000pxtRKYAY, 500VP00000qPrBFYA0, 500VP00000njKGAYA2,
500VP00000qJUu7YAG, 500VP00000q8WeIYAU, 500VP00000oFkHAYA0,
500VP00000fwDi5YAE, 500VP00000qFeLoYAK, 500VP00000pfDwqYAE,
500VP00000q7oLZYAY
…ts/ecommerce_events.md

Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>
…ts/ecommerce_events.md

Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>
…ts/ecommerce_events.md

Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>
Adds a new REST API section to the developer guide with a reference
article that walks through creating an API campaign and using the
/messages/send endpoint to send WhatsApp template messages.

Made-with: Cursor
Recipients must already exist in Braze for /messages/send, and only
TEXT/IMAGE headers are supported for WhatsApp templates via this endpoint.

Made-with: Cursor
The json fence tag was misleading when it also contained the HTTP
method line and headers. Split into an untagged block for the request
line/headers and a json-tagged block for the payload.

Made-with: Cursor
The example hard-coded rest.iad-01.braze.com, which is only correct
for one cluster. Use a placeholder and link to the endpoint discovery
docs instead.

Made-with: Cursor
Replace the WhatsApp-specific article with a general "Sending messages
using the REST API" guide that covers all supported channels. Links to
existing endpoint references instead of duplicating request body docs.

Made-with: Cursor
…ssages/send, clarify two endpoints

Made-with: Cursor
Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>
Co-authored-by: github-actions[bot] <github-actions[bot]@users.noreply.github.com>
Co-authored-by: Lydia Xie <87040416+lydia-xie@users.noreply.github.com>
Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>
Co-authored-by: Cursor <cursoragent@cursor.com>
Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>
Co-authored-by: github-actions[bot] <github-actions[bot]@users.noreply.github.com>
Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>
Replaces all 55 instances of {% include %} with {% multi_lang_include %}
across 38 files in _docs/ to ensure translated include files are resolved
correctly for non-English locales.

Made-with: Cursor
…es (#12235)

Co-authored-by: Cursor <cursoragent@cursor.com>
Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>
…times (#12267)

Co-authored-by: copilot-swe-agent[bot] <198982749+Copilot@users.noreply.github.com>
Co-authored-by: rachel-feinberg <135255868+rachel-feinberg@users.noreply.github.com>
Co-authored-by: Rachel Feinberg <rachel.feinberg@braze.com>
Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>
…#12311)

Co-authored-by: copilot-swe-agent[bot] <198982749+Copilot@users.noreply.github.com>
Co-authored-by: atom-evens <234223650+atom-evens@users.noreply.github.com>
Resolve 5 conflicts:
- teams.md: keep updated administer/ link path (ours) with Legacy permissions tab (develop)
- media_library.md: keep link to dedicated image_specifications page + GIF warning
- post_duplicate_campaigns.md: drop rebase-artifact EA alert, match develop
- managing_custom_data.md: delete old path (moved to data/activation/), multi_lang_include fix applied
- dnd_content_blocks.md: delete old path (moved to messaging/design_and_edit/content_blocks.md)

Made-with: Cursor
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Projects

None yet

Development

Successfully merging this pull request may close these issues.