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. This endpoint reports the assisted setup request, not the live connection record.

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.

Call from your backend with Content-Type: application/json and either bearer authentication or X-LeadIntel-Platform-Key. No tenant ID, connection ID, Meta login, QR scan, or SMS code is required for this lookup.

curl --request POST "$LEAD_INTEL_API_BASE_URL/external-platform/whatsapp/connections/lookup" \
  --header "X-LeadIntel-Platform-Key: $LEAD_INTEL_PLATFORM_KEY" \
  --header "Content-Type: application/json" \
  --data '{"phoneNumber":"+254700000000"}'

Set LEAD_INTEL_API_BASE_URL to the API base URL shown above (including /api) and LEAD_INTEL_PLATFORM_KEY to your issued key in your backend's secret configuration. Replace the sample number with the connected WhatsApp business number. Never put the key in browser code, URLs, or logs.

{
  "externalPlatformTenantId": "tenant_42",
  "externalConnectionId": "wa_primary",
  "phoneNumberId": "123456789012345",
  "displayPhoneNumber": "+254700000000",
  "status": "active",
  "disconnectedAt": null,
  "updatedAt": "2026-09-28T08:00:00.000Z"
}

Use the recovered connection

1. Save externalPlatformTenantId as your tenantId and externalConnectionId as your connectionId against the correct customer in your system. Finding a number does not authenticate that customer; enforce your own customer permissions before exposing it.
2. If status is active, reuse the existing connection. Save phoneNumberId to identify incoming webhooks.
3. Use GET /api/external-platform/whatsapp/connections/{tenantId}/{connectionId} for current settings, or the documented send endpoint to send messages. URL-encode both IDs when building paths.
4. If the returned connection is not active, do not send through it. Follow your recovery process or contact Lead Intel; this lookup does not reactivate it. A permanently deleted connection cannot be recovered with this endpoint.

Errors and recovery

Scope and privacyResults are restricted to connections owned by the supplied platform key. This is not a global phone directory or personal-account SMS verification. Provider access tokens and webhook signing secrets are never returned. Responses use Cache-Control: no-store; avoid logging phone numbers or caching these responses in shared infrastructure.

Check whether a number is connected in Lead Intel and can be claimed. Body: {"phoneNumber":"+254700000000"}.

{ "connected": true, "claimable": true, "displayPhoneNumber": "+254700000000" }

When claimable is false, reason is phone_number_already_connected (another platform owns it) or number_not_claimable. A number Lead Intel doesn't hold returns 404 number_not_connected; use assisted setup instead.

Sends the SMS code to the number and returns a claimId. The code expires in 10 minutes.

curl --request POST "$LEAD_INTEL_API_BASE_URL/external-platform/whatsapp/existing-numbers/claims" \
  --header "X-LeadIntel-Platform-Key: $LEAD_INTEL_PLATFORM_KEY" \
  --header "Content-Type: application/json" \
  --data '{"phoneNumber":"+254700000000","externalPlatformTenantId":"tenant_42","externalConnectionId":"wa_primary","inboundWebhookUrl":"https://example.com/leadintel/whatsapp","inboundWebhookSecret":"your-signing-secret"}'

{ "claimId": 17, "status": "code_sent", "sentTo": "+254700000000", "expiresAt": "2026-10-12T21:10:00.000Z" }

Body: {"code":"123456"}. On success the number is connected to your platform immediately, and its incoming messages go to your webhook. Use the returned IDs with the connection, send and lookup endpoints exactly as for any other connection.

{
  "status": "connected",
  "externalPlatformTenantId": "tenant_42",
  "externalUserId": null,
  "externalConnectionId": "wa_primary",
  "phoneNumberId": "123456789012345",
  "displayPhoneNumber": "+254700000000"
}

Errors and recovery

OwnershipOnly whoever holds the number's SIM can complete a claim. Leads of the Lead Intel business that used the number still have their replies routed to that business; everyone else goes to your webhook.

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 Lead Intel accepted and submitted the message to its WhatsApp provider; it is not delivery confirmation. Reuse the same Idempotency-Key only when retrying the same recipient and message. A completed replay returns the saved result without sending again; reuse with different content returns 409.

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

The tap arrives as a normal incoming message on your webhook. Route on the id you set, not on the title.

{
  "messages": [{
    "from": "254700000000",
    "type": "interactive",
    "interactive": {
      "type": "button_reply",
      "button_reply": { "id": "book_demo", "title": "Book a demo" }
    }
  }]
}

Errors

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 Lead Intel accepted and submitted the message to its WhatsApp provider and returns its messageId when available. It does not guarantee final delivery. 400 means the idempotency key or message is invalid; 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. Monitor provider delivery events or your own conversation records when delivery status matters.

{
  "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. Retry a 502 deliberately with that same key; do not create a new key for an uncertain attempt, because that can create another send.

Create a WhatsApp message template on the connection's own WhatsApp Business Account and submit it to Meta for review. Send multipart/form-data (required when uploading a header sample) or plain form fields. Once the template is approved, send it with the template message type above.

curl --request POST "$LEAD_INTEL_API_BASE_URL/external-platform/whatsapp/connections/tenant_42/wa_primary/templates" \
  --header "Authorization: Bearer $LEAD_INTEL_PLATFORM_KEY" \
  --form name=welcome_offer \
  --form language=en \
  --form category=MARKETING \
  --form bodyText="Hi {{1}}, thanks for your interest in {{2}}! Want a quick call?" \
  --form 'buttons=[{"type":"QUICK_REPLY","text":"Yes please"},{"type":"QUICK_REPLY","text":"Not now"}]'

HTTP/1.1 201 Created
{ "name": "welcome_offer", "language": "en", "category": "MARKETING",
  "status": "pending", "metaId": "123456789", "variableCount": 2 }

What you get: 201 means Meta accepted the template for review; status is normally pending. Poll the list endpoint until it is approved or rejected. 400 carries an error code (invalid_template_name, invalid_body_text, invalid_buttons, invalid_variables, sample_required, invalid_sample_file or template_submission_failed) and a detail message, including Meta's reason when it rejects the submission. 404 means the connection was not found and 409 means it is not active. Media headers also require the platform's Meta App ID to be configured.

List the templates on the connection's WhatsApp Business Account, straight from Meta. Add ?status=approved (or pending, rejected) to filter.

HTTP/1.1 200 OK
{ "templates": [
  { "name": "welcome_offer", "status": "approved", "category": "MARKETING",
    "language": "en", "rejectedReason": null, "components": [ ... ] }
] }

A 502 with template_list_failed means Meta could not be reached or refused the request.

Delete a template by name from the connection's WhatsApp Business Account. Returns 204; a template that no longer exists at Meta also returns 204. A 502 with template_delete_failed means Meta refused the deletion.

Template writes are limited to 60 requests per 10 minutes and reads to 120 per 10 minutes.

Authenticate with the platform key using Authorization: Bearer li_platform_... or X-LeadIntel-Platform-Key. The URL tenant and lead references are resolved together with the authenticated key and the required connection ID; a raw workspace or lead ID is never authorized alone. leadId is the Lead Intel lead ID, scoped by the authenticated platform key, externalPlatformTenantId, and externalConnectionId.

POST /api/external-platform/leads/tenant_42/12345/response
Authorization: Bearer li_platform_...
Content-Type: application/json

{
  "externalConnectionId": "wa_primary",
  "eventId": "reply_evt_8f2",
  "channel": "whatsapp",
  "body": "Yes, please send details.",
  "occurredAt": "2026-09-02T12:10:00.000Z"
}

The channel must be email, sms, or whatsapp. body is optional when only the confirmed response state is available; Lead Intel stores an explicit marker, Response confirmed by external platform (message content not provided)., rather than pretending to know the user's text. eventId (or messageId) is required. Idempotency is scoped to the authenticated platform key, tenant, connection, Lead Intel lead, and channel, so the same event ID can safely exist in separate scopes; safely retry the same request as often as needed.

{
  "ok": true,
  "duplicate": false,
  "leadId": 12345,
  "status": "replied",
  "queueStopped": true
}

A body records an inbound message and activity, advances a new or contacted lead to replied, updates its latest message, and halts its queue. Replays return success with duplicate: true without another message or activity. A confirmed response never marks a lead not_interested.

Lead Intel's own connected email, SMS, and WhatsApp channels report replies internally and apply the same stop behavior; use this endpoint only for confirmed replies received through your external platform.