Quickstart

This guide takes you from a connected number to your first message sent through the API, and then to events arriving on your server.

Before you startCopy Anchor Link

• A Wappfy account at app.wappfy.io.
• A WhatsApp number connected in the dashboard (Connections), with the status Connected.
• You must be the owner of the connection: people it was shared with cannot generate keys for it.

1. Generate an API keyCopy Anchor Link

2. Check the connectionCopy Anchor Link

curl https://app.wappfy.io/api/v1/instance \
  -H "X-Api-Key: wpf_YOUR_KEY"

{
  "data": {
    "id": 12,
    "name": "Support",
    "status": "connected",
    "connected": true,
    "phone": "5581988888888",
    "push_name": "Downtown Store",
    "profile_picture_url": null,
    "status_updated_at": "2026-10-14T12:00:00.000Z"
  }
}

Sends only work while connected is true. A 401 chave_invalida means the key is missing, mistyped or revoked.

3. Send your first messageCopy Anchor Link

curl -X POST https://app.wappfy.io/api/v1/messages/text \
  -H "X-Api-Key: wpf_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: order-1234-confirmation" \
  -d '{ "to": "5581999999999", "text": "Hi! Your order is on its way." }'

const response = await fetch('https://app.wappfy.io/api/v1/messages/text', {
  method: 'POST',
  headers: {
    'X-Api-Key': process.env.WAPPFY_API_KEY,
    'Content-Type': 'application/json',
    'Idempotency-Key': 'order-1234-confirmation',
  },
  body: JSON.stringify({ to: '5581999999999', text: 'Hi! Your order is on its way.' }),
})
const body = await response.json()
if (!response.ok) throw new Error(`${body.error.codigo}: ${body.error.mensagem}`)
console.log(body.data.message_id)

import os
import requests

response = requests.post(
    "https://app.wappfy.io/api/v1/messages/text",
    headers={
        "X-Api-Key": os.environ["WAPPFY_API_KEY"],
        "Idempotency-Key": "order-1234-confirmation",
    },
    json={"to": "5581999999999", "text": "Hi! Your order is on its way."},
    timeout=60,
)
body = response.json()
if not response.ok:
    raise RuntimeError(f"{body['error']['codigo']}: {body['error']['mensagem']}")
print(body["data"]["message_id"])

• to: the phone number with country code and area code, digits only. A chat ID (...@c.us, ...@lid, or a group ...@g.us) also works.
• Idempotency-Key: optional, but recommended. If your system repeats the same request with the same value within 24 hours, the API returns the first response without sending again. Use one value per message, such as your order id or workflow run id.

4. Read the responseCopy Anchor Link

{
  "data": {
    "message_id": "true_5581999999999@c.us_3EB0C767D26A1D5E",
    "chat_id": "5581999999999@c.us"
  }
}

• message_id: store it. The same id shows up in the message.sent and message.status webhooks, and you use it to react, reply quoting (reply_to), edit or delete the message.
• chat_id: where the message actually went. It can be an @lid address, the internal WhatsApp id of the contact.

If the number has no WhatsApp account, nothing is sent and you get:

{
  "error": {
    "codigo": "numero_sem_whatsapp",
    "mensagem": "Este numero nao tem conta no WhatsApp. Nada foi enviado."
  }
}

Decide by codigo. The mensagem is a human-readable explanation (currently in Portuguese) and may change. See Response format for the full list.

5. Receive events on a webhookCopy Anchor Link

Webhooks tell your system when a message arrives, when yours is delivered or read, and when the connection drops, so you don't have to poll the API.

Answer each delivery with any 2xx within 10 seconds, and verify the signature before trusting the body. The Webhooks guide explains both.

Next stepsCopy Anchor Link