Complete Guide to External API Integration

Introduction to the Coext External API

The Coext External API is a powerful RESTful interface that enables you to programmatically send WhatsApp messages through your connected WhatsApp Business Account. Whether you’re building automated notifications, customer support systems, or marketing campaigns, this API provides the tools you need.

This guide will walk you through everything from initial setup to advanced use cases, ensuring you can fully leverage the API’s capabilities.

What Makes This API Different

Unlike complex OAuth flows or multi-step authentication procedures, the Coext External API uses simple API key authentication. This means:

• Quick Setup: Get started in minutes, not hours
• Simple Headers: Just add your API key to each request
• No Token Refresh: Your API key works until you revoke it
• Optional Enhanced Security: Add HMAC signatures when you need extra protection

Capabilities Overview

Step 1: Creating Your API Key

Your API key is the credential that identifies and authenticates your requests. Here’s how to create one:

Navigate to External API Management

1. Log into your Coext dashboard
2. From the side menu, select External API Management
3. Click on the API Keys tab
4. Click the Create API Key button

Configure Your Key

When creating your key, you’ll need to provide:

Save Your Credentials Immediately

⚠️ Critical: After creating your API key, you’ll see both the API Key and API Secret. The secret is only shown once and cannot be retrieved later. Copy both credentials and store them securely!

Your credentials will look like:

API Key:    pk_live_a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6
API Secret: sk_live_x9y8z7w6v5u4t3s2r1q0p9o8n7m6l5k4
            

Step 2: Understanding the Base URL

All API requests are made to the following base URL:

https://your-domain.com/api/v1/external
            

Replace your-domain.com with your actual Coext instance domain.

Available Endpoints

Step 3: Making Your First API Call

Let’s send your first message! We’ll start with a simple text message.

Required Headers

Every request must include these headers:

Content-Type: application/json
X-API-Key: pk_live_your_api_key_here
            

cURL Example

curl -X POST "https://your-domain.com/api/v1/external/messages/text" 
  -H "Content-Type: application/json" 
  -H "X-API-Key: pk_live_your_api_key_here" 
  -d '{
    "to": "+919876543210",
    "message": "Hello! This is a test message from the API.",
    "reference": "test-msg-001"
  }'
            

Understanding the Request Body

Success Response

{
  "success": true,
  "data": {
    "message_id": "550e8400-e29b-41d4-a716-446655440000",
    "status": "sent"
  },
  "meta": {
    "request_id": "req_abc123def456",
    "rate_limit": {
      "limit": 60,
      "remaining": 59,
      "reset_at": "2025-12-19T10:01:00.000Z"
    }
  }
}
            

Error Response Example

{
  "success": false,
  "error": {
    "code": "INVALID_PHONE_NUMBER",
    "message": "Phone number must be in E.164 format"
  },
  "meta": {
    "request_id": "req_xyz789"
  }
}
            

Step 4: Sending Template Messages

Template messages are pre-approved message formats required for business-initiated conversations outside the 24-hour customer service window.

Why Templates Are Important

• Required for First Contact: You cannot send freeform messages to customers who haven’t messaged you in the last 24 hours
• Pre-Approved Content: Templates are reviewed by Meta to ensure compliance with messaging policies
• Consistent Branding: Templates ensure your messages maintain a professional, consistent format

Simplified Template Endpoint

The easiest way to send templates is using the simplified endpoint with named variables:

curl -X POST "https://your-domain.com/api/v1/external/messages/template/send" 
  -H "Content-Type: application/json" 
  -H "X-API-Key: pk_live_your_api_key_here" 
  -d '{
    "to": "+919876543210",
    "template_name": "order_confirmation",
    "language": "en",
    "variables": {
      "customer_name": "John Doe",
      "order_id": "ORD-12345",
      "total_amount": "$99.99",
      "delivery_date": "December 25, 2025"
    },
    "reference": "order-12345"
  }'
            

Raw Template Endpoint

For more control, use the raw template endpoint with component arrays:

curl -X POST "https://your-domain.com/api/v1/external/messages/template" 
  -H "Content-Type: application/json" 
  -H "X-API-Key: pk_live_your_api_key_here" 
  -d '{
    "to": "+919876543210",
    "template_name": "order_confirmation",
    "language": "en",
    "components": [
      {
        "type": "body",
        "parameters": [
          { "type": "text", "text": "John Doe" },
          { "type": "text", "text": "ORD-12345" },
          { "type": "text", "text": "$99.99" }
        ]
      }
    ]
  }'
            

Step 5: Understanding Rate Limits

Rate limits protect the system from abuse and ensure fair usage. Every response includes rate limit information:

Rate Limit Headers in Response

"meta": {
  "rate_limit": {
    "limit": 60,           // Your per-minute limit
    "remaining": 45,       // Requests remaining this minute
    "reset_at": "2025-12-19T10:01:00.000Z"  // When limit resets
  }
}
            

Next Steps

Now that you understand the basics, explore these advanced topics:

• Authentication Deep Dive: Learn about enhanced HMAC signature authentication
• Webhook Integration: Receive real-time notifications for message events
• Error Handling: Understand all error codes and build robust retry logic
• Template Configuration: Set up variable mappings in the dashboard

Best Practices Summary

1. Store credentials securely – Use environment variables, never commit to code
2. Use the Playground first – Test your integration before production
3. Implement retry logic – Handle rate limits with exponential backoff
4. Track with references – Use the reference field to correlate messages
5. Monitor rate limits – Check remaining limits in each response
6. Set up webhooks – Don’t poll for status; use webhooks instead