Wevlix Messaging API

What Wevlix Provides

Wevlix is a developer-focused messaging platform built on the official WhatsApp Business Platform. Each project has isolated credentials, balance, WhatsApp configuration, templates, message history, and operational controls. Your backend calls a focused API while Wevlix handles orchestration, retries, status updates, and billing.

Quickstart

Start in sandbox mode to exercise validation, persistence, queues, status reads, and OTP verification without contacting the live messaging network or charging the project balance.

1. Create a project in the Wevlix dashboard.
2. Login and retrieve the project API key from the setup endpoints, or copy it from the dashboard.
3. Use sandbox mode while building. Sandbox sends do not call Meta and do not charge balance.
4. Call POST /v1/otp/send from your backend.
5. Poll GET /v1/otp/status/{messageId} or store the returned message id.
6. Call POST /v1/otp/verify when the user submits the code.

Authenticate For Setup

Most teams copy a project API key from the Wevlix dashboard. Trusted first-party tooling may instead log in and retrieve it through the API. The short-lived dashboard token is only for setup operations; the project key authorizes messaging and project-scoped public APIs.

1. Call POST /v1/auth/login with the Wevlix account email and password.
2. Use the returned accessToken as Authorization: Bearer ....
3. Call GET /v1/projects/{projectId}/api-keys.
4. Choose the active key by id or name.
5. Use its rawKey as x-api-key for project API calls.

1. Login

curl -X POST https://api.wevlix.com/v1/auth/login \
  -H "Content-Type: application/json" \
  -d '{
    "email": "[email protected]",
    "password": "StrongPass123!"
  }'

2. Get a project API key

curl https://api.wevlix.com/v1/projects/{projectId}/api-keys \
  -H "Authorization: Bearer $ACCESS_TOKEN"

3. Send with the project key

curl -X POST https://api.wevlix.com/v1/otp/send \
  -H "x-api-key: $PROJECT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "to": "+{country_code}{subscriber_number}",
    "otpMode": "generated",
    "clientMessageId": "login_attempt_123456"
  }'

Credentials

Wevlix uses different credentials for different jobs. Keep them separate in your codebase so dashboard setup, production sends, and local testing never accidentally share the same secret.

Required headers

x-api-key: wvlx_live_or_dev_key
Content-Type: application/json

Live And Sandbox Modes

Delivery behavior is resolved from both the project runtime mode and the key type. This keeps production keys useful in sandbox projects while making development keys safe in every environment.

OTP Flow

OTP sends are a simplified, template-backed form of authentication messaging. Start with only to. Wevlix generates a six-digit code when both otpMode and code are omitted. A provided code may contain exactly four or six digits. Supplying code without otpMode is also valid and automatically selects provided mode.

1. Minimum generated-code request

{
  "to": "+12345678900"
}

2. Add your own code when your backend generates it

{
  "to": "+12345678900",
  "code": "123456"
}

Writing "otpMode": "provided" is optional when code is present. If you explicitly use "otpMode": "provided", the code is required. Do not send a code with "otpMode": "generated".

Which WhatsApp template is used?

Generated and provided codes use the same template-selection rules. In live mode, Wevlix chooses an approved, sendable AUTHENTICATION template belonging to the connected project WhatsApp account. It prefers the requested locale, then a compatible language match, then the earliest eligible authentication template.

3. Add retry protection and locale only when needed

{
  "to": "+12345678900",
  "clientMessageId": "login_attempt_123456",
  "locale": "en"
}

Template Messaging

Use template messaging for approved authentication, utility, and marketing templates. Retrieve the Wevlix template id from the project template list, pass variable values in template placeholder order, and store the returned messageId for status reads.

Send an approved template

The fastest path is to request a template-specific integration example. It verifies the template against the project in your API key and returns the exact parameter order, sample JSON, and a ready-to-copy cURL command.

curl https://api.wevlix.com/v1/templates/{wevlix_template_id}/integration   -H "x-api-key: $PROJECT_API_KEY"

curl -X POST https://api.wevlix.com/v1/messages/template   -H "x-api-key: $PROJECT_API_KEY"   -H "Content-Type: application/json"   -d '{
    "to": "+{country_code}{subscriber_number}",
    "templateId": "{wevlix_template_id}",
    "variables": ["Customer"],
    "clientMessageId": "order_confirmation_12345"
  }'

How variables are ordered

Wevlix orders simple values by component: text-header variables first, then body variables, then dynamic URL buttons by button position. Placeholders are scoped to their component, so body {{1}} and button {{1}} are separate values. Use the generated integration response instead of calculating this order yourself.

Creation components versus send components

Components shown in a template definition describe its approved text, examples, and buttons. They cannot be copied into a send request. Send either the generated variables array or Meta-style message components containing parameters.

Media headers

For an approved template with an image, video, or document header, use components and provide either a stable HTTPS public link or a provider media id. The media object must match the approved header type. Captions are not supported in template headers.

"components": [{
  "type": "header",
  "parameters": [{
    "type": "image",
    "image": { "link": "https://cdn.example.com/campaign.jpg" }
  }]
}]

Message Statuses

Store the returned messageId and use it to inspect delivery and verification progress. Statuses are stable string values and should be treated as an enum in your integration.

Status responses may include a recovery object while Wevlix refreshes a submitted Meta-pending template or repairs an explicitly unregistered sender or incomplete WhatsApp billing setup. Recovery uses the same message id, stops within six minutes, and does not automatically resend ambiguous transport timeouts.

Backend Code Examples

These examples are intentionally server-side. Your browser or mobile app should call your own backend, and your backend should call Wevlix.

const response = await fetch('https://api.wevlix.com/v1/otp/send', {
  method: 'POST',
  headers: {
    'content-type': 'application/json',
    'x-api-key': process.env.WEVLIX_API_KEY,
  },
  body: JSON.stringify({
    to: '+{country_code}{subscriber_number}',
    otpMode: 'generated',
    clientMessageId: 'login_attempt_123456',
  }),
});

const result = await response.json();

const response = await fetch('https://api.wevlix.com/v1/otp/verify', {
  method: 'POST',
  headers: {
    'content-type': 'application/json',
    'x-api-key': process.env.WEVLIX_API_KEY,
  },
  body: JSON.stringify({
    messageId: 'msg_123',
    code: '123456',
  }),
});

const verification = await response.json();

Pricing

Customer-facing quotes return totals only. Internal Meta fees, markup, floors, caps, and project-specific overrides stay hidden from customers.

Public landing calculator

These read-only routes require no credentials and are safe for a public website. The estimate starts at the first monthly tier and includes tier transitions across the requested quantity.

Project-specific quote

Use quotes before high-volume sends or to show expected cost in your own admin tools. Actual charging happens from delivered message events.

Responses And Errors

JSON endpoints return a stable envelope with success, data or error, and request metadata. Keep the requestId when contacting support.

{
  "success": true,
  "data": {},
  "meta": {
    "requestId": "f3f0d89a-...",
    "timestamp": "2026-06-16T12:00:00.000Z"
  }
}

{
  "success": false,
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Validation failed"
  },
  "meta": {
    "requestId": "f3f0d89a-..."
  }
          }

Common error codes

Message status responses expose stable failureCode, failureReason, and failureRetryable fields. Upstream transport names and raw provider payloads are never included in customer-facing responses.

Production Checklist

• Connect your WhatsApp Business Account from the Wevlix dashboard.
• Sync or create the templates your message flows require and wait for Meta approval.
• Top up the project balance before switching high-traffic flows to live mode.
• Use idempotent clientMessageId values for retry-safe sends.
• Store Wevlix messageId values for status and verification checks.
• Handle asynchronous status changes and terminal failures in your application.
• Rotate API keys regularly and scope development keys to test phone numbers.