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": "[email protected]",
      "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 ([email protected])
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

• JID (Jabber ID): The traditional WhatsApp identifier based on phone number (e.g., [email protected])
• LID (Local ID): A newer identifier used by WhatsApp for privacy. Some contacts may only have a LID initially.

info

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.

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');
});