Contacts and Chats

These routes are under the Contacts, Chats and Presence tags in the API Reference tab. They read what is on the number's WhatsApp right now.

ContactsCopy Anchor Link

Check a numberCopy Anchor Link

curl "https://app.wappfy.io/api/v1/contacts/check?phone=5581999999999" \
  -H "X-Api-Key: wpf_YOUR_KEY"

{
  "data": { "exists": true, "chat_id": "5581999999999@c.us", "phone": "5581999999999" }
}

• exists: false is an answer, not an error.
• chat_id is the address sends to this number will use (it can be @lid), or null when the number has no WhatsApp.
• For Brazilian numbers, both spellings of the ninth digit are checked, and phone comes back in the spelling WhatsApp confirmed.

Profile pictureCopy Anchor Link

GET /contacts/profile-picture?phone=5581999999999 returns url (a temporary WhatsApp link) and chat_id. url is null when the person has no picture or hides it.

List contactsCopy Anchor Link

curl "https://app.wappfy.io/api/v1/contacts?limit=100&offset=0" \
  -H "X-Api-Key: wpf_YOUR_KEY"

Each item has chat_id, phone (digits only, or null when WhatsApp didn't reveal the number), name (as saved on the phone), push_name (the name the person set on WhatsApp), is_my_contact and is_group. limit goes from 1 to 500 (default 100), and the order is stable between pages.

ChatsCopy Anchor Link

curl "https://app.wappfy.io/api/v1/chats?limit=20&offset=0" \
  -H "X-Api-Key: wpf_YOUR_KEY"

curl "https://app.wappfy.io/api/v1/chats/5581999999999@c.us/messages?limit=50&before=1791912000" \
  -H "X-Api-Key: wpf_YOUR_KEY"

{
  "data": [
    {
      "message_id": "false_5581999999999@c.us_3EB0C767D26A1D5E",
      "chat_id": "5581999999999@c.us",
      "from_me": false,
      "from": "5581999999999",
      "is_group": false,
      "type": "text",
      "text": "Is this one still available?",
      "has_media": false,
      "media": null,
      "reply_to": null,
      "status": null,
      "timestamp": 1791911879
    }
  ]
}

• A chat comes with chat_id, name, phone, is_group, picture_url and last_message (same format as a message, or null).
• {chatId} is a chat ID from GET /chats or a webhook, or a phone number with country code and area code.
• limit goes from 1 to 100 (default 20). For messages, before and after filter by time (Unix seconds, exclusive).
• status only appears on messages the number sent: pending, sent, delivered, read, played or failed.
• media has a Wappfy link when the file already came through the webhook. Otherwise has_media is true and media is null: these reads don't download files from WhatsApp.
• These reads can come from the 10-second cache (Age header). To follow new messages, use the message.received webhook instead of polling.

PresenceCopy Anchor Link

# subscribe to a contact's presence, then read it
curl -X POST https://app.wappfy.io/api/v1/chats/5581999999999/presence/subscribe \
  -H "X-Api-Key: wpf_YOUR_KEY"

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

{
  "data": {
    "chat_id": "5581999999999@c.us",
    "is_group": false,
    "presences": [{ "phone": "5581999999999", "presence": "online", "last_seen": null }]
  }
}

• A contact's presence only shows up after you subscribe, and only for people who share it. Before that, presences is empty. In a group, there is one entry per participant.
• presence is online, offline, typing, recording or paused.
• The presence read is never cached, but it counts toward the polling limit. To follow it, enable the presence webhook event instead (it is off by default).

To show "typing..." in a chat before replying, see Sending messages.