Connect, receive, and send WhatsApp messages

Create one request for each WhatsApp number. Call this endpoint from your backend; browser requests and frontend callbacks are not supported.

POST /api/external-platform/whatsapp/assisted-requests
Authorization: Bearer li_platform_...
Content-Type: application/json

{
  "externalPlatformTenantId": "tenant_42",
  "externalUserId": "user_108",
  "externalConnectionId": "wa_primary",
  "countryCode": "254",
  "phoneNumber": "700000000",
  "businessName": "Acme Stores",
  "displayName": "Acme Support",
  "businessProfile": {
    "profileImageUrl": "https://cdn.example.com/acme-logo-512x512.jpg",
    "about": "Customer support and online orders",
    "description": "Acme Stores provides retail products and customer support.",
    "address": "123 Business Street, Riyadh",
    "email": "support@example.com",
    "websites": ["https://example.com"],
    "vertical": "RETAIL"
  },
  "inboundWebhookUrl": "https://api.your-platform.example/whatsapp/inbound",
  "inboundWebhookSecret": "your-signing-secret",
  "inboundWebhookTimeoutMs": 10000
}

{
  "requestId": "request_...",
  "status": "pending"
}

What you get: 202 Accepted means the setup request was saved. It does not mean the number is connected. Save requestId, then use the status endpoint below.

Optional fields are real setup controls: omit externalUserId, businessProfile, or inboundWebhookTimeoutMs only when you do not need them. If you include businessProfile, Lead Intel applies it after WhatsApp verification; you can also change it later with PATCH.

Verified name limitation: displayName is submitted to Meta as the number's verified name during initial setup. It is not an ordinary profile field and cannot be changed through the connection PATCH endpoint. Meta limits how often a verified name can be submitted or changed. If the status response contains verified_name_change_limit_reached, stop retrying the setup request and wait for Meta's limit to clear or contact Meta support.

Duplicate number: before accepting the request, Lead Intel checks whether the number is already connected to a Lead Intel workspace, product, or active external connection, or has appeared in any earlier external assisted-setup request—including failed or cancelled requests. If it exists, the API returns 409 with {"error":"phone_number_already_connected"}. Do not retry with the same number or start Meta verification.

Use the requestId from step 1. Check every few seconds while setup is running. The response tells you whether to keep waiting, start using the connection, or show an error.

GET /api/external-platform/whatsapp/assisted-requests/{requestId}
Authorization: Bearer li_platform_...

{
  "requestId": "request_...",
  "status": "connected",
  "externalPlatformTenantId": "tenant_42",
  "externalConnectionId": "wa_primary",
  "displayPhoneNumber": "+254700000000",
  "errorCode": null,
  "errorMessage": null,
  "updatedAt": "2026-09-01T12:10:00.000Z"
}

The example shows the fields your application normally needs. The full response also echoes the submitted setup details and timestamps. It never returns provider credentials, verification codes, or your webhook secret.

Use this call when you need the current connection state or webhook configuration. Save phoneNumberId: incoming webhook bodies include that value, so it tells you which connection received the message.

{
  "externalConnectionId": "wa_primary",
  "phoneNumberId": "provider-phone-id",
  "displayPhoneNumber": "+254700000000",
  "status": "active",
  "inboundWebhookUrl": "https://api.your-platform.example/whatsapp/inbound",
  "inboundWebhookTimeoutMs": 10000,
  "businessProfile": {
    "profileImageConfigured": true
  },
  "updatedAt": "2026-09-01T12:10:00.000Z"
}

Update the receiver configuration and/or the public WhatsApp Business Profile for an active connection. Send only the fields you want to change; omitted fields stay unchanged. When businessProfile is included, Lead Intel calls Meta using the connected number's credentials before saving the new profile locally. A 204 response means the requested update succeeded in Meta and Lead Intel.

PATCH /api/external-platform/whatsapp/connections/tenant_42/wa_primary
Authorization: Bearer li_platform_...
Content-Type: application/json

{
  "businessProfile": {
    "profileImageUrl": "https://cdn.acme.example/new-profile.png",
    "about": "Acme support, now 24/7",
    "address": "Nairobi, Kenya",
    "description": "Customer support for Acme customers",
    "email": "help@acme.example",
    "websites": ["https://acme.example/help"],
    "vertical": "RETAIL"
  }
}

Send inboundWebhookSecret only when you want a new signing secret. Send inboundWebhookTimeoutMs only when you want to change how long Lead Intel waits for an immediate reply. Inside businessProfile, supported fields are profileImageUrl, about, address, description, email, websites (up to two HTTP(S) URLs), and vertical. A profile image must be a publicly reachable HTTPS JPG/JPEG URL, larger than 192 × 192 pixels, and no larger than 5 MB. Use a square image where possible; Lead Intel downloads it and uploads it to Meta.

This is the single cleanup call. Lead Intel first deregisters the number from Meta, then permanently removes the connection and its Lead Intel records. A successful request returns 204 only after both steps complete. If an older request already marked the local connection disconnected without completing Meta cleanup, this endpoint reconciles it with Meta instead of silently assuming deregistration succeeded.

DELETE /api/external-platform/whatsapp/connections/tenant_42/wa_primary
Authorization: Bearer li_platform_...

Provider-first safety: if Meta rejects deregistration, Lead Intel returns 502 with {"error":"meta_deregistration_failed"} and deletes nothing. Retry the same call after resolving the Meta issue. This endpoint removes the connection, matching setup requests and sessions, lifecycle events, and delivery history. The external tenant and platform key remain available for a new number.

To cancel a setup request that is still pending, call DELETE /external-platform/whatsapp/assisted-requests/{requestId} instead.

Every delivery attempt is a signed POST. Lead Intel may retry temporary failures, so duplicate protection is required. It never sends a GET or HEAD request to test the URL.

Content-Type: application/json
X-LeadIntel-Event-Id: external-message:...
X-LeadIntel-Timestamp: 1788206400000
X-LeadIntel-Signature: lowercase-hex-hmac-sha256

{
  "messaging_product": "whatsapp",
  "metadata": {
    "display_phone_number": "254 700 000000",
    "phone_number_id": "provider-phone-id"
  },
  "messages": [{
    "id": "wamid...",
    "from": "254700000000",
    "timestamp": "1788206400",
    "type": "text",
    "text": { "body": "Hello" }
  }]
}

// 1. Verify X-LeadIntel-Signature over the exact raw body.
// 2. Parse the body and inspect messages[].
const message = body.messages[0];
const media = message[message.type];

if (media?.downloadUrl) {
  // 3. Download immediately; no Meta token is needed.
  const file = await fetch(media.downloadUrl);
  if (!file.ok) throw new Error(`Media download failed: ${file.status}`);
  const bytes = await file.arrayBuffer();
  // 4. Store/process bytes before media.expiresAt.
}

Supported inbound mediaUse the signed URL to download image, audio (including voice notes), video, document, or sticker files. Download from your backend, do not add a Meta access token, and do not retry a URL after it expires.

Build the signed text as {timestamp}.{exactRawBody}. Use the connection's inboundWebhookSecret as the HMAC key, compare the lowercase hexadecimal result with a timing-safe check, and reject timestamps more than five minutes from the current time.

const expected = createHmac('sha256', inboundWebhookSecret)
  .update(`${timestamp}.${rawBody}`)
  .digest('hex');

Use this when the reply is ready before the webhook timeout. The response body becomes the WhatsApp reply to the sender.

Content-Type: application/json

{ "type": "text", "text": "Thanks — how can we help?" }

Text must be non-empty and no longer than 4,000 characters.

{
  "type": "media",
  "mediaType": "document",
  "url": "https://cdn.prosuite.example/quote.pdf",
  "caption": "Your quote",
  "filename": "quote.pdf"
}

The media URL must be public HTTPS so Meta can download it. Supported mediaType values are image, video, audio, and document. For any other successful response, return valid reply JSON or Lead Intel will reject the delivery.

Use this when your application needs more time. Save the event first, return 202 or 204 with no reply body, then call the send endpoint when the reply is ready.

POST /api/external-platform/whatsapp/connections/tenant_42/wa_primary/send
Authorization: Bearer li_platform_...
Idempotency-Key: reply-wamid-1
Content-Type: application/json

{
  "to": "254700000000",
  "type": "text",
  "text": "Your asynchronous reply"
}

What you get: 202 Accepted means Meta accepted the send request. Reuse the same Idempotency-Key only when retrying the same recipient and message; using it for different content returns 409.

Review the response codes Lead Intel accepts from your receiver and how each one affects delivery retries.

Choose the active connection in the URL and put the recipient in to. This minimum example sends text.

Authorization: Bearer li_platform_...
Idempotency-Key: prosuite-message-abc-123
Content-Type: application/json

{
  "to": "254700000000",
  "text": "Your message"
}

HTTP/1.1 202 Accepted
{ "messageId": "wamid....", "status": "accepted" }

What you get: 202 means Meta accepted the message and returns its messageId when available. It does not guarantee final delivery. 404 means the connection was not found, 409 means the connection is inactive or the key was reused for different content, and 502 means the send failed.

{
  "to": "254700000000",
  "type": "media",
  "mediaType": "image",
  "url": "https://cdn.prosuite.example/property.jpg",
  "caption": "Available property"
}

{
  "to": "254700000000",
  "type": "template",
  "name": "appointment_reminder",
  "language": "en",
  "components": []
}

When retrying, reuse an idempotency key only with the same recipient and message body.