Webhook

The webhook adds leads from your own systems: a form on your website, your CRM, an app you built. You send one HTTP request per lead, the lead enters a campaign, and the campaign starts the WhatsApp conversation. Every account type can use the webhook.

Open the webhook page

Go to Integrations. The webhook is in the Automations group.
Turn on its switch. The webhook gets an entry in the sidebar and its card opens its page.
Open Integrations → Webhook.

The Connection section shows the Endpoint and your API key. The eye button shows the key, the copy button copies it.

Anyone with your API key can add leads to your account. Keep it on your server, never in a web page’s code.

Send a lead

POST https://api.whappy.ai/v1/lead

Headers

Content-Type: application/json
X-API-Key: YOUR_API_KEY

Body

{
  "name": "Mario Rossi",
  "phone": "+393331234567",
  "email": "mario@example.com",
  "campaign": "Spring promo",
  "tags": ["website"],
  "budget": "5000"
}

Field	What it does
`name`	The lead’s name.
`phone`	The WhatsApp number. Write it with its international prefix (`+39…`), or set a default country (see below).
`email`	Optional.
`campaign` or `campaign_id`	Optional. The campaign’s name, or its id. Leave both out to use your default campaign.
`tags`	Optional. A list, or text separated by commas. The tags are saved on the lead.
`language`	Optional. The lead’s language, as a code (`es`, `es-ES`) or an English name (`Spanish`). Used when Form or page language is on under Language of new leads (in Profile). An unknown value is ignored.
any other field	Saved on the lead, like `budget` above. The AI reads it, and WhatsApp templates can use it as `{{budget}}`.

name and phone are what a conversation needs. Fields inside a lead_data object are read as if they were at the top level.

Which campaign gets the lead

campaign_id, when you send it.
Otherwise the campaign whose name matches campaign.
Otherwise your default campaign. You choose it on the Campaigns page: open a campaign’s menu and pick Set as default.

The campaign must talk on WhatsApp. A campaign that talks only on Instagram cannot take a lead by phone number, and the request is refused (see Errors).

Phone numbers without a prefix

Open Profile and find Lead phone numbers. With a Default country set, a number that arrives without a prefix gets that country’s code. A number Whappy cannot read as a phone number is refused.

Code examples

cURL
JavaScript
Python

curl -X POST https://api.whappy.ai/v1/lead \
  -H "Content-Type: application/json" \
  -H "X-API-Key: YOUR_API_KEY" \
  -d '{
    "name": "Mario Rossi",
    "phone": "+393331234567",
    "email": "mario@example.com",
    "campaign": "Spring promo",
    "tags": ["website"],
    "budget": "5000"
  }'

const response = await fetch("https://api.whappy.ai/v1/lead", {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    "X-API-Key": "YOUR_API_KEY",
  },
  body: JSON.stringify({
    name: "Mario Rossi",
    phone: "+393331234567",
    email: "mario@example.com",
    campaign: "Spring promo",
    tags: ["website"],
    budget: "5000",
  }),
});
console.log(await response.json());

import requests

response = requests.post(
    "https://api.whappy.ai/v1/lead",
    headers={"X-API-Key": "YOUR_API_KEY"},
    json={
        "name": "Mario Rossi",
        "phone": "+393331234567",
        "email": "mario@example.com",
        "campaign": "Spring promo",
        "tags": ["website"],
        "budget": "5000",
    },
)
print(response.json())

Response

A 200 answer means the lead is in. data is the lead as Whappy saved it (shortened here):

{
  "status": "success",
  "message": "Lead created successfully",
  "data": {
    "name": "Mario Rossi",
    "phone": "+393331234567",
    "email": "mario@example.com",
    "tags": ["website"],
    "lead_info": {"budget": "5000"}
  }
}

The same person sent again to the same campaign (same phone) is not duplicated: the lead’s details are updated, and the answer is still 200. message says what happened:

`message`	Meaning
`Lead created successfully`	A new lead.
`Lead already exists; details merged`	The lead was already there; its details were updated.
`Lead already exists; details merged and campaign restart requested`	As above, and the campaign starts over with this lead. This happens only when the campaign’s Restart the campaign for a lead that comes back option is on and the conversation had already started.

Errors

Status	Body	Cause
`401`	`{"status": "error", "message": "Invalid API key"}`	The `X-API-Key` header holds a key Whappy does not know.
`401`	`{"status": "error", "message": "Authentication required. Provide a valid API key (X-API-Key header) or Bearer token."}`	No `X-API-Key` header.
`400`	`{"detail": "Phone number '…' is not a valid number…"}`	The phone cannot be read as a number. Add the international prefix, or set a default country.
`409`	`{"detail": {"code": "campaign_not_on_whatsapp", "message": "…"}}`	The campaign does not talk on WhatsApp. Turn on WhatsApp in the campaign’s options, or send the lead to another campaign.
`422`	`{"detail": [...]}`	The body is not a JSON object.
`500`	`{"detail": "…"}`	Whappy could not save the lead. Try again.

Test it

Send one request with just name and your own phone.
Check the answer is 200.
Open the campaign’s Leads tab and find the new lead.

Troubleshooting

The lead went to the wrong campaign. The campaign value has to be the campaign’s name, spelled the same (capitals do not matter). When no campaign matches, the lead goes to your default campaign. The lead is in, but no message arrives. The campaign has to be running, and your account needs a connected WhatsApp number. See WhatsApp. Need help? See the FAQ or contact support.

Conversations

E-commerce

AI clients

CRM

Leads

Appointment Setting

Advertising

Open the webhook page

Send a lead

Headers

Body

Which campaign gets the lead

Phone numbers without a prefix

Code examples

Response

Errors

Test it

Troubleshooting

​Open the webhook page

​Send a lead

​Headers

​Body

​Which campaign gets the lead

​Phone numbers without a prefix

​Code examples

​Response

​Errors

​Test it

​Troubleshooting

Open the webhook page

Send a lead

Headers

Body

Which campaign gets the lead

Phone numbers without a prefix

Code examples

Response

Errors

Test it

Troubleshooting