Skip to main content

Documentation Index

Fetch the complete documentation index at: https://developers.telnyx.com/llms.txt

Use this file to discover all available pages before exploring further.

​
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 WhatsApp Business
  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:
Signup session monitoring is handled automatically by the portal. API-based signup tracking may not be available in all configurations.
# 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 category: Inherited from Business Manager
  • Webhooks: Configured via your messaging profile webhook settings
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": "APPROVED",
      "waba_id": "2019979452207634"
    }
  ]
}
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 a Telnyx number with an active messaging profile assigned
  • Cannot be currently registered with another WhatsApp provider
  • Can be used alongside SMS/voice on the same number — WhatsApp uses a separate API path
The embedded signup flow currently requires a Telnyx-owned number with a messaging profile. Bring-your-own-number (non-Telnyx numbers) is not yet supported through the portal signup flow. If you need to register an external number, contact support for assistance.
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",
    "enabled": true,
    "calling_enabled": false
  }
}

​
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
Symptom: Embedded signup popup fails to load, shows a blank page, or gets stuck during the Facebook OAuth step.Causes:
  • Ad blockers (uBlock Origin, Adblock Plus, etc.) blocking Facebook/Meta domains
  • Privacy extensions (Privacy Badger, Ghostery) blocking third-party scripts
  • Browser security settings blocking cross-origin popups
Solutions:
  1. Temporarily disable ad blockers and privacy extensions for the signup flow
  2. Add facebook.com and meta.com domains to your extension’s allowlist
  3. Try using a different browser profile without extensions
  4. Use Chrome Incognito mode (extensions are typically disabled by default)
  5. Ensure popup blockers allow popups from the Telnyx Portal domain
Note: The WhatsApp embedded signup flow is powered by Meta/Facebook. The OAuth consent screen and business verification steps are hosted on Facebook’s servers, which means browser extensions that block Facebook domains will prevent the signup from completing.

​
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"
    }
  }
}