Build with WhatsApp API

Integrate WhatsApp messaging into your applications with our RESTful API.

RESTful JSON Webhooks

Getting Started

1 Get your API key

Generate an API key from your portal dashboard: /my/whatsapp/api-keys

2 Set the Authorization header

                                
                                Authorization: Bearer YOUR_API_KEY
                            

3 Make your first request

curl -X POST https://www.procomrades.com/api/v1/wa/send/text \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"phone": "+1234567890", "text": "Hello from the API!"}'

API Scopes

Scope	Description
`messages`	Send and receive WhatsApp messages (text, media, templates)
`conversations`	Read, assign, and resolve conversation threads
`contacts`	Manage WhatsApp contact lists and attributes
`templates`	Create, update, and delete message templates
`campaigns`	Launch and monitor bulk messaging campaigns

API Reference

Messages

POST


                                                            /api/v1/wa/send/text

Send text message

Send a plain-text WhatsApp message to a phone number.

Required scopes: messages:write

Request Body

{
  "phone": "+1234567890",
  "text": "Hello from the API!",
  "account_id": 1
}

Response

{
  "success": true,
  "message_id": 42,
  "wa_id": "wamid.HBgL..."
}

POST


                                                            /api/v1/wa/send/template

Send template message

Send an approved WhatsApp template message with optional dynamic components.

Required scopes: messages:write

Request Body

{
  "phone": "+1234567890",
  "template_name": "order_confirmation",
  "language": "en_US",
  "components": [
    {
      "type": "body",
      "parameters": [
        {"type": "text", "text": "John"},
        {"type": "text", "text": "#ORD-1234"}
      ]
    }
  ]
}

Response

{
  "success": true,
  "message_id": 43,
  "wa_id": "wamid.HBgL..."
}

POST


                                                            /api/v1/wa/send/media

Send media message

Send an image, video, document, or audio message.

Required scopes: messages:write

Request Body

{
  "phone": "+1234567890",
  "media_type": "image",
  "media_url": "https://example.com/photo.jpg",
  "caption": "Check this out!",
  "account_id": 1
}

Response

{
  "success": true,
  "message_id": 44,
  "wa_id": "wamid.HBgL..."
}

POST


                                                            /api/v1/wa/send/interactive

Send interactive message

Send a message with buttons, lists, or other interactive elements.

Required scopes: messages:write

Request Body

{
  "phone": "+1234567890",
  "interactive": {
    "type": "button",
    "body": {"text": "Choose an option:"},
    "action": {
      "buttons": [
        {"type": "reply", "reply": {"id": "opt1", "title": "Option 1"}},
        {"type": "reply", "reply": {"id": "opt2", "title": "Option 2"}}
      ]
    }
  },
  "account_id": 1
}

Response

{
  "success": true,
  "message_id": 45,
  "wa_id": "wamid.HBgL..."
}

Conversations

GET


                                                            /api/v1/wa/conversations

List conversations

Retrieve a paginated list of WhatsApp conversations.

Required scopes: conversations:read

Query Parameters

Parameter	Type	Required	Description
`status`	string	No	Filter by status (open, closed, expired)
`limit`	integer	No	Max records to return
`offset`	integer	No	Number of records to skip

Response

{
  "data": [
    {
      "id": 1,
      "phone": "+1234567890",
      "status": "open",
      "contact_name": "John Doe",
      "last_message_at": "2025-06-15T10:30:00Z"
    }
  ],
  "count": 124
}

GET


                                                            /api/v1/wa/conversations/{id}

Get conversation

Retrieve a single conversation with its last 50 messages.

Required scopes: conversations:read

Response

{
  "id": 1,
  "phone": "+1234567890",
  "status": "open",
  "contact": {
    "id": 10,
    "name": "John Doe",
    "phone": "+1234567890"
  },
  "messages": [
    {
      "id": 501,
      "direction": "inbound",
      "body": "Hi there!",
      "timestamp": "2025-06-15T10:30:00Z"
    }
  ]
}

POST


                                                            /api/v1/wa/conversations/{id}/reply

Reply to conversation

Send a text reply within an existing conversation.

Required scopes: conversations:write

Request Body

{
  "text": "Thanks for reaching out!"
}

Response

{
  "success": true
}

Contacts

GET


                                                            /api/v1/wa/contacts

List contacts

Retrieve a paginated list of WhatsApp contacts.

Required scopes: contacts:read

Query Parameters

Parameter	Type	Required	Description
`limit`	integer	No	Max records to return
`offset`	integer	No	Number of records to skip

Response

{
  "data": [
    {
      "id": 10,
      "phone": "+1234567890",
      "name": "John Doe",
      "tags": ["vip", "support"]
    }
  ],
  "count": 350
}

POST


                                                            /api/v1/wa/contacts

Create or find contact

Create a new contact or return an existing one matched by phone number.

Required scopes: contacts:write

Request Body

{
  "phone": "+1234567890",
  "name": "John Doe"
}

Response

{
  "success": true,
  "contact_id": 10
}

PUT


                                                            /api/v1/wa/contacts/{id}

Update contact

Update an existing contact's name or tags.

Required scopes: contacts:write

Request Body

{
  "name": "John D.",
  "tags": ["vip"]
}

Response

{
  "success": true
}

Templates

GET


                                                            /api/v1/wa/templates

List approved templates

Retrieve all approved WhatsApp message templates for the account.

Required scopes: templates:read

Response

{
  "data": [
    {
      "id": 5,
      "template_name": "order_confirmation",
      "category": "UTILITY",
      "language": "en_US",
      "status": "approved",
      "body": "Hi {{1}}, your order {{2}} has been confirmed."
    }
  ]
}

Campaigns

GET


                                                            /api/v1/wa/campaigns

List campaigns

Retrieve a paginated list of WhatsApp campaigns.

Required scopes: campaigns:read

Query Parameters

Parameter	Type	Required	Description
`state`	string	No	Filter by state (draft, scheduled, sent, cancelled)
`limit`	integer	No	Max records to return
`offset`	integer	No	Number of records to skip

Response

{
  "data": [
    {
      "id": 3,
      "name": "Summer Promo",
      "state": "draft",
      "template_id": 5,
      "audience_count": 1200,
      "scheduled_at": null
    }
  ],
  "count": 8
}

POST


                                                            /api/v1/wa/campaigns

Create campaign

Create a new WhatsApp campaign in draft state.

Required scopes: campaigns:write

Request Body

{
  "name": "Summer Promo",
  "template_id": 5,
  "audience_domain": [["tag_ids.name", "=", "vip"]],
  "scheduled_at": "2025-07-01T09:00:00Z"
}

Response

{
  "success": true,
  "campaign_id": 3
}

POST


                                                            /api/v1/wa/campaigns/{id}/send

Send campaign

Immediately send a draft or scheduled campaign.

Required scopes: campaigns:write

Request Body

{}

Response

{
  "success": true,
  "state": "sending"
}

Usage

GET


                                                            /api/v1/wa/usage

Get usage stats

Retrieve current subscription usage and quota information.

Required scopes: usage:read

Response

{
  "plan": "professional",
  "state": "active",
  "conversations_used": 847,
  "conversations_limit": 5000,
  "api_calls_used": 12340,
  "api_calls_limit": 100000,
  "renewal_date": "2025-07-15"
}

Webhooks

POST


                                                            /api/v1/wa/webhooks

Required scopes: webhooks:write

Request Body

{
  "url": "https://example.com/webhook",
  "events": ["message.received", "message.status"],
  "secret": "my_signing_secret"
}

Response

{
  "success": true,
  "webhook_id": 7
}

DELETE


                                                            /api/v1/wa/webhooks/{id}

Delete webhook

Remove a previously registered webhook.

Required scopes: webhooks:write

Response

{
  "success": true
}

Code Examples

Send a text message in your favorite language

curl -X POST https://www.procomrades.com/api/v1/wa/send/text \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"phone": "+1234567890", "text": "Hello from our API!"}'

import requests

response = requests.post(
    "https://www.procomrades.com/api/v1/wa/send/text",
    headers={
        "Authorization": "Bearer YOUR_API_KEY",
        "Content-Type": "application/json",
    },
    json={
        "phone": "+1234567890",
        "text": "Hello from our API!",
    },
)
print(response.json())

const response = await fetch("https://www.procomrades.com/api/v1/wa/send/text", {
    method: "POST",
    headers: {
        "Authorization": "Bearer YOUR_API_KEY",
        "Content-Type": "application/json",
    },
    body: JSON.stringify({
        phone: "+1234567890",
        text: "Hello from our API!",
    }),
});
const data = await response.json();
console.log(data);

$ch = curl_init("https://www.procomrades.com/api/v1/wa/send/text");
curl_setopt_array($ch, [
    CURLOPT_POST => true,
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => [
        "Authorization: Bearer YOUR_API_KEY",
        "Content-Type: application/json",
    ],
    CURLOPT_POSTFIELDS => json_encode([
        "phone" => "+1234567890",
        "text" => "Hello from our API!",
    ]),
]);
$response = curl_exec($ch);
echo $response;

Error Codes

Status Code	Error	Description
400	Bad Request	The request body is malformed or missing required fields. Check the JSON payload and ensure all required parameters are provided.
401	Unauthorized	The API key is missing, invalid, or has been revoked. Verify your `Authorization` header contains a valid Bearer token.
403	Insufficient Scope	Your API key does not have the required scope for this endpoint. Check the endpoint's required scopes and update your key permissions.
404	Not Found	The requested resource does not exist. Verify the endpoint URL and any resource IDs in the path.
429	Rate Limit / Quota Exceeded	You have exceeded the per-minute rate limit or your monthly API call quota. Wait before retrying or upgrade your plan for higher limits.
500	Internal Server Error	An unexpected error occurred on the server. If the issue persists, contact support with the request ID from the response headers.

Rate Limiting

To ensure fair usage and platform stability, all API keys are subject to rate limiting:

Per-key default: 100 requests per minute. Requests exceeding this threshold will be queued or rejected.
Monthly API call quota: Each subscription plan includes a monthly API call allowance. Once exhausted, all API calls are rejected until the next billing cycle or until you upgrade your plan.
HTTP 429 response: When either the per-minute rate limit or the monthly quota is exceeded, the API returns a 429 Too Many Requests status. The response includes a Retry-After header indicating how many seconds to wait before retrying.

HTTP/1.1 429 Too Many Requests
Retry-After: 30
Content-Type: application/json

{
    "error": "rate_limit_exceeded",
    "message": "Too many requests. Please retry after 30 seconds.",
    "retry_after": 30
}

Webhooks

Receive real-time notifications when events occur on your WhatsApp account by registering webhook endpoints.

Registration

POST /api/v1/wa/webhooks

{
    "url": "https://your-server.com/webhook",
    "events": ["message.received", "message.status"],
    "secret": "your_webhook_secret"
}

Supported Events

Event	Description
`message.received`	Fired when a new inbound message is received from a contact
`message.status`	Fired when a message status changes (sent, delivered, read, failed)
`conversation.assigned`	Fired when a conversation is assigned to an agent or team
`conversation.resolved`	Fired when a conversation is marked as resolved

HMAC-SHA256 Signature Verification

Every webhook request includes an X-WA-Signature header containing an HMAC-SHA256 hex digest of the request body, signed with your webhook secret. Always verify this signature before processing the payload.

import hmac
import hashlib

def verify_signature(payload_body, signature, secret):
    """Verify the X-WA-Signature header."""
    expected = hmac.new(
        secret.encode("utf-8"),
        payload_body,
        hashlib.sha256,
    ).hexdigest()
    return hmac.compare_digest(expected, signature)

Payload Format

{
    "event": "message.received",
    "timestamp": "2026-03-26T12:00:00Z",
    "data": {
        "message_id": "wamid.HBgN...",
        "from": "+1234567890",
        "type": "text",
        "text": "Hi, I need help with my order.",
        "conversation_id": 42
    }
}

Ready to Build?

Get Started