The BSUID Integration Checklist for Developers

Migrating to Business Scoped User IDs requires a few specific codebase changes. Use this checklist to ensure a smooth transition. If you haven't read the BSUID Engineering Deep Dive yet, start there for the conceptual foundation.

The BSUID migration affects three core areas of any WhatsApp Business API integration. First, database schemas must be updated to store user_id as a VARCHAR(64) column alongside existing phone number fields, with a unique constraint per WABA ID and a composite index for fast lookups during outbound messaging. Second, webhook ingestion parsers must be updated to check for contacts[0].user_id as the primary identifier, with a graceful fallback to wa_id during the Q3 2026 dual-mode transition period.

Third, outbound message API calls to graph.facebook.com/v19.0/{PHONE_NUMBER_ID}/messages must use the BSUID string in the to field instead of a raw phone number. According to Meta's Cloud API documentation, failing to update webhook parsers before Q4 2026 will result in 400 Bad Request errors when username-initiated conversations return no wa_id field. The BSUID Audit Tool can validate existing payload compatibility before production deployment.

1. What Database Schema Updates Are Needed?

• [ ] Ensure your Users or Customers table allows the phone number column to be nullable.
• [ ] Add a new string column: whatsapp_bsuid. Recommended SQL:

  ALTER TABLE users ADD COLUMN whatsapp_bsuid VARCHAR(64) NULL;
  ALTER TABLE users ADD CONSTRAINT uq_bsuid_per_waba UNIQUE (waba_id, whatsapp_bsuid);
  

• [ ] Add a unique constraint to whatsapp_bsuid per WABA ID. This prevents duplicate entries if the same user messages your business through different entry points.
• [ ] Index the column for fast lookups during outbound messaging:

  CREATE INDEX idx_users_bsuid ON users (waba_id, whatsapp_bsuid);
  

According to Meta's Cloud API webhook schema, the user_id field is a string of up to 64 characters, so VARCHAR(64) is the appropriate column type.

2. How Do I Update Webhook Ingestion?

• [ ] Update your Express/Next.js payload parsers to check for contacts[0].user_id.
• [ ] Fallback gracefully if user_id is missing by checking for wa_id (legacy).
• [ ] Test this logic by pasting your webhook payload into our BSUID Audit Tool.
• [ ] Log both wa_id and user_id during the transition period (Q3 2026) to ensure no data loss.

Sample Webhook Parser (Node.js)

app.post('/webhook/whatsapp', (req, res) => {
  const entry = req.body.entry?.[0];
  const change = entry?.changes?.[0]?.value;
  const contact = change?.contacts?.[0];
  
  // BSUID-aware parsing
  const userId = contact?.user_id || contact?.wa_id;
  const profileName = contact?.profile?.name;
  
  // Store both during transition
  await db.users.upsert({
    where: { bsuid: userId },
    update: { lastSeen: new Date() },
    create: { 
      bsuid: userId,
      waId: contact?.wa_id, // temporary, for backward compatibility
      profileName 
    }
  });
});

3. How Do I Update the Outbound Message API?

• [ ] Update your POST requests to https://graph.facebook.com/v19.0/{PHONE_NUMBER_ID}/messages.
• [ ] Instead of "to": "123456789", send "to": "bsuid_987654321".
• [ ] Test with a known BSUID from your webhook logs before full rollout.

Sample Outbound Payload

{
  "messaging_product": "whatsapp",
  "to": "bsuid_987654321",
  "type": "template",
  "template": { "name": "order_confirmation", "language": { "code": "en" } }
}

4. How Should I Handle BSUID Errors?

• [ ] Handle 400 Bad Request errors gracefully—log the full response body for debugging.
• [ ] Implement retry logic with exponential backoff for transient failures.

What Are Common BSUID Troubleshooting Issues?

| Error | Likely Cause | Solution | |-------|-------------|----------| | 400 Invalid Parameter | BSUID belongs to different WABA | Verify the WABA ID matches your configured phone number ID | | 400 Not Found | BSUID expired or user deleted account | Gracefully fall back to requesting the user's phone number | | wa_id still returned | User hasn't migrated to username-based chat | Accept both fields until Q4 2026 deprecation |

If you receive a 400 Bad Request with an Invalid Parameter error on outbound messages, ensure you are not passing a BSUID that belongs to a different WABA ID. BSUIDs are strictly isolated per business account per Meta's WhatsApp Business API architecture.

5. How Do I Verify a Successful Migration?

• [ ] Run a full webhook payload through the BSUID Audit Tool after migration.
• [ ] Verify outbound messages deliver to the correct recipients.
• [ ] Monitor error logs for 24 hours post-deployment.
• [ ] Check the Migration Timeline for upcoming deprecation deadlines.

Return to the BSUID Hub for more resources, or visit the FAQ for common developer questions.