v1.0 REST API

Wpbox API Reference

Detailed references, endpoints, and examples for integrating with the WACM Wpbox V1 API.

Download as Markdown

Base URL

https://app.wacm.in/api/v1

Authentication

The API uses Bearer tokens for authentication. Include your token in the Authorization header of every request.

HTTP Header (Recommended)

Send the token securely in the request header.

Query Parameter (Fallback)

If your system cannot send HTTP headers, you can append ?token=YOUR_API_TOKEN to the URL.

Example Request Header

Authorization: Bearer YOUR_API_TOKEN

Profile

GET /api/v1/me

Retrieves the authenticated user and company profile.

Response: Profile 200 OK

{
  "status": "success",
  "message": "Profile retrieved successfully",
  "data": {
    "id": 1,
    "name": "John Doe",
    "email": "admin@example.com",
    "company_id": 1
  }
}

Messages

POST GET /api/v1/messages/text

Send a standard text or media message to a phone number. Supports both POST and GET for legacy integration.

Parameters

Parameter	Description
phone Req	Recipient's phone number with country code.
message	Text content of the message.
media_url	Public URL for sending an image/video.

POST GET /api/v1/messages/template

Send a pre-approved WhatsApp template message.

Parameters

Parameter	Description
phone Req	Recipient's phone number.
template_name Req	The exact name of the template.
template_language	Language code (e.g. en, es). Default is en. (Alias: language)
components	Array of component parameters for dynamic variables (Standard).
Legacy / Simple Parameters
variables	JSON Array of strings to replace 1 variables.
document / image	Public URL for sending media in the template header.

POST GET /api/v1/messages/list

Send an interactive list message.

Parameters

Parameter	Description
phone Req	Recipient's phone number.
message Req	Main body text.
action Req	List action definition.
header / footer	Header/footer text.

Response: Send Message 200 OK

{
  "status": "success",
  "message": "Message sent successfully",
  "data": {
    "message_id": 105,
    "message_wamid": "wamid.HBgL..."
  }
}

Request: Template (Standard) POST Payload

{
  "phone": "1234567890",
  "template_name": "welcome_message",
  "components": [
    {
      "type": "body",
      "parameters": [
        { "type": "text", "text": "John" }
      ]
    }
  ]
}

Request: Template (Legacy) POST Payload

{
  "phone": "1234567890",
  "template_name": "welcome_message",
  "language": "en",
  "variables": ["John", "Doe"],
  "document": "https://example.com/file.pdf"
}

Contacts

GET /api/v1/contacts

Retrieve a paginated list of contacts. Add ?update_from=YYYY-MM-DD HH:MM:SS to filter recently modified contacts. Use ?page=1&limit=15 for pagination, and ?search=QUERY to search by name or phone.

POST /api/v1/contacts

Create or upsert a contact by phone number.

Parameters

Parameter	Description
phone Req	Contact phone number.
name / email	Full name and email address.
groups	Comma-separated string or array of group names.
custom	Key-value object of custom fields.
enabled_ai_bot	Enable (1) or disable (0) AI Bot.

POST /api/v1/contacts/bulk-sync

Create or match contacts in bulk and optionally assign them to a company-owned group or tag. Assignments are additive and repeated requests do not create duplicate memberships.

contacts is required and must be a non-empty array.
Every contacts.*.phone must contain at least one digit; name is optional.
country_code, group_id, and tag_id are optional.
The group or tag must belong to the authenticated company. Invalid input returns HTTP 422.

GET /api/v1/contacts/{id}

PUT /api/v1/contacts/{id}

Retrieve or fully update (using the same payload as POST) a contact by their database ID.

GET /api/v1/contacts/{id}/groups-and-fields

GET /api/v1/contacts/{id}/notes

POST /api/v1/contacts/check-phone

DEL /api/v1/contacts/{id}

Retrieve nested contact relationships, request an evidence-based WhatsApp reachability check, or soft-delete a contact. Phone checks accept phone and optional refresh=true. A pending Meta webhook returns HTTP 202 with a null boolean result.

Request: Upsert Contact POST Payload

{
  "phone": "1234567890",
  "name": "Jane Doe",
  "groups": ["VIP", "Leads"],
  "custom": {
    "Company": "Acme Corp",
    "Role": "Manager"
  },
  "enabled_ai_bot": 1
}

Request: Bulk Sync to Group POST Payload

{
  "contacts": [
    {"phone": "9876543210", "name": "Jane Doe"},
    {"phone": "+919876543211", "name": "John Doe"}
  ],
  "country_code": "91",
  "group_id": 123
}

Response: Check Phone 200 OK / 202 Pending

{
  "status": "success",
  "message": "Phone checked successfully",
  "data": {
    "phone": "919876543210",
    "is_valid": null,
    "exists_on_whatsapp": null,
    "check_status": "pending",
    "source": "live_pending"
  }
}

Templates

GET /api/v1/templates

List all available templates. Use ?name=TEMPLATE_NAME to filter by exact name.

GET /api/v1/templates/{id}

Retrieve details of a specific template by ID.

Campaigns

GET /api/v1/campaigns

List paginated campaigns. Filter using ?type=bot|api|regular. Use ?page=1&limit=15 for pagination, and ?search=QUERY to search by name.

POST /api/v1/campaigns

Create and durably queue a new campaign. Supports multipart/form-data for media uploads. Campaign construction and Meta delivery are asynchronous. Send a unique Idempotency-Key header so a client timeout can be retried without creating a second billable campaign. Reusing the key with different parameters returns HTTP 409.

Parameters

Parameter	Description
name Req	Campaign name.
template_id Req	ID of the approved template to use.
audience_type	`all`, `group`, or `contact`. If omitted, it is inferred from group_id/contact_id and otherwise defaults to all.
group_id	Required when audience_type is group. The group must belong to the authenticated company.
contact_id	Required when audience_type is contact. The contact must belong to the authenticated company.
send_now	Send immediately (1) or schedule later (0).
send_time	Time to send (if send_now is 0).
paramvalues	Dynamic variables as a JSON object, JSON string, or array.
parammatch	Template-to-contact variable mapping as a JSON object, JSON string, or array.
prevent_template_duplicates	When true, exclude contacts already represented by a campaign using this template.
pdf / imageupload	Media file to attach.

POST /api/v1/campaigns/audience-preview

Return the eligible audience count before creation. Marketing previews exclude opted-out, unsubscribed, deleted, and known non-WhatsApp contacts.

GET /api/v1/campaigns/{id}

PUT /api/v1/campaigns/{id}

DEL /api/v1/campaigns/{id}

Retrieve stats, delete, or update a campaign's active status (use is_active: true/false to pause or resume).

GET /api/v1/campaigns/{id}/messages?status=scheduled|processing|sent|delivered|read|failed returns paginated message execution records. Processing corresponds to internal status 6.

POST /api/v1/campaigns/{id}/retry safely reschedules eligible failures; ambiguous-send and protected duplicate failures remain unchanged.

POST /api/v1/campaigns/send

Create a scheduled campaign message for a contact. The response contains the local message ID and queue state. message_wamid is normally null until Meta accepts the asynchronous send; follow the campaign messages endpoint or webhooks for final status.

Parameters

Parameter	Description
phone Req	Contact's phone number.
campaign_id Req	ID of the campaign. (Alias: campaing_id)
data	Dynamic variables mapping to the template.

Conversations

GET /api/v1/conversations

Get a paginated list of active chat conversations. Use ?lastmessagetime=YYYY-MM-DD HH:MM:SS to sync new conversations. Use ?page=1&limit=50 for pagination, and ?search=QUERY to search by name or phone.

GET /api/v1/conversations/{id}/messages

Fetch the message timeline for a specific conversation ID. Supports ?lastmessagetime filter, ?before_id cursor pagination, ?limit=50, and ?search=QUERY.

Groups

GET /api/v1/groups

Retrieve contact groups. Use ?showContacts=yes to eagerly load all assigned contacts.

POST /api/v1/groups

PUT /api/v1/groups/{id}

DEL /api/v1/groups/{id}

Create, rename, or delete a group owned by the authenticated company. Create and update requests require a name.

GET /api/v1/groups/{id}/preflight

Return campaign readiness counts using local contact data and existing webhook evidence. This endpoint validates phone formatting, consent, known reachability, and duplicates without sending WhatsApp messages. The former /check-phones endpoint remains temporarily available as a deprecated alias and also sends no messages.