Send Your First WhatsApp Message
Get started with WhatsApp Business messaging via Telnyx in minutes. This guide covers account setup, template creation, and sending your first message with delivery confirmation.Prerequisites
Before sending WhatsApp messages, ensure you have:- Telnyx Account — Sign up and verify your account
- Meta Business Manager Account — Required for WhatsApp Business Platform access
- WhatsApp Business Account (WABA) — Connected via Telnyx’s Embedded Signup
- Verified phone number — Added to your WABA and verified with Meta
WhatsApp Business Platform requires business verification through Meta’s process. Personal WhatsApp accounts cannot send template messages via the API.
Set up your Telnyx account
- Create a Telnyx account and verify your email
- Navigate to the Portal and complete account verification
- Add billing information to enable message sending
- Generate an API key from Developer Center → API Keys → Create API Key
Connect WhatsApp Business Account
Complete the WhatsApp Embedded Signup to connect your Meta Business Manager:
- Navigate to Messaging → WhatsApp in the Telnyx Portal
- Click Connect WhatsApp Business Account
- Sign in with your Facebook Business Manager credentials
- Select the Business Manager account to connect
- Follow Meta’s prompts to create or select a WhatsApp Business Account
- Verify your business phone number when prompted
If you’re registering a landline number, choose phone call verification instead of SMS when prompted. SMS delivery to landline numbers can be unreliable — call verification is more consistent.
Create your first message template
WhatsApp requires pre-approved templates for outbound marketing and notifications:
- In the Telnyx Portal, navigate to Messaging → WhatsApp → Send Messages
- Click Create Template
- Configure your template:
- Name:
welcome_message(lowercase, underscores only) - Category: Marketing
- Language: English (US)
- Body:
Hello {{1}}! Welcome to our WhatsApp updates. - Example Values: Provide sample data for the
{{1}}parameter
- Name:
- Click Submit for Review
Send your first WhatsApp message
Once your template is approved, send your first message:
The messaging profile is automatically resolved from your WhatsApp-enabled phone number specified in the
from field.Set up webhook notifications
Configure webhooks to receive real-time delivery status updates:
- In the Telnyx Portal, navigate to Messaging → Messaging Profiles
- Select your messaging profile
- Set Webhook URL to your endpoint (e.g.,
https://yourapp.com/webhooks/telnyx) - Enable Failover URL for redundancy (optional)
- Save the configuration
Verify Message Delivery
Check message delivery through multiple channels:Portal Dashboard
- Navigate to Messaging → Message Logs in the Telnyx Portal
- Filter by Channel: WhatsApp and Date Range
- View delivery status, timestamps, and any error codes
- Click individual messages for detailed delivery information
Webhook Events
Monitor these key webhook events:message.sent— Message successfully submitted to WhatsAppmessage.delivered— Message delivered to recipient’s devicemessage.read— Recipient opened and read the messagemessage.failed— Message delivery failed (with error details)
API Response
The initial API response includes:Common Issues
Template not approved
Template not approved
Symptoms: API returns a
41000 error (WhatsApp Error) indicating the template was not found or not approvedSolutions:- Verify template status in Portal under Messaging → WhatsApp → Send Messages
- Ensure template name matches exactly (case-sensitive)
- Wait for Meta’s approval (typically 24-48 hours for first templates)
- Review Meta’s template guidelines for approval requirements
Phone number not verified
Phone number not verified
Symptoms: API returns a
41000 error indicating the sender phone number is not registered with WhatsAppSolutions:- Complete phone number verification in the Telnyx Portal
- Ensure number is added to your WhatsApp Business Account
- Verify the number through Meta’s verification process
- Check that the number hasn’t been used with personal WhatsApp
Outside 24-hour window
Outside 24-hour window
Symptoms: Free-form (session) message fails with a
41000 error. WhatsApp requires a template to initiate conversations outside the 24-hour windowSolutions:- Use approved message templates for outbound messaging
- Only send free-form messages within 24 hours of customer’s last message
- Check conversation window status via webhook events
- Consider switching to template-based messaging for customer re-engagement
Invalid recipient
Invalid recipient
Symptoms: Message status webhook returns
undeliverable with Meta API error details in the responseSolutions:- Verify recipient has WhatsApp installed and active
- Ensure phone number format includes country code (+1…)
- Check that recipient hasn’t blocked your business number
- Confirm recipient’s WhatsApp account is not banned or restricted