Provider API

Use the Wevlix Provider API when your platform manages WhatsApp messaging for its own customers.

Your customers become managed Wevlix users. They do not receive Wevlix dashboard accounts, project API keys, individual wallets, or direct Wevlix logins.

Before you start

You need:

• An active Wevlix Platform Provider account
• A provider API credential
• The provider:onboarding:write scope
• An approved HTTPS return URL
• A backend capable of storing customer identifiers securely

Provider credentials are server-side secrets. Never expose them in browser or mobile application code.

Authentication

Send your provider credential using the X-API-Key header:

X-API-Key: your_provider_api_key

You may also use it as a Bearer credential when supported:

Authorization: Bearer your_provider_api_key

A provider credential is different from:

• A customer project API key
• A dashboard access token
• A Meta access token
• A WhatsApp webhook secret

Authentication errors

• 401 Unauthorized means the credential is missing, invalid, expired, or revoked.
• 403 Forbidden means the provider is inactive or the credential does not have the required scope.

Onboard your first customer

Customer onboarding uses a hosted Wevlix flow.

1. Create an onboarding session

Call:

POST /v1/provider/whatsapp/onboarding-sessions

Example:

curl --request POST \
  --url https://api.wevlix.com/v1/provider/whatsapp/onboarding-sessions \
  --header "X-API-Key: $WEVLIX_PROVIDER_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{
    "returnUrl": "https://partner.example.com/wevlix/callback",
    "metadata": {
      "customerId": "customer_123"
    }
  }'

The returnUrl must be an exact HTTPS URL already allowed for your provider account.

The optional metadata object is returned after onboarding. Use it for your own customer, tenant, plan, or correlation identifier. Do not place credentials or secrets in metadata.

Create a customer onboarding session

2. Redirect the customer

The response contains a hostedUrl.

Redirect the customer’s browser to that URL:

{
  "hostedUrl": "https://api.wevlix.com/provider/onboarding/..."
}

Wevlix hosts the Meta Embedded Signup experience. Your application must not call the internal hosted-page endpoints directly.

The onboarding session is valid for 15 minutes.

3. Receive the result code

After the customer finishes onboarding, Wevlix redirects the browser to your configured returnUrl with a short-lived resultCode.

Example:

https://partner.example.com/wevlix/callback?resultCode=...

Do not treat the browser redirect alone as proof that onboarding succeeded.

Send the result code from your backend to Wevlix to retrieve the completed onboarding result.

4. Exchange the result code

Call:

GET /v1/provider/onboarding-results/{resultCode}

Example:

curl --request GET \
  --url "https://api.wevlix.com/v1/provider/onboarding-results/$RESULT_CODE" \
  --header "X-API-Key: $WEVLIX_PROVIDER_API_KEY"

The result code:

• Is valid for 10 minutes
• Can be used only once
• Must be exchanged from your backend
• Must not be stored as a permanent customer identifier

Exchange an onboarding result code

5. Store the managed user ID

A successful result includes the managed Wevlix userId.

Store that identifier against the customer record in your platform:

{
  "userId": "managed_user_id",
  "metadata": {
    "customerId": "customer_123"
  }
}

Use the returned userId for later WhatsApp connection, template, messaging, usage, and customer-management requests.

After onboarding

After storing the managed userId, your backend can:

• Read the customer’s WhatsApp connection
• Synchronize WhatsApp account state
• Submit templates for Wevlix review
• List and synchronize templates
• Send approved template messages
• Read message delivery status
• Inspect customer usage
• Configure provider webhooks
• Manage scoped provider credentials

Open the Provider API Reference

Provider billing model

Managed customers do not have separate Wevlix wallets.

All provider-managed messaging is charged to the provider’s shared prepaid wallet. Your platform may store its own retail pricing metadata and bill customers independently.

Your provider account can access:

• Shared wallet balance
• Wallet ledger
• Top-up checkout
• Paid invoices and receipts
• Usage grouped by managed user
• Effective wholesale pricing
• Provider-owned retail pricing metadata

Webhooks

Configure a provider webhook to receive asynchronous lifecycle events.

Your backend should:

• Verify each webhook using the configured secret
• Return a successful response quickly
• Process events asynchronously
• Deduplicate repeated deliveries
• Store delivery identifiers
• Use replay controls only when necessary

Never expose the webhook secret to a browser or managed customer.

Credential security

• Store provider credentials in your backend secret manager.
• Never include credentials in URLs, metadata, logs, email, or frontend code.
• Issue credentials with only the scopes required by the integration.
• Rotate credentials periodically.
• Revoke a credential immediately if it may have been exposed.
• Use stable idempotency identifiers for retry-safe operations.
• Store Wevlix resource identifiers returned by successful requests.

Recommended integration sequence

1. Obtain and secure the provider credential.
2. Add the customer return URL to the provider allowlist.
3. Create a hosted onboarding session.
4. Redirect the customer to hostedUrl.
5. Receive and exchange resultCode.
6. Store the managed userId.
7. Read the customer’s WhatsApp connection.
8. Submit or synchronize templates.
9. Send an approved template message.
10. Track message status and webhook delivery.