Contact Created Event

Triggered when a new contact is discovered on your WhatsApp instance. This happens when you receive a message from a new number or when WhatsApp syncs contact information.

Event Type

contact-created

Payload Structure

{
  "event": "contact-created",
  "instanceId": "instance-uuid",
  "data": {
    "contact": {
      "id": "contact-uuid",
      "jid": "5511888888888@s.whatsapp.net",
      "lid": null,
      "name": "John Doe",
      "profilePictureUrl": "https://...",
      "isBusiness": false
    },
    "instanceId": "instance-uuid",
    "connectedNumber": "5511999999999",
    "timestamp": "2024-12-14T12:00:00.000Z"
  }
}

Data Fields

Field	Type	Description
contact	object	Contact information
instanceId	string	Instance ID
connectedNumber	string	Connected phone number
timestamp	string	ISO 8601 timestamp of the event

Contact Object

Field	Type	Description
id	string	Internal contact ID
jid	string | null	WhatsApp JID (phone@s.whatsapp.net)
lid	string | null	WhatsApp LID (local identifier)
name	string | null	Contact name (from WhatsApp or address book)
profilePictureUrl	string | null	Profile picture URL
isBusiness	boolean | undefined	Whether this is a WhatsApp Business account

Understanding JID and LID

WhatsApp uses two types of identifiers:

• LID (Local ID): The newer, primary identifier used by WhatsApp. LID is now the standard identifier and is prioritized in our system.
• JID (Jabber ID): The traditional WhatsApp identifier based on phone number (e.g., 5511999999999@s.whatsapp.net). May not always be available initially.

LID Priority

LID is now the primary identifier in ZapyAPI. When both identifiers are available, LID is used as the main reference. The phone number (JID) may be discovered later via WhatsApp's LID-to-PN mapping.

tip

When a contact has only a LID, the phone number may be revealed later when WhatsApp maps the LID to a phone number. This triggers a contact-updated event with the newly discovered JID.

Example: Syncing Contacts

app.post('/webhook', async (req, res) => {
  const { event, data } = req.body;
  
  if (event === 'contact-created') {
    const { contact, instanceId } = data;
    
    // Save to your database
    await db.contacts.create({
      externalId: contact.id,
      instanceId,
      phoneNumber: contact.jid?.replace('@s.whatsapp.net', ''),
      name: contact.name,
      profilePicture: contact.profilePictureUrl,
      isBusiness: contact.isBusiness || false
    });
    
    console.log(`New contact: ${contact.name || contact.jid}`);
  }
  
  res.status(200).send('OK');
});