REST API

Konviq API reference

Authenticated REST endpoints for sending messages, managing contacts, building broadcasts, and inspecting phone health. All requests are over HTTPS.

Download OpenAPI 3.1 spec Manage API keys

Base URL

https://api.konviq.in/v1

Authentication

Pass your API key as a Bearer token. Create one in the dashboard.

curl https://api.konviq.in/v1/health \
  -H "Authorization: Bearer wp_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"

Scopes

Each API key can be granted a subset of scopes. A key with no scopes has full access.

messages:send

messages:read

contacts:read

contacts:write

templates:read

broadcasts:write

broadcasts:read

Rate limits

Default: 100 requests / minute / key. Rate-limited responses return HTTP 429 with a Retry-After header.

Endpoints

GET
/v1/healthWorkspace health snapshot
GET
/v1/phone-numbersList connected WhatsApp numbers—
GET
/v1/contactsList contacts (paginated)contacts:read
POST
/v1/contactsCreate or update a contactcontacts:write
GET
/v1/contacts/{id}Retrieve a contactcontacts:read
PATCH
/v1/contacts/{id}Update a contactcontacts:write
GET
/v1/templatesList approved templatestemplates:read
POST
/v1/messagesSend a message (text or template)messages:send
GET
/v1/broadcastsList broadcastsbroadcasts:read
POST
/v1/broadcastsCreate a broadcastbroadcasts:write
GET
/v1/broadcasts/{id}Get a broadcastbroadcasts:read
POST
/v1/broadcasts/{id}Start a broadcastbroadcasts:write

Quick examples

Send a template message

Opens a new WhatsApp conversation.

curl -X POST https://api.konviq.in/v1/messages \
  -H "Authorization: Bearer wp_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "to": "+919876543210",
    "template": "welcome_v1",
    "language": "en",
    "variables": { "1": "Jane" }
  }'

Create a contact

Upserts by phone number.

curl -X POST https://api.konviq.in/v1/contacts \
  -H "Authorization: Bearer wp_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "phone": "+919876543210",
    "name": "Jane Doe",
    "email": "jane@example.com",
    "attributes": { "plan": "pro" },
    "tagIds": ["vip"]
  }'

Trigger a broadcast

Sends a template to filtered contacts.

curl -X POST https://api.konviq.in/v1/broadcasts \
  -H "Authorization: Bearer wp_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Diwali sale",
    "template": "diwali_offer",
    "audience": { "tagIds": ["vip"] },
    "variables": { "1": "20% off" }
  }'

Check phone health

Returns quality ratings and status.

curl https://api.konviq.in/v1/health \
  -H "Authorization: Bearer wp_live_..."

Errors

All errors return JSON with a stable code and a human message.

{
  "error": {
    "code": "no_open_session",
    "message": "No open service window. Use a template to start a new conversation."
  }
}

unauthorized— Missing or invalid API key

invalid_key— API key is revoked or wrong

insufficient_scope— API key is missing a required scope

rate_limited— Too many requests (HTTP 429)

no_open_session— Service window is closed — use a template

template_not_found— Template name is unknown or not approved

empty_audience— Broadcast audience filter matched zero contacts

internal_error— Server error — retry with backoff

Best practices: cache responses, respect rate limits, never put your API key in client-side code, rotate keys every 90 days, and always validate that contacts have optedIn: true before sending.