Skip to main content

​
WhatsApp Embedded Signup

WhatsApp Embedded Signup enables businesses to connect their Facebook Business Manager account to Telnyx and provision WhatsApp Business Account (WABA) resources through a streamlined browser-based workflow.

​
Prerequisites

Before starting the embedded signup process:
1

Telnyx Account Setup

Required account status:
  • Active Telnyx account with messaging enabled
  • Valid payment method configured
  • Account in good standing with no billing issues
Portal access:
  • Log in to Telnyx Portal
  • Navigate to Messaging → WhatsApp
  • Ensure you have admin permissions for your organization
2

Facebook Business Manager

Business Manager requirements:
  • Facebook Business Manager account (business.facebook.com)
  • Admin access to the Business Manager account
  • Business verification completed (recommended for production use)
Important limitations:
  • Each phone number can only be associated with one Business Manager
  • Business Manager must have appropriate permissions for WhatsApp Business API
  • Account must comply with Facebook Business policies
Ensure your Facebook Business Manager is fully set up and verified before starting embedded signup. Incomplete Business Manager setup can cause signup failures that require manual intervention.

​
Signup Flow Overview

The embedded signup process follows a multi-step finite state machine (FSM) that progresses through these states: Each state represents a checkpoint in the signup process with specific completion criteria and potential failure points.

​
Step-by-Step Signup Process

1

Initiate Embedded Signup

From Telnyx Portal:
  1. Navigate to Messaging → WhatsApp → Getting Started
  2. Click Connect Facebook Business Manager
  3. Review the permissions and requirements displayed
  4. Click Begin Setup to start the embedded signup flow
What happens:
  • Telnyx creates a signup session with state initiated
  • Portal generates a secure OAuth URL for Facebook authorization
  • Session tracking begins for completion monitoring
Verification:
# Check signup session status via API
curl -X GET "https://api.telnyx.com/v2/whatsapp/signup/{signup_id}/status" \
  -H "Authorization: Bearer YOUR_API_KEY"

# Response
{
  "data": {
    "id": "signup_123abc",
    "state": "initiated",
    "created_at": "2024-01-15T10:30:00Z"
  }
}
2

Facebook OAuth Authorization

Facebook authorization flow:
  1. Browser redirects to Facebook Business Manager OAuth consent screen
  2. Review the requested permissions:
    • WhatsApp Business Management — Create and manage WABA
    • Business Asset Management — Associate phone numbers and templates
    • Webhook Management — Configure message and status webhooks
  3. Click Continue to grant permissions
  4. Select target Business Manager if you have multiple
What happens:
  • Facebook validates your Business Manager admin status
  • OAuth token is generated and securely transmitted to Telnyx
  • Signup state advances to facebook_auth
Common issues:
  • Permission denied: Ensure you have admin access to Business Manager
  • Business not verified: Some features require verified Business Manager
  • Already connected: Phone number may be connected to another provider
Verification: The Portal will show “Connected to Facebook” with Business Manager details when successful.
3

WhatsApp Business Account Creation

WABA provisioning:Telnyx automatically creates your WhatsApp Business Account using the connected Business Manager:
  1. WABA is created under your Business Manager
  2. Telnyx is granted the necessary permissions as a solution partner
  3. Initial configuration is applied (timezone, business category)
  4. Webhook endpoints are pre-configured for Telnyx integration
What happens:
  • Facebook creates the WABA resource
  • Telnyx receives WABA credentials and configuration details
  • Signup state advances to waba_created
  • WABA settings are synced to Telnyx systems
WABA configuration:
  • Business hours: Set to 24/7 by default
  • Business category: Inherited from Business Manager
  • Webhooks: Configured for Telnyx endpoint (https://whatsapp.telnyx.com/webhooks)
Verification:
# List WABAs for your account
curl -X GET "https://api.telnyx.com/v2/whatsapp/business_accounts" \
  -H "Authorization: Bearer YOUR_API_KEY"

# Response
{
  "data": [
    {
      "id": "waba_456def",
      "name": "Your Business Name",
      "status": "active",
      "business_manager_id": "123456789"
    }
  ]
}
4

Phone Number Registration

Number selection and registration:
  1. Portal displays available phone numbers from your Telnyx inventory
  2. Select the phone number to register for WhatsApp
  3. Choose the WABA to associate with the number
  4. Confirm the registration request
Phone number requirements:
  • Must be owned by your Telnyx account
  • Cannot be currently registered with another WhatsApp provider
  • Should be a dedicated number (not shared with voice/SMS)
What happens:
  • Phone number is submitted to Facebook for WhatsApp registration
  • Facebook begins the verification process
  • Signup state advances to phone_registered
  • Number status changes to “pending verification”
Registration details:
  • Number format: E.164 format (+1234567890)
  • Verification method: Automatically determined by Facebook
  • Processing time: Usually 1-5 minutes for verification
Verification:
# Check phone number registration status
curl -X GET "https://api.telnyx.com/v2/whatsapp/phone_numbers" \
  -H "Authorization: Bearer YOUR_API_KEY"

# Response
{
  "data": [
    {
      "phone_number": "+15551234567",
      "business_account_id": "waba_456def",
      "status": "pending_verification",
      "registered_at": "2024-01-15T11:15:00Z"
    }
  ]
}
5

Phone Number Verification

Facebook verification process:Facebook automatically verifies phone numbers using multiple methods:
  1. Carrier validation: Facebook verifies number ownership with telecom provider
  2. SMS verification: Test SMS may be sent to validate delivery capability
  3. API validation: Facebook tests webhook delivery and response handling
Verification timeline:
  • Typical duration: 1-15 minutes
  • Complex cases: Up to 24 hours for carrier validation
  • Failed attempts: May require manual review or different number
What happens:
  • Facebook completes all verification checks
  • Number status updates to “verified” in Facebook systems
  • Signup state advances to verified
  • Number becomes available for sending messages
Verification methods Facebook may use:
Automated voice call to verify number is operational and accessible.Duration: 30 seconds
Requirements: Number must accept incoming calls
Verification completion:
# Final verification status
curl -X GET "https://api.telnyx.com/v2/whatsapp/phone_numbers/+15551234567" \
  -H "Authorization: Bearer YOUR_API_KEY"

# Response
{
  "data": {
    "phone_number": "+15551234567",
    "business_account_id": "waba_456def", 
    "status": "verified",
    "verified_at": "2024-01-15T11:20:00Z",
    "messaging_enabled": true
  }
}

​
Signup Completion

When verification succeeds, your WhatsApp integration is ready:

​
Account Status

  • WABA Status: Active and ready for messaging
  • Phone Number: Verified and enabled for sending/receiving
  • Webhooks: Configured and receiving events
  • Templates: Ready for submission and approval

​
Next Steps After Signup

Send Messages

Send templates, text, media, and interactive messages

Quickstart

Send your first WhatsApp message end-to-end

Receiving Webhooks

Handle inbound messages and delivery status callbacks

​
Troubleshooting Common Issues

Error: “You don’t have permission to complete this action”Causes:
  • Not admin of Business Manager account
  • Business Manager doesn’t have WhatsApp permissions
  • Account suspended or restricted
Solutions:
  1. Verify admin access in Business Manager
  2. Contact Facebook Business Support if account restricted
  3. Use different Business Manager account
  4. Check account verification status
Error: “Unable to create WhatsApp Business Account”Causes:
  • Business Manager doesn’t meet Facebook requirements
  • Too many existing WABAs on Business Manager
  • Business policy violations
Solutions:
  1. Complete Business Manager verification
  2. Review and resolve any policy violations
  3. Remove unused WABAs from Business Manager
  4. Contact Telnyx support with signup session ID
Error: “This phone number is already connected to WhatsApp Business API”Causes:
  • Number registered with another Business Service Provider
  • Number previously registered but not properly disconnected
  • Number registered to different WABA
Solutions:
  1. Disconnect number from previous provider
  2. Contact previous provider to release number
  3. Use different phone number for registration
  4. Contact Facebook Business Support for assistance
Error: “Phone number verification failed” or timeoutCauses:
  • Number doesn’t support voice calls or SMS
  • Carrier blocking verification attempts
  • Number routing issues
Solutions:
  1. Verify number accepts incoming calls and SMS
  2. Try different phone number if possible
  3. Contact carrier to check for blocks
  4. Wait and retry verification process
  5. Contact Telnyx support with verification details
Error: Webhooks not receiving events after successful signupCauses:
  • Webhook URL not properly configured
  • Firewall blocking webhook delivery
  • Invalid webhook signature verification
Solutions:
  1. Verify webhook URL accessibility from Facebook servers
  2. Check webhook signature verification implementation
  3. Review webhook configuration in Portal
  4. Test webhook endpoint with manual POST requests
  5. Check logs for delivery attempts and errors

​
API Integration

​
Signup Session Monitoring

Monitor signup progress programmatically using the Signup API: 
curl -X GET "https://api.telnyx.com/v2/whatsapp/signup/{signup_id}/status" \
  -H "Authorization: Bearer YOUR_API_KEY"

​
Webhook Events

Receive real-time signup progress updates: 
{
  "data": {
    "event_type": "whatsapp.signup.state_updated",
    "payload": {
      "signup_id": "signup_123abc",
      "state": "verified",
      "previous_state": "phone_registered",
      "waba_id": "waba_456def",
      "phone_number": "+15551234567",
      "occurred_at": "2024-01-15T11:20:00Z"
    }
  }
}

​
Security Considerations

​
Data Protection

  • OAuth tokens: Securely stored and encrypted by Telnyx
  • Business Manager access: Limited to necessary permissions only
  • Webhook security: All webhooks use Ed25519 signature verification

​
Best Practices

  • Use dedicated Business Manager for production WhatsApp integration
  • Review and audit Business Manager permissions regularly
  • Monitor webhook logs for unauthorized access attempts
  • Implement proper error handling for signup failures

​
Compliance

  • GDPR compliance for EU businesses using WhatsApp
  • Data residency requirements for certain industries
  • Facebook Business Policy compliance required
  • Regular compliance monitoring and reporting

​
Migration from Manual Setup

If migrating from manual WhatsApp Business API setup:

​
Preparation Steps

  1. Document existing WABA configuration
  2. Export message templates and business profile data
  3. Plan downtime window for migration
  4. Backup webhook configurations

​
Migration Process

  1. Complete embedded signup for new WABA
  2. Migrate templates to new WABA
  3. Update webhook endpoints to Telnyx
  4. Test messaging functionality thoroughly
  5. Disable old WABA after successful verification

​
Post-Migration Validation

  • Verify all message templates are approved
  • Test inbound and outbound messaging
  • Confirm webhook delivery and processing
  • Monitor message delivery rates and errors